Conceptos básicos

​

Escenarios

• name — identificador del escenario
• seed - semilla RNG determinista (misma semilla = mismos resultados)
• ticks — número de pasos de simulación
• tickSeconds — tiempo simulado por tick (por ejemplo, 3600 = 1 hora)
• pack — adaptador de protocolo que configura el estado mundial
• agents — lista de tipos, recuentos y parámetros de agentes
• assertions — comprobaciones de validación posteriores a la ejecución
• gossip : definiciones de canales, presupuestos y configuraciones de confianza

import { defineScenario } from '@elata-biosciences/agentforge';

export default defineScenario({
  name: 'my-scenario',
  seed: 42,
  ticks: 200,
  tickSeconds: 3600,
  pack: myPack,
  agents: [
    { type: MyAgent, count: 10 },
  ],
  assertions: [
    { type: 'gt', metric: 'totalVolume', value: 0 },
  ],
});

​

Garrapatas

1. El motor llama al step(ctx) a cada agente en orden
2. Cada agente devuelve cero, una o hasta tres acciones.
3. El paquete ejecuta cada acción contra el estado del protocolo.
4. Se registran métricas, chismes y artefactos.

​

Agentes

export class MyAgent extends BaseAgent {
  async step(ctx: TickContext): Promise<Action | Action[] | null> {
    // Observe state, decide, and return actions
  }
}

​

Contexto del agente

​

Estado del agente

• this.remember(key, value) - almacenar un valor
• this.recall(key) — recuperar un valor almacenado
• this.setCooldown(name, ticks) — límite de velocidad de una acción
• this.isOnCooldown(name) — comprobar el estado de enfriamiento

​

Soporte de múltiples acciones

return [
  { id: this.generateActionId('swap', ctx.tick), name: 'swap', params: { ... } },
  { id: this.generateActionId('post', ctx.tick), name: 'PostMessage', params: { ... } },
];

​

Agentes personales de LLM

• Perfil de persona (identificación, estilo, objetivos, perfil de riesgo, preferencias de herramientas)
• Conjunto de avisos estructurado con contexto de manifiesto de capacidad total
• Bucle OODA de dos etapas: planifique y luego actúe, con respaldo al análisis de un solo disparo
• Intenciones de acción validadas por esquema a través de Zod

​

Paquetes

• setup() — implementar contratos, inicializar estado
• executeAction(action) — ejecutar la acción de un agente contra el protocolo
• getWorldState() : devuelve el estado actual del protocolo para que los agentes lo observen
• getCapabilityManifest() : describe los contratos, funciones y plantillas de acción disponibles

​

chismes

• Canales : canales de transmisión global o de estrategia específica con listas de miembros
• Mensajes de formato libre : cargas de texto con puntuaciones credibilityPrior opcionales (0-1)
• Presupuestos : configurables maxPostsPerTick y maxReadsPerTick por agente
• Enfriamientos - por canal postCooldownTicks para limitar la velocidad de publicación

gossip: {
  channels: [
    { id: 'global', members: 'all' },
    { id: 'strategy', members: ['LlmAgent-0', 'LlmAgent-1'] },
  ],
  budgets: { maxPostsPerTick: 3, maxReadsPerTick: 10 },
}

​

Determinismo

• CI reproducible : las afirmaciones se aprueban o fallan de manera consistente
• Repetir : vuelva a ejecutar los seguimientos de exploración de forma determinista frente a contratos actualizados
• Comparación - diferencia dos ejecuciones con forge-sim compare

forge-sim run --toy --seed 123 --out run1 --ci
forge-sim run --toy --seed 123 --out run2 --ci
forge-sim compare run1/toy-market-ci run2/toy-market-ci

​

Flujo de trabajo de exploración/reproducción

1. Explorar : ejecute con agentes LLM en modo de exploración para descubrir comportamientos
2. Captura — un replay_bundle.json registra el seguimiento de decisión completo
3. Repetir : vuelva a ejecutar exactamente el mismo seguimiento de forma determinista contra contratos actualizados

forge-sim run scenario.ts --mode exploration
forge-sim run scenario.ts --mode replay --replay-bundle results/run/replay_bundle.json