Swarm

Define AI agents as simple Python objects with static or callable instructions, a list of bound functions, and model configuration. Instructions can be static strings or dynamically generated via callables, enabling context-aware agent behavior without complex inheritance hierarchies. The Agent type (from swarm/types.py) is a minimal data structure that pairs instructions with executable functions, avoiding framework boilerplate while maintaining composability for agent switching.

Maintain and pass context variables (arbitrary Python dictionaries) through agent interactions and handoffs, allowing agents to read and modify shared state. The Swarm.run() method accepts initial context_variables, passes them to all agent functions as parameters, and returns updated context in the response. This enables agents to share information (e.g., user ID, conversation history, flags) without explicit message passing or global state, supporting clean agent-to-agent transitions.

Return structured Response objects from Swarm.run() containing the agent's message, updated context variables, and metadata about the execution (e.g., which agent responded, whether a handoff occurred). The Response type encapsulates all relevant information about an agent interaction, enabling applications to inspect and act on execution details beyond just the message text. This pattern supports debugging, logging, and conditional logic based on agent behavior.

Execute agent interactions synchronously using blocking calls to the OpenAI API, processing one message at a time and waiting for completion before returning. The Swarm.run() method is a blocking function that calls OpenAI's Chat Completions API, processes tool calls, and returns a Response object. This pattern is simple and suitable for single-threaded applications, but can block the event loop in async contexts if not carefully managed.

Bind Python functions to agents and automatically convert them to OpenAI function-calling schemas (JSON Schema format) for tool invocation. The framework introspects function signatures (using Python's inspect module) to extract parameter names, types, and docstrings, generating tool schemas without manual schema definition. When the LLM requests a tool call, Swarm automatically executes the bound function with the LLM-provided arguments and returns results back to the model, closing the tool-use loop.

Enable agents to transfer control to other agents mid-conversation by returning an Agent object from a function call. When an agent function returns an Agent instead of a string, Swarm switches to that agent, preserving the conversation history and context variables. This pattern supports hierarchical workflows (e.g., tier-1 support → tier-2 support → escalation) where agents can decide to hand off based on conversation state, without explicit routing logic in the application layer.

Stream agent responses token-by-token to the client using OpenAI's streaming API, enabling real-time feedback without waiting for full response completion. The Swarm.run() method supports a stream parameter that yields Response objects containing individual tokens as they arrive from the LLM. This pattern reduces perceived latency in user-facing applications and allows clients to display partial responses while the agent is still thinking, improving user experience in interactive systems.

Enable agents to invoke multiple tools in a single turn by setting parallel_tool_calls=True on the Agent configuration. When enabled, the LLM can request multiple tool calls in one response, and Swarm executes all of them concurrently (using Python's asyncio or threading) before returning results back to the model. This pattern reduces round-trips for independent operations (e.g., fetching user data and order history simultaneously) and improves overall agent efficiency.

Automatically maintain a conversation history (list of messages) across multiple Swarm.run() calls, accumulating user inputs and agent responses in a single thread. Each call to Swarm.run() appends new messages to the history, and subsequent calls include the full history when requesting completions from OpenAI. This enables multi-turn conversations where the LLM has context of previous exchanges, supporting coherent long-running interactions without explicit history management by the application.

Configure the OpenAI model used by each agent independently via the model parameter on the Agent type, enabling different agents to use different models (e.g., gpt-4 for complex reasoning, gpt-3.5-turbo for simple tasks). Swarm passes the agent's model to the OpenAI API when requesting completions, allowing fine-grained control over model selection without changing agent code. This pattern supports cost optimization (using cheaper models for simple tasks) and capability matching (using more capable models for complex reasoning).

Control how the LLM selects tools via the tool_choice parameter on the Agent type, supporting modes like 'auto' (LLM decides), 'required' (must call a tool), or specific tool names. This configuration is passed to OpenAI's function-calling API, enabling deterministic tool selection for workflows where certain tools must be called or where tool calling should be disabled. This pattern supports both flexible agent behavior (auto mode) and constrained workflows (required mode).

Provide utility functions (in swarm/util.py) that wrap Python functions to make them compatible with Swarm's tool system, handling schema generation, parameter validation, and error handling. These utilities abstract away the complexity of converting Python functions to OpenAI function-calling schemas, enabling developers to write simple functions and have Swarm handle the integration details. The utilities support both synchronous and asynchronous functions, enabling flexible tool implementations.