SID-2 Swarm
Making a request
Connect over WebSocket and start a run with one response.create event.
SID-2 Swarm is served over the WebSocket form of the OpenAI Responses API, with OpenAI's multi-agent beta header. Use the same SID API key and the same base URL as SID-2. Each swarm uses one WebSocket connection.
- Endpoint:
wss://api.sid-1.com/v1/responses - Beta header:
OpenAI-Beta: responses_multi_agent=v1 - Model ID:
SID-2-Swarm
Requires openai[realtime]>=2.45.0.
import asyncio
import os
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://api.sid-1.com/v1", api_key=os.environ["SID_API_KEY"])
MODEL = "SID-2-Swarm"
async def main():
async with client.beta.responses.connect(extra_headers={"OpenAI-Beta": "responses_multi_agent=v1"}) as conn:
await conn.send(REQUEST) # the response.create event below
...
asyncio.run(main())We recommend using the asynchronous OpenAI client to run tool execution concurrently.
The response.create event
Start the run with one response.create event. Its fields are those of a SID-2 request, plus a multi_agent object:
REQUEST = {
"type": "response.create",
"model": MODEL,
"input": QUESTION,
"instructions": INSTRUCTIONS, # SID appends the multi-agent protocol
"tools": TOOLS,
"max_output_tokens": 4096,
"sid": {"tool_examples": TOOL_EXAMPLES, "reward": REWARD},
"multi_agent": {
"enabled": True,
"max_agents": 6,
"agent_max_turns": 50,
"last_turn_message": LAST_TURN_MESSAGE,
},
}input: the question, as a string or as one user message with string content.instructions: your system prompt.tools: your search and read tools and the unchangedreport_helpful_ids, exactly as for SID-2. Don't add the multi-agent tools; SID adds them.max_output_tokens,sid.reward: as for SID-2.max_output_tokensapplies to each agent turn.reasoning: leave it out. Every agent turn runs at efforthigh, which is fixed;{"effort": "high"}is accepted, any other value is refused.sid.tool_examples: your examples as for SID-2, with the multi-agent examples inserted just before thereport_helpful_idsexample.multi_agent:enabled: must betrue.max_agents: the most agents the run may have, the root included. From 1 to 24; default 6. It also can't be more than your account's agent quota (12 by default; see Usage and pricing).agent_max_turns: each agent's turn budget; default 50. A forked agent's budget includes the turns its parent had already used when it forked.last_turn_message: the warning SID adds to an agent's input when it has one turn left. Send the text below.
The request is fixed for the life of the run and applies to every agent.
SID rejects a response.create with an error event and closes the socket when it:
- sets
multi_agent.max_concurrent_subagents(usemax_agents, which counts the root); - sets
previous_response_id,stream_id,stream,background,generate, orstore: false; - defines a tool named
fork,message_agents,waitorlist_agents, or one of OpenAI's multi-agent action names (spawn_agent,send_message,followup_task,wait_agent,interrupt_agent); - sets
reasoningto anything but{"effort": "high"}(reasoning_not_configurable); - has
instructionsthat already contain the multi-agent protocol (protocol_in_instructions); - names a model other than
SID-2-Swarmorsid-2-swarm(model_not_found).
Multi-agent tool examples
Insert these before your report_helpful_ids example in sid.tool_examples, so the examples run in the order of a run: search and read, then the multi-agent tools, then the report.
MULTI_AGENT_EXAMPLES = [
{
"caption": "Example — spawning parallel agents, one per name:",
"name": "fork",
"arguments": {"names": ["first-part", "second-part"]},
},
{
"caption": "Example — messaging another agent by name:",
"name": "message_agents",
"arguments": {"recipients": ["first-part"], "message": "placeholder_1 answers the first part; read it."},
},
{
"caption": "Example — listing the agents and their states:",
"name": "list_agents",
"arguments": {},
},
{
"caption": "Example — waiting for another agent's message:",
"name": "wait",
"arguments": {},
},
]
TOOL_EXAMPLES = [*SEARCH_AND_READ_EXAMPLES, *MULTI_AGENT_EXAMPLES, REPORT_EXAMPLE]The last-turn message
SID adds the turn budget to every agent's input itself, so unlike SID-2 you don't send it. Send this as multi_agent.last_turn_message; SID adds it when an agent has one turn left:
LAST_TURN_MESSAGE = (
"This is your last turn: you must call report_helpful_ids now (an empty list is allowed). "
"Anything you have found but not reported is lost when this turn ends."
)