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 unchanged report_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_tokens applies to each agent turn.
  • reasoning: leave it out. Every agent turn runs at effort high, 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 the report_helpful_ids example.
  • multi_agent:
    • enabled: must be true.
    • 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 (use max_agents, which counts the root);
  • sets previous_response_id, stream_id, stream, background, generate, or store: false;
  • defines a tool named fork, message_agents, wait or list_agents, or one of OpenAI's multi-agent action names (spawn_agent, send_message, followup_task, wait_agent, interrupt_agent);
  • sets reasoning to anything but {"effort": "high"} (reasoning_not_configurable);
  • has instructions that already contain the multi-agent protocol (protocol_in_instructions);
  • names a model other than SID-2-Swarm or sid-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."
)

Content