Expand description
The agent-definition endpoints: register a definition, list registered ones, and read one back.
§Why a server-side registry keyed by the definition hash
Under the single built-in loop an agent is pure data, and pure data has a
content hash: agent_def_hash, already recorded in every RunStarted
event. The control plane leans on that. A client submits a definition once
to POST /v1/agents; the server builds it (which validates it and computes
the hash), stores the raw definition under that hash, and returns the hash
as the agent’s id. Starting a run then references the agent by hash and
carries only the input, so the start payload stays tiny and the same
definition drives every start, resume, and recover without the client
resubmitting it.
The alternative, making the client pass the full definition on every start,
was declined: it would put the definition on the wire repeatedly, give the
server no stable id to talk about an agent by, and separate the id a run
records (agent_def_hash) from the id the API uses. Registering once and
referencing by the same hash the log already speaks keeps those aligned.
Registration is also the definition’s validation point: building the agent
spawns and immediately closes its MCP sessions, so a definition that cannot
build is rejected here with a 400 rather than failing later at the first
start.