Skip to main content

Recipe: snapshot an agent spec

# Idempotent — re-running with unchanged content returns the same
# spec_hash and the same version row.
curl -X POST http://localhost:8000/agents/specs `
    -H "Content-Type: application/json" `
    -d @configs/agents/my-agent.yaml

The response carries spec_hash and version. If you change a field and re-POST, a NEW agent_spec_versions row is created with a NEW hash. Old versions stay intact for replay.

What the runtime does​

The AgentRuntime (lives in the alphaswarm_agents sibling repo) gates every run on:

  • A valid agent_spec_versions row.
  • A cost cap (AgentSpec.max_cost_usd, AgentSpec.max_calls).
  • The active kill switch.
  • The RFC 9728 + 8707 MCP audience check (rule 49).
  • An experiment_id (rule 34).

If any check fails, the run rejects before the first LLM call.

Run the agent​

curl -X POST http://localhost:8000/agents/runs/v2/sync `
    -d '{"spec_name":"<spec_name>","inputs":{"universe":["SPY","QQQ","IWM"]}}'

AgentRuntime writes agent_runs_v2 rows with telemetry, cost, and OTEL trace IDs.

Don't bypass the runtime​

Never call router_complete directly from inside agent code. Declare the model in AgentSpec.model and let the runtime drive the call. See AGENTS rule 12.

Deeper reads​