> ## Documentation Index > Fetch the complete documentation index at: https://docs.usesynth.ai/llms.txt > Use this file to discover all available pages before exploring further. # swarms # `synth_ai.research.swarms` Alpha `client.research.swarms` — launch and lifecycle for Managed Swarms. A Managed Swarm is one bounded multi-agent execution under the Managed Research (SMR) umbrella. Swarms launch directly against a project, or are composed by Managed Factories through Efforts. The wire protocol still uses `run`/`run_id`; this module is the public noun layer over it. ## Functions ### `swarm_state_is_terminal` ```python theme={null} swarm_state_is_terminal(state: str) -> bool ``` Return whether a public swarm state string is terminal. Reuses :class:`RunState` (the same terminal-state source the low-level wait/contract path is projected from) instead of hand-authoring a string set. Unknown states are non-terminal. ### `classify_event_kind` ```python theme={null} classify_event_kind(kind: str) -> str ``` Classify a wire event `kind` into a coarse forward-compatible category. Returns one of `"tool"`, `"message"`, `"turn"`, `"usage"`, `"status"`, or `"other"`. Unknown kinds always classify as `"other"` so new backend event kinds never break consumers. ## Classes ### `SwarmPreflightBlockedError` Raised when `launch_and_wait` preflight is not clear to trigger. Carries the structured `blockers` list and the full preflight payload so callers can act on the class of denial rather than a bare message. ### `SwarmLaunchBackpressureError` Raised when swarm launch exhausts its bounded backpressure retries. ### `SwarmResult` Typed outcome of :meth:`ResearchSwarmsAPI.launch_and_wait`. **Methods:** #### `is_terminal` ```python theme={null} is_terminal(self) -> bool ``` ### `SwarmRetryResult` Typed outcome of :meth:`ResearchSwarmHandle.retry`. Provenance (which swarm this retry came from and why) lives here client-side; the launch wire has no metadata field to carry it. ### `ResearchSwarmHandle` Swarm-scoped readouts and lifecycle (public hero session type). A Managed Swarm is one bounded multi-agent execution. Prefer `ResearchSwarmSession` in type hints — `RunHandle` is not part of the public hero surface. **Methods:** #### `swarm_id` ```python theme={null} swarm_id(self) -> str ``` Public swarm identifier (wire transport still calls this `run_id`). #### `wait_until_terminal` ```python theme={null} wait_until_terminal(self, timeout: float, poll_interval: float = 10.0) -> ResearchSwarm ``` Block until the swarm reaches a terminal state (thin over `wait`). **Args:** * `timeout`: Max seconds to wait; the operator owns the wall clock. * `poll_interval`: Seconds between status polls. **Returns:** * class:`ResearchSwarm` public state model. #### `is_terminal` ```python theme={null} is_terminal(self) -> bool ``` Return whether the swarm has reached a terminal state. Uses the backend run contract's `terminal` flag — the same authority the low-level wait loop polls. #### `retry` ```python theme={null} retry(self, mode: Literal['from_checkpoint', 'fresh'] = 'fresh') -> SwarmRetryResult ``` Retry a terminal swarm, either fresh or branched from a checkpoint. **Args:** * `mode`: `"fresh"` re-launches the project's configured swarm; `"from_checkpoint"` branches from an existing checkpoint. * `reason`: Optional operator reason, recorded client-side on the result (and on the branch request for checkpoint retries). * `checkpoint_id`: Required when `mode="from_checkpoint"`. **Returns:** * class:`SwarmRetryResult` with the new swarm id and handle. **Raises:** * `ValueError`: If the source swarm is not terminal, or the mode / checkpoint arguments are inconsistent. #### `progress_snapshot` ```python theme={null} progress_snapshot(self) -> Any ``` Deprecated alias for `snapshots.get(detail=...)`. #### `full_progress` ```python theme={null} full_progress(self) -> RunObservabilitySnapshot ``` Return the full observability snapshot (deprecated path — use `snapshots.get(detail='full')`). #### `stream_transcript` ```python theme={null} stream_transcript(self) -> Iterator[dict[str, Any]] ``` Stream transcript event pages for the swarm. #### `work_product_content` ```python theme={null} work_product_content(self, work_product_id: str) -> str | bytes ``` Download work product bytes or text by id. #### `download_workspace_archive` ```python theme={null} download_workspace_archive(self, destination: str) -> dict[str, Any] ``` Deprecated alias for `workspace.download`. #### `list_artifacts` ```python theme={null} list_artifacts(self) -> List[dict[str, Any]] ``` Deprecated alias for `artifacts.list`. ### `ResearchSwarmsAPI` Public Managed Swarm methods (alpha must-have). **Methods:** #### `runbook_presets` ```python theme={null} runbook_presets(self) -> tuple[ResearchRunbookPreset, ...] ``` Return supported runbook presets for `swarms.create`. #### `check_preflight` ```python theme={null} check_preflight(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any] ``` Validate a launch request before starting a swarm. Call after `projects.setup.prepare` to surface blockers (missing repo, secrets, budget caps) without creating a swarm record. **Returns:** * Preflight payload with `allowed` flag and structured denials. #### `launch_and_wait` ```python theme={null} launch_and_wait(self, project_id: str | None = None, **launch_kwargs: Any) -> SwarmResult ``` Preflight, launch, and wait for a swarm in one call (hero flow). Runs `check_preflight` first and fails immediately with a typed :class:`SwarmPreflightBlockedError` when not clear to trigger. Launch is wrapped in a bounded backpressure retry (HTTP 502/503/504 and concurrent-run-limit backpressure, max 5 attempts, capped backoff); other errors raise immediately. Then blocks until terminal and assembles a typed :class:`SwarmResult`. **Args:** * `project_id`: Owning project id. * `objective`: Primary operator message (objective launch path). When omitted, the project's configured swarm is triggered. * `timeout`: REQUIRED max seconds to wait for terminal state — the operator owns the wall clock; there is no wait-forever default. * `poll_interval`: Seconds between status polls. * `raise_if_failed`: Raise when the swarm ends failed/blocked. * `**launch_kwargs`: Any launch-request field the backend accepts (`execution_target`, `local_execution`, `limit`, ...). **Returns:** * class:`SwarmResult` with final state, usage, cost, work products, * and a live handle for further readouts. #### `launch_preflight` ```python theme={null} launch_preflight(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any] ``` Deprecated alias for `check_preflight`. #### `create` ```python theme={null} create(self, project_id: str | None = None, **kwargs: Any) -> ResearchSwarmHandle | dict[str, Any] ``` Launch a Managed Swarm. When `objective` is provided, returns a :class:`ResearchSwarmHandle`. Objective-less calls retain their historical raw response. Use :meth:`create_configured` for a typed configured-swarm launch. **Args:** * `project_id`: Owning project id. * `objective`: Primary operator message for the swarm (preferred launch path). **Returns:** * A typed handle for objective launches, otherwise the legacy raw payload. #### `create_configured` ```python theme={null} create_configured(self, project_id: str | None = None, **kwargs: Any) -> ResearchSwarmHandle ``` Launch the project's configured swarm and return a typed handle. #### `start` ```python theme={null} start(self, objective: str, **kwargs: Any) -> ResearchSwarmHandle ``` Start a swarm with a primary objective message (deprecated — use `create`). #### `launch` ```python theme={null} launch(self, objective: str, **kwargs: Any) -> ResearchSwarmHandle ``` Deprecated alias for `create` with a required objective. #### `trigger` ```python theme={null} trigger(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any] ``` Compatibility alias for existing ReportBench drivers. #### `start_run` ```python theme={null} start_run(self, project_id: str | None = None, **kwargs: Any) -> dict[str, Any] ``` Deprecated alias for configured-swarm launch (prefer `create`). #### `get` ```python theme={null} get(self, *args: str) -> ResearchSwarmHandle ``` Open a swarm-scoped session handle for readouts and lifecycle control. Accepts `(project_id, swarm_id)`, `(swarm_id,)` when project is implied, or keyword forms. Prefer nested readouts on the returned handle: `handle.usage.get()`, `handle.snapshots.get()`, `handle.transcript.get()`. #### `open` ```python theme={null} open(self, *args: str) -> ResearchSwarmHandle ``` Open a swarm session (alias for `get`). #### `state` ```python theme={null} state(self, swarm_id: str) -> ResearchSwarm ``` Return the public swarm state model without opening a full session handle. #### `public_state` ```python theme={null} public_state(self, swarm_id: str) -> ResearchSwarm ``` Return the public swarm state model without opening a full session handle. #### `list` ```python theme={null} list(self, project_id: str, **kwargs: Any) -> List[dict[str, Any]] ``` List swarms for a project (newest first). #### `list_active` ```python theme={null} list_active(self, project_id: str, **kwargs: Any) -> List[dict[str, Any]] ``` Return active swarms for a project (eval-compat name). #### `wait` ```python theme={null} wait(self, project_id: str | None = None, swarm_id: str | None = None) -> ResearchSwarm ``` Block until a swarm reaches a terminal state. **Args:** * `timeout`: Max seconds to wait (`None` waits indefinitely). * `poll_interval`: Seconds between status polls. * `raise_if_failed`: Raise when the swarm ends in a failed state. **Returns:** * Final `ResearchSwarm` public state model. #### `transcript` ```python theme={null} transcript(self, swarm_id: str) -> dict[str, Any] ``` Fetch a transcript page for a swarm (prefer `handle.transcript.get`). #### `stream_events` ```python theme={null} stream_events(self, swarm_id: str) -> Iterator[RunRuntimeStreamEvent] ``` Stream runtime events for a swarm (prefer `handle.events.stream`). #### `resource_limits` ```python theme={null} resource_limits(self, swarm_id: str) -> SmrResourceLimits ``` Return configured resource limits for the swarm. #### `progress_toward_resource_limits` ```python theme={null} progress_toward_resource_limits(self, swarm_id: str) -> SmrResourceLimitProgress ``` Return progress toward resource limits for the swarm. #### `stop` ```python theme={null} stop(self, swarm_id: str) -> ManagedResearchRunControlAck ``` Request graceful stop for a swarm. #### `pause` ```python theme={null} pause(self, swarm_id: str) -> ManagedResearchRunControlAck ``` Pause an active swarm. #### `resume` ```python theme={null} resume(self, swarm_id: str) -> ManagedResearchRunControlAck ``` Resume a paused swarm. #### `results` ```python theme={null} results(self, project_id: str, swarm_id: str) -> dict[str, Any] ``` Return final swarm results when execution completes. #### `logs` ```python theme={null} logs(self, project_id: str, swarm_id: str) -> dict[str, Any] ``` List structured log records for a swarm. #### `logs_page` ```python theme={null} logs_page(self, project_id: str, swarm_id: str) -> SyncPage[dict[str, Any]] ``` Fetch a paginated page of swarm logs. **Returns:** * `SyncPage` with `items`, `next_cursor`, and `has_more` for * cursor-based iteration without hand-parsing wire payloads. #### `execution` ```python theme={null} execution(self, project_id: str, swarm_id: str, **kwargs: Any) -> Any ``` Return orchestrator execution metadata for a swarm. #### `orchestrator` ```python theme={null} orchestrator(self, project_id: str, swarm_id: str) -> dict[str, Any] ``` Return orchestrator state for a swarm (actors, phases, checkpoints).