SID-2 Swarm
Reference implementation
A runnable SID-2 Swarm client in Python that answers tool calls concurrently.
The reference implementation runs one swarm run against the first-party SID API. Your backend returns documents or chunks, the SDK renders snippets for each agent, and the agents' reports are fused at the end. It is Python only for now.
Download reference_implementation_swarm.pySID_API_KEY=your-api-key uv run --with sid-sdk --with 'openai[realtime]>=2.45.0' reference_implementation_swarm.pypip install sid-sdk 'openai[realtime]>=2.45.0'
SID_API_KEY=your-api-key python reference_implementation_swarm.pyThe tools (fetch_results, render_results, read, report) are the same as in the SID-2 reference implementation; only the cache they use is now per agent, and the backend calls are async. Each tool call runs as its own task: searches from every agent run at the same time, while each agent's results are rendered in the order its calls arrived. Reconnecting is left out for brevity; see Reconnecting.
"""SID-2 Swarm preview.Before using this template: implement the vector_search and keyword_search backendfunctions, set ID_FIELD and SNIPPET_FIELD to your document's fields, and customizeINSTRUCTIONS, QUESTION and TOOL_EXAMPLES to fit your data. Keep MULTI_AGENT_EXAMPLESand LAST_TURN_MESSAGE as they are. The report_helpful_ids tool is fixed and cannot bechanged or modified. SID adds the multi-agent protocol to the instructions and runsevery turn at reasoning effort high; don't send either.Tool calls are answered concurrently: each one runs as its own asyncio task, thebackend searches of every agent overlap, and each output is injected as soon as it isready. Rendering into an agent's DocumentCache still follows the order of that agent'scalls (the seen-ledger is stateful).Run: SID_API_KEY=your-api-key uv run --with sid-sdk --with 'openai[realtime]>=2.45.0' reference_implementation_swarm.py"""import asyncioimport jsonimport osimport timefrom openai import AsyncOpenAIfrom sid import DocumentCache, InvalidCharacterRange, parse_rendered_model_facing_idfrom sid.document_cache import SNIPPET_SIZE_DEFAULTclass ToolError(Exception): """A mistake the *model* made (bad id, malformed ref, invalid arguments); recoverable, and passed back to the model as the tool's output."""# ---------------------------------------------------------------------------# The run. TODO: your question.# ---------------------------------------------------------------------------QUESTION = "What government position was held by the woman who portrayed Corliss Archer in the film Kiss and Tell?"BASE_URL = os.environ.get("SID_BASE_URL", "https://api.sid-1.com/v1")MODEL = "SID-2-Swarm" # or "sid-2-swarm"MAX_AGENTS = 6 # agents in the run, the root included (at most 24)AGENT_MAX_TURNS = 50 # each agent's turn budget (the default)REWARD = "ndcg"DEFAULT_LIMIT = 5FUSED_RESULTS = 10 # how many fused ids to keep# ---------------------------------------------------------------------------# TODO: your search backend, as in the SID-2 reference implementation, as# async functions so that many agents can search at once.# ---------------------------------------------------------------------------ID_FIELD = "id"SNIPPET_FIELD = "content"async def vector_search(query: str, limit: int) -> list[dict]: """TODO: your semantic (embedding) search: the ``limit`` most relevant documents for ``query``, best first.""" raise NotImplementedError("implement vector_search against your document store")async def keyword_search(query: str, limit: int) -> list[dict]: """TODO: your full-text keyword (BM25) search.""" raise NotImplementedError("implement keyword_search against your document store")# ---------------------------------------------------------------------------# The prompt: your system prompt. SID appends the multi-agent protocol# (with MAX_AGENTS and AGENT_MAX_TURNS filled in), so don't add it here.# ---------------------------------------------------------------------------INSTRUCTIONS = """You are an expert research assistant that is given a question and must use the provided search tools to find all documents needed to answer the question.Steps:1. Reflect on what information is needed to answer the question and use the search tools to find documents. Each document has an id.2. Repeat step 1 until all documents necessary and sufficient to answer the question have been found. Take as many turns and searches as needed – you can make multiple searches per turn! Most questions will require multiple turns. Many will need more.3. Use the report_helpful_ids tool to report the most helpful document ids. List the most helpful document ids first (important!).The episode ends once report_helpful_ids is called."""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.")# ---------------------------------------------------------------------------# The tool schemas: the SID-2 schemas, unchanged. Each tool should be# demonstrated in TOOL_EXAMPLES. Don't define the multi-agent tools; SID adds them.# ---------------------------------------------------------------------------SNIPPET_SIZE_DESCRIPTION = ( f"Words shown per result snippet (default {SNIPPET_SIZE_DEFAULT}). Must be a positive integer. " f"Pass a larger value to see more of each document.")SEARCH_TOOL = { "type": "function", "name": "search", "description": ( "Semantic (vector) search over the dataset. Best for conceptual or paraphrased " "queries: a long, descriptive query of what you want beats a few keywords; use " "text_search when you know the distinctive words a match would contain. Result " "ids may be ranged references 'id#start:end' naming the exact character span of " "the document shown; stretches you have already been shown are replaced by " "'[seen: \"#start:end\"]' markers instead of repeating, and doc_length gives the " "document's total character count." ), "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "The query to search the dataset with"}, "limit": {"type": "integer", "description": "The number of results to return"}, "snippet_size": {"type": "integer", "description": SNIPPET_SIZE_DESCRIPTION}, }, "required": ["query"], },}TEXT_SEARCH_TOOL = { "type": "function", "name": "text_search", "description": ( "Full-text keyword search over the dataset, ranked by BM25. Provide the terms you " "want matched as plain words separated by spaces: the distinctive content words a " "matching document would contain. Result ids may be ranged references 'id#start:end' naming the exact " "character span of the document shown; stretches you have already been shown are " "replaced by '[seen: \"#start:end\"]' markers instead of repeating, and doc_length " "gives the document's total character count." ), "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": ( "Plain space-separated content words to match (BM25)." ), }, "limit": {"type": "integer", "description": "The number of results to return"}, "snippet_size": {"type": "integer", "description": SNIPPET_SIZE_DESCRIPTION}, }, "required": ["query"], },}READ_TOOL = { "type": "function", "name": "read", "description": "Search results show only short snippets. Read up to 10,000 characters of a document per call. A bare ID starts at character 0; a ranged reference starts at its requested offset. Use further ranged reads to continue.", "parameters": { "type": "object", "properties": { "id": { "type": "string", "description": ( "The id of the document to read. Also accepts a ranged reference " "'id#start:end' (character offsets, e.g. '123456#800:1600') to read only " "that part of the document's text; a range running past the end of the " "document is trimmed to the part that overlaps it." ), }, }, "required": ["id"], },}# The fixed terminal tool: do not change its name, description or parameters.REPORT_TOOL = { "type": "function", "name": "report_helpful_ids", "description": ( "Report the most helpful document ids from the search results. This is required in " "the last step. Each id may be reported at most once; repeated ids are penalized. " "Ids may be whole documents ('123456') or ranged references ('123456#800:1600'); a " "ranged reference counts as its whole document, so there is no need to strip the " "'#start:end' part." ), "parameters": { "type": "object", "properties": { "ids": { "type": "array", "description": "The ids of the most helpful documents from the search results.", "items": {"type": "string"}, }, }, "required": ["ids"], },}TOOLS = [SEARCH_TOOL, TEXT_SEARCH_TOOL, READ_TOOL, REPORT_TOOL]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": {}},]# Search and read examples first, then the multi-agent examples, then the report.TOOL_EXAMPLES = [ { "caption": "Example: a semantic search with a long, descriptive query:", "name": "search", "arguments": { "query": "the actress who played Corliss Archer in the 1945 film, and the government post she later held", "limit": 5, }, }, { "caption": "Example: a keyword search:", "name": "text_search", "arguments": {"query": "Kiss and Tell 1945 Shirley Temple Corliss Archer", "limit": 5}, }, {"caption": "Example: reading one character range:", "name": "read", "arguments": {"id": "placeholder_1#800:1600"}}, *MULTI_AGENT_EXAMPLES, { "caption": "Example: ending the episode with a report:", "name": "report_helpful_ids", "arguments": {"ids": ["placeholder_1", "placeholder_2", "placeholder_3"]}, },]# ---------------------------------------------------------------------------# The tool implementations, from the SID-2 reference implementation, taking the# calling agent's cache.# ---------------------------------------------------------------------------async def fetch_results(name: str, arguments: dict) -> tuple[str, int, list[dict]]: """Validate a search call and run it against the backend. Touches no cache, so calls from any agent can run at the same time.""" query = arguments.get("query", "") if not isinstance(query, str) or not query: raise ToolError("search requires a non-empty `query`. To fetch a document by id, use the `read` tool.") limit = arguments.get("limit", DEFAULT_LIMIT) snippet_size = arguments.get("snippet_size", SNIPPET_SIZE_DEFAULT) if not isinstance(limit, int) or not isinstance(snippet_size, int) or snippet_size <= 0: raise ToolError(f"Invalid {name} arguments: limit and snippet_size must be positive integers") results = await (vector_search(query, limit) if name == "search" else keyword_search(query, limit)) return query, snippet_size, resultsdef render_results(cache: DocumentCache, query: str, snippet_size: int, results: list[dict]) -> str: """Render fetched results against the calling agent's cache, updating its seen-ledger.""" rendered = [] for result in results: document = dict(result) data_id = document.pop(ID_FIELD) if data_id not in cache: cache.add_document(data_id, document) view = cache.apply_snippet(data_id, SNIPPET_FIELD, query, snippet_size=snippet_size) rendered.append(view.render_xml()) cache.update_seen(view) return "\n".join(rendered) if rendered else "No results found. Try a different query."def parse_reference(reference) -> tuple[str, tuple[int, int] | None]: try: return parse_rendered_model_facing_id(reference) except ValueError as error: raise ToolError(str(error)) from Nonedef read(cache: DocumentCache, reference) -> str: model_facing_id, char_range = parse_reference(reference) # The ids are shared across agents: this also reads documents another agent found. if not cache.contains_model_facing_id(model_facing_id): raise ToolError( f"Invalid document id '{model_facing_id}'. You can only read documents returned by search. " f"Use 'search' or 'text_search' first." ) data_id = cache.to_data_id(model_facing_id) if char_range is not None: try: char_range = cache.resolve_char_range(data_id, SNIPPET_FIELD, char_range) except InvalidCharacterRange as error: raise ToolError(f"{error}. Re-read '{model_facing_id}' without a range.") from None start, end = char_range char_range = (start, min(end, start + 10_000)) elif len(cache.get_document(data_id)[SNIPPET_FIELD]) > 10_000: char_range = (0, 10_000) view = cache.get_single_span_document_view(data_id, SNIPPET_FIELD, snippet_display_span=char_range) rendered = view.render_xml() cache.update_seen(view) return rendereddef report(cache: DocumentCache, ids) -> list[str]: """Deduplicated, translated to your data ids; ids outside the map are dropped.""" if not isinstance(ids, list) or not all(isinstance(reference, str) for reference in ids): raise ToolError("ids must be a list of strings") reported: list[str] = [] for reference in ids: model_facing_id, _ = parse_reference(reference) if model_facing_id not in reported: reported.append(model_facing_id) return [cache.to_data_id(m) for m in reported if cache.contains_model_facing_id(m)]def reciprocal_rank_fusion(rankings: list[list[str]], k: int = 60) -> list[str]: scores: dict[str, float] = {} for ranking in rankings: for rank, doc_id in enumerate(ranking): scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (k + rank + 1) return sorted(scores, key=scores.get, reverse=True)# ---------------------------------------------------------------------------# The run: one request, then a loop over the server's events. SID runs every# agent's turns; this loop answers tool calls, forks caches and ends agents.# Each tool call runs as its own task: backend searches from every agent (and the# several calls of one turn) run at the same time, while rendering into an agent's# cache keeps the order its calls arrived in, because the seen-ledger is stateful.# ---------------------------------------------------------------------------class Run: def __init__(self, conn): self.conn = conn self.response_id: str | None = None self.caches = {"/root": DocumentCache(range_mode="lenient")} # one per agent path self.reports: dict[str, list[str]] = {} # agent path -> its ranking, in your data ids self.calls = 0 self.tasks: set[asyncio.Task] = set() self.rendered: dict[str, asyncio.Future] = {} # agent path -> its latest call's render self.failed: asyncio.Future = asyncio.get_running_loop().create_future() self._send_lock = asyncio.Lock() async def send(self, message: dict) -> None: async with self._send_lock: # one frame at a time on the shared socket await self.conn.send(message) def answer_later(self, agent: str, item: dict) -> None: # Chain this call's render behind the agent's previous call, in arrival order. previous = self.rendered.get(agent) rendered = asyncio.get_running_loop().create_future() self.rendered[agent] = rendered task = asyncio.create_task(self.answer(agent, item, previous, rendered)) self.tasks.add(task) task.add_done_callback(self.tasks.discard) async def answer(self, agent: str, item: dict, previous: asyncio.Future | None, rendered: asyncio.Future) -> None: """Run one tool call and inject its output. A ToolError goes back to the model; anything else (the search backend down, a bug) fails the run.""" try: name = item["name"] output = {"type": "function_call_output", "call_id": item["call_id"]} try: arguments = json.loads(item.get("arguments") or "{}") fetched = error = None if name in ("search", "text_search"): try: fetched = await fetch_results(name, arguments) # concurrent with other calls except ToolError as e: error = e if previous is not None: await previous # this agent's earlier calls render first cache = self.caches[agent] try: if error is not None: raise error if name == "report_helpful_ids": self.reports[agent] = report(cache, arguments.get("ids")) output["end_agent"] = True # a valid report ends this agent print(f"{agent} reported {len(self.reports[agent])} ids") elif name == "read": output["output"] = read(cache, arguments.get("id")) else: output["output"] = render_results(cache, *fetched) except ToolError as e: output["output"] = str(e) # the agent continues and can try again finally: if not rendered.done(): rendered.set_result(None) self.calls += 1 if "output" in output: print(f" {agent} {name}({item.get('arguments')}) -> {len(output['output'])} chars") await self.send({"type": "response.inject", "response_id": self.response_id, "input": [output]}) except Exception as e: if not self.failed.done(): self.failed.set_exception(e) async def next_event(self) -> dict: """The next server event, or the first tool failure, whichever comes first.""" receive = asyncio.ensure_future(self.conn.recv_bytes()) await asyncio.wait({receive, self.failed}, return_when=asyncio.FIRST_COMPLETED) if self.failed.done(): receive.cancel() self.failed.result() # raises the tool's exception return json.loads(receive.result())async def main() -> None: client = AsyncOpenAI(base_url=BASE_URL, api_key=os.environ["SID_API_KEY"]) async with client.beta.responses.connect(extra_headers={"OpenAI-Beta": "responses_multi_agent=v1"}) as conn: run = Run(conn) await run.send({ "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": MAX_AGENTS, "agent_max_turns": AGENT_MAX_TURNS, "last_turn_message": LAST_TURN_MESSAGE, }, }) print(f"Q: {QUESTION}") started = time.perf_counter() try: while True: event = await run.next_event() kind = event["type"] agent = (event.get("agent") or {}).get("agent_name") item = event.get("item") or {} if kind == "response.created": run.response_id = event["response"]["id"] print(f"run {run.response_id}; rate limits: {event.get('rate_limits')}") elif kind == "response.output_item.done" and item.get("type") == "function_call": run.answer_later(agent, item) elif kind == "response.output_item.done" and item.get("type") == "multi_agent_call": if item.get("action") != "spawn_agent": print(f" {agent} {item.get('action')}({item.get('arguments')})") elif kind == "response.output_item.done" and item.get("type") == "multi_agent_call_output": # A fork: give each new agent a fork of its parent's cache. The parent's # earlier calls were all answered before it could fork. children = json.loads(item["output"][0]["text"])["agents"] for path, child in zip(children, run.caches[agent].fork(len(children)), strict=True): run.caches[path] = child print(f"{agent} forked {children}") elif kind == "response.inject.failed": print(f"inject failed: {event['error']}") elif kind == "response.agent.ended": print(f"{agent} ended: {event['reason']}") elif kind == "response.completed": agents = event["response"].get("agents", []) print(f"completed in {time.perf_counter() - started:.1f}s: {len(agents)} agents, {run.calls} tool calls") break elif kind in ("response.failed", "error"): raise RuntimeError(f"run failed: {event.get('response', {}).get('error') or event.get('error')}") finally: for task in run.tasks: # calls left over when the run ended or failed task.cancel() # Empty reports abstain; fuse the rest. fused = reciprocal_rank_fusion([ranking for ranking in run.reports.values() if ranking]) print("Fused ranking:", fused[:FUSED_RESULTS])if __name__ == "__main__": try: asyncio.run(main()) except Exception as error: # A refused WebSocket handshake hides the server's reason; print it. response = getattr(error, "response", None) if response is not None and getattr(response, "body", None): raise SystemExit(f"connection refused (HTTP {response.status_code}): {response.body.decode()}") from error raise