SID-2 Swarm

Events

The JSON events the server sends during a run: lifecycle, tool calls, multi-agent calls and inject acknowledgements.

The server sends JSON events on the socket. Every event carries an increasing sequence_number. Events that belong to an agent also carry agent.agent_name, the agent's path: /root for the root, /root/composer for an agent the root forked, /root/composer/dates for one that composer forked. Agent names are unique within a run.

Lifecycle

  • response.created: the run has started. response.id is the run's ID; keep it for injects and reconnecting.
{"type": "response.created", "sequence_number": 0,
 "response": {"id": "resp_...", "object": "response", "status": "in_progress", "model": "sid-2-swarm"}}
  • response.agent.ended: an agent has finished. reason is ended_by_client (you ended it, usually on its report), max_turns (its turn budget ran out) or truncated (a turn hit max_output_tokens or the context limit).
  • response.completed: every agent has ended. response.agents lists each agent and how it ended. The reports themselves are the report_helpful_ids calls you already received.
{"type": "response.completed", "sequence_number": 103,
 "response": {"id": "resp_...", "object": "response", "status": "completed", "model": "sid-2-swarm",
              "agents": [{"agent_name": "/root", "ended": "ended_by_client"},
                         {"agent_name": "/root/composer", "ended": "ended_by_client"}]}}
  • response.failed: the run ended early. response.error.code says why; run_abandoned means the run made no progress for 30 minutes, for example because a tool call was never answered.

Tool calls

response.output_item.done with a function_call item is a call to one of your tools. It is a standard Responses function_call item with the agent added. arguments is a JSON string.

{"type": "response.output_item.done", "sequence_number": 7,
 "agent": {"agent_name": "/root/composer"},
 "item": {"type": "function_call", "id": "fc_...", "call_id": "call_...", "name": "search",
          "arguments": "{\"query\": \"composer of The Bartered Bride\", \"limit\": 5}",
          "agent": {"agent_name": "/root/composer"}}}

An agent's calls arrive in the order the agent made them. Calls to a tool that isn't in your tools are dropped before they reach you.

Multi-agent calls

response.output_item.done with a multi_agent_call item reports a multi-agent tool the model used. SID has already handled it: don't answer it.

actionThe model calledarguments
spawn_agentfork{"names": [...]}
send_messagemessage_agents{"recipients": [...], "message": "..."}
wait_agentwait{}
list_agentslist_agents{}

A successful fork is followed by a multi_agent_call_output item with the same call_id. Its text lists the new agents' paths, in order:

{"type": "response.output_item.done", "sequence_number": 4,
 "agent": {"agent_name": "/root"},
 "item": {"type": "multi_agent_call_output", "call_id": "call_...", "agent": {"agent_name": "/root"},
          "output": [{"type": "output_text", "text": "{\"agents\": [\"/root/composer\", \"/root/town\"]}"}]}}

A fork can create fewer agents than the model asked for: the run never holds more than max_agents. If a fork creates none (for example a name is already taken), there is no output item.

Inject acknowledgements and errors

  • response.inject.created: your response.inject was accepted.
  • response.inject.failed: it was refused; error.code says why, for example inject_rejected for a call that is unknown or already answered. input returns the items that were not applied.
  • error: a message the server couldn't accept, with status and error.code, error.message and sometimes error.param. An invalid response.create gets an error and the socket closes.

Content