OpenAI Agents Python

https://openai.github.io/openai-agents-python
Admin
The OpenAI Agents SDK enables building agentic AI apps with lightweight primitives like Agents,...
Tokens:938,457
Snippets:5,559
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Complete voice pipeline example

Source: https://openai.github.io/openai-agents-python/voice/quickstart

Full example combining agent setup, pipeline creation, and running with audio input and playback. Run with asyncio.run(main()).

```python
import asyncio
import random

import numpy as np
import sounddevice as sd

from agents import Agent
from agents.decorators import tool
from agents.voice import (
    AudioInput,
    SingleAgentVoiceWorkflow,
    VoicePipeline,
)
from agents.extensions.handoff_prompt import prompt_with_handoff_instructions


@tool
def get_weather(city: str) -> str:
    """Get the weather for a given city."""
    print(f"[debug] get_weather called with city: {city}")
    choices = ["sunny", "cloudy", "rainy", "snowy"]
    return f"The weather in {city} is {random.choice(choices)}."


spanish_agent = Agent(
    name="Spanish",
    handoff_description="A Spanish-speaking agent.",
    instructions=prompt_with_handoff_instructions(
        "You're speaking to a human, so be polite and concise. Speak in Spanish.",
    ),
    model="gpt-5.6-sol",
)

agent = Agent(
    name="Assistant",
    instructions=prompt_with_handoff_instructions(
        "You're speaking to a human, so be polite and concise. If the user speaks in Spanish, hand off to the Spanish agent.",
    ),
    model="gpt-5.6-sol",
    handoffs=[spanish_agent],
    tools=[get_weather],
)


async def main():
    pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
    buffer = np.zeros(24000 * 3, dtype=np.int16)
    audio_input = AudioInput(buffer=buffer)

    result = await pipeline.run(audio_input)

    # Create an audio player using `sounddevice`
    player = sd.OutputStream(samplerate=24000, channels=1, dtype=np.int16)
    player.start()

    # Play the audio stream as it comes in
    async for event in result.stream():
        if event.type == "voice_stream_event_audio":
            player.write(event.data)


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Usage example for run()

Source: https://openai.github.io/openai-agents-python/ref/realtime/runner

Example of creating a RealtimeRunner and using run() to start a session, send a message, and iterate over events.

```python
runner = RealtimeRunner(agent)
async with await runner.run() as session:
    await session.send_message("Hello")
    async for event in session:
        print(event)
```

--------------------------------

### Quick start with SQLAlchemySession.from_url

Source: https://openai.github.io/openai-agents-python/sessions/sqlalchemy_session

Quick start using SQLAlchemySession.from_url with an in-memory SQLite database. Creates tables automatically and runs an agent with the session.

```python
import asyncio
from agents import Agent, Runner
from agents.extensions.memory import SQLAlchemySession


async def main():
    agent = Agent("Assistant")

    # Create session using database URL
    session = SQLAlchemySession.from_url(
        "user-123", url="sqlite+aiosqlite:///:memory:", create_tables=True
    )

    result = await Runner.run(agent, "Hello", session=session)
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install openai-agents with Docker support

Source: https://openai.github.io/openai-agents-python/sandbox_agents

Install the SDK with Docker support for Docker-backed sandboxes.

```bash
pip install "openai-agents[docker]"

```

--------------------------------

### Install openai-agents[redis]

Source: https://openai.github.io/openai-agents-python/sessions

Install the Redis extra for the Agents SDK.

```bash
pip install openai-agents[redis]

```

--------------------------------

### Install voice dependencies

Source: https://openai.github.io/openai-agents-python/voice/quickstart

Install the optional voice dependencies from the SDK using pip.

```bash
pip install 'openai-agents[voice]'

```

--------------------------------

### Start from a snapshot with LocalSnapshotSpec

Source: https://openai.github.io/openai-agents-python/sandbox/guide

Seed a new sandbox from saved files and artifacts. Use this when a run that creates a fresh sandbox session should start from saved workspace contents rather than only agent.default_manifest.

```python
from pathlib import Path

from agents.run import RunConfig
from agents.sandbox import LocalSnapshotSpec, SandboxRunConfig
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=UnixLocalSandboxClient(),
        snapshot=LocalSnapshotSpec(base_path=Path("/tmp/my-sandbox-snapshot")),
    ),
)

```

--------------------------------

### Agent Configuration Example

Source: https://openai.github.io/openai-agents-python/agents

Shows how to instantiate an Agent with common properties including a custom tool.

```APIDOC
## Agent Configuration

### Description
Creates an Agent instance with configurable properties such as name, instructions, model, and tools.

### Constructor
`Agent(name, instructions=None, prompt=None, handoff_description=None, handoffs=None, model=None, model_settings=None, tools=None, mcp_servers=None, mcp_config=None, input_guardrails=None, output_guardrails=None, output_type=None, hooks=None, tool_use_behavior=None, reset_tool_choice=True)`

### Parameters
- **name** (string) - Required - Human-readable agent name.
- **instructions** (string or callable) - Optional - System prompt or dynamic instructions callback. Strongly recommended.
- **prompt** (object or function) - Optional - OpenAI Responses API prompt configuration. Accepts a static prompt object or a function.
- **handoff_description** (string) - Optional - Short description exposed when this agent is offered as a handoff target.
- **handoffs** (list) - Optional - Delegate the conversation to specialist agents.
- **model** (string) - Optional - Which LLM to use.
- **model_settings** (object) - Optional - Model tuning parameters such as `temperature`, `top_p`, and `tool_choice`.
- **tools** (list) - Optional - Tools the agent can call.
- **mcp_servers** (list) - Optional - MCP servers that provide MCP-backed tools to the agent.
- **mcp_config** (object) - Optional - Fine-tune how MCP tools are prepared, such as converting their schemas to strict mode and formatting MCP failures.
- **input_guardrails** (list) - Optional - Guardrails that run on the first user input for this agent chain.
- **output_guardrails** (list) - Optional - Guardrails that run on the final output for this agent.
- **output_type** (type) - Optional - Structured output type instead of plain text.
- **hooks** (object) - Optional - Agent-scoped lifecycle callbacks.
- **tool_use_behavior** (object) - Optional - Control whether tool results loop back to the model or end the run.
- **reset_tool_choice** (boolean) - Optional - Reset `tool_choice` after a tool call (default: `True`) to avoid tool-use loops.

### Example
```python
from agents import Agent
from agents.decorators import tool


@tool
def get_weather(city: str) -> str:
    """returns weather info for the specified city."""
    return f"The weather in {city} is sunny"


agent = Agent(
    name="Haiku agent",
    instructions="Always respond in haiku form",
    model="gpt-5-nano",
    tools=[get_weather],
)
```
```

--------------------------------

### Hello world agent with Runner.run_sync

Source: https://openai.github.io/openai-agents-python

Creates a simple agent and runs it synchronously with a prompt. Prints the final output, which in this example is a haiku about recursion. Requires the OPENAI_API_KEY environment variable to be set.

```python
from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

# Code within the code,
# Functions calling themselves,
# Infinite loop's dance.

```

--------------------------------

### RunHooks lifecycle example

Source: https://openai.github.io/openai-agents-python/agents

Defines a RunHooks subclass that logs agent start, LLM end, and agent end events. The hooks are passed to Runner.run() to observe the entire workflow. The example shows async hook methods and printing usage information.

```python
from agents import Agent, RunHooks, Runner


class LoggingHooks(RunHooks):
    async def on_agent_start(self, context, agent):
        print(f"Starting {agent.name}")

    async def on_llm_end(self, context, agent, response):
        print(f"{agent.name} produced {len(response.output)} output items")

    async def on_agent_end(self, context, agent, output):
        print(f"{agent.name} finished with usage: {context.usage}")


agent = Agent(name="Assistant", instructions="Be concise.")
result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks())
print(result.final_output)

```

--------------------------------

### Conversation analysis with AdvancedSQLiteSession

Source: https://openai.github.io/openai-agents-python/sessions/advanced_sqlite_session

Shows how to retrieve conversation data organized by turns, get tool usage statistics, and find turns by content using AdvancedSQLiteSession methods. Each method returns data that is iterated and printed in the examples.

```python
# Get conversation organized by turns
conversation_by_turns = await session.get_conversation_by_turns()
for turn_num, items in conversation_by_turns.items():
    print(f"Turn {turn_num}: {len(items)} items")
    for item in items:
        if item["tool_name"]:
            print(f"  - {item['type']} (tool: {item['tool_name']})")
        else:
            print(f"  - {item['type']}")

# Get tool usage statistics
tool_usage = await session.get_tool_usage()
for tool_name, count, turn in tool_usage:
    print(f"{tool_name}: used {count} times in turn {turn}")

# Find turns by content
matching_turns = await session.find_turns_by_content("weather")
for turn in matching_turns:
    print(f"Turn {turn['turn']}: {turn['content']}")
```

--------------------------------

### UnixLocalSandboxClient.__init__

Source: https://openai.github.io/openai-agents-python/ref/sandbox/sandboxes/unix_local

Initializes a new UnixLocalSandboxClient instance with configurable host environment inheritance and dependency injection.

```APIDOC
## UnixLocalSandboxClient.__init__

### Description
Initializes a new UnixLocalSandboxClient instance for creating local host sandbox sessions.

### Method
Constructor

### Parameters
#### Keyword Arguments
- **instrumentation** (Instrumentation | None) - Optional - Instrumentation instance for observability.
- **dependencies** (Dependencies | None) - Optional - Dependencies for the sandbox client.
- **inherit_host_environment** (bool) - Optional - Whether to inherit the host environment. Defaults to True.
- **host_environment_allowlist** (Collection[str] | None) - Optional - Collection of environment variable names to allow when inherit_host_environment is False. Cannot be set when inherit_host_environment is True. Must be a collection of variable names, not a string.

### Exceptions
- **ValueError** - Raised when both inherit_host_environment is True and host_environment_allowlist is provided.
- **TypeError** - Raised when host_environment_allowlist is a string instead of a collection of variable names.
```

```APIDOC
## [CREATE] create

### Description
Creates a new local host sandbox session. Linux sessions add no OS-level command confinement. macOS sessions apply filesystem restrictions through sandbox-exec, but do not provide network isolation. Separate workspaces and host environment filtering do not establish an OS isolation boundary.

### Method
CREATE

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **snapshot** (SnapshotSpec | SnapshotBase | None) - Optional - Snapshot specification for the session
- **manifest** (Manifest | None) - Optional - Manifest configuration for the session
- **options** (UnixLocalSandboxClientOptions | None) - Optional - Options for the Unix local sandbox client

### Request Example
```python
client = UnixLocalSandboxClient()
session = await client.create(snapshot=..., manifest=..., options=...)
```

### Response
#### Success Response (200)
- **SandboxSession** - The created sandbox session

#### Response Example
```python
session = await client.create(...)
```
```

--------------------------------

### Use EncryptedSession with SQLiteSession

Source: https://openai.github.io/openai-agents-python/sessions/encrypted_session

Quick start example using an in-memory SQLiteSession with a fresh encryption key. The built-in session does not require a separate database driver. For persistent storage, retain and reuse the key across process restarts.

```python
import asyncio
from cryptography.fernet import Fernet
from agents import Agent, Runner, SQLiteSession
from agents.extensions.memory import EncryptedSession


async def main():
    agent = Agent("Assistant")
    encryption_key = Fernet.generate_key().decode("ascii")

    underlying_session = SQLiteSession("user-123")
    try:
        session = EncryptedSession(
            session_id="user-123",
            underlying_session=underlying_session,
            encryption_key=encryption_key,
            ttl=600,  # 10 minutes
        )

        result = await Runner.run(agent, "Hello", session=session)
        print(result.final_output)
    finally:
        underlying_session.close()


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### start

Source: https://openai.github.io/openai-agents-python/ref/tracing

Start the trace and optionally mark it as the current trace.

```APIDOC
## start

### Description
Start the trace and optionally mark it as the current trace.

### Method
start

### Parameters
- **mark_as_current** (bool) - Optional - If true, marks this trace as the current trace in the execution context.

### Notes
- Must be called before any spans can be added
- Only one trace can be current at a time
- Thread-safe when using mark_as_current
```

--------------------------------

### MCPServer.__init__

Source: https://openai.github.io/openai-agents-python/ref/mcp/server

Initialize the MCPServer instance with configuration options for structured content, approval requirements, error handling, tool metadata, custom data extraction, and guardrails.

```APIDOC
## MCPServer.__init__

### Description
Initialize the MCPServer instance with configuration options for structured content, approval requirements, error handling, tool metadata, custom data extraction, and guardrails.

### Method
Constructor

### Parameters
- **use_structured_content** (bool) - Optional - Whether to use structured content. Defaults to False.
- **require_approval** (RequireApprovalSetting) - Optional - Approval requirement setting. Defaults to None.
- **failure_error_function** (ToolErrorFunction | None | _UnsetType) - Optional - Error function to call on tool failure. Defaults to _UNSET.
- **tool_meta_resolver** (MCPToolMetaResolver | None) - Optional - Resolver for tool metadata. Defaults to None.
- **custom_data_extractor** (MCPToolCustomDataExtractor | None) - Optional - Custom data extractor for tools. Defaults to None.
- **tool_input_guardrails** (list[ToolInputGuardrail[Any]] | None) - Optional - Guardrails for tool inputs. Defaults to None.
- **tool_output_guardrails** (list[ToolOutputGuardrail[Any]] | None) - Optional - Guardrails for tool outputs. Defaults to None.
```

--------------------------------

### Install openai-agents[dapr]

Source: https://openai.github.io/openai-agents-python/sessions

Install the Dapr extra for the Agents SDK.

```bash
pip install openai-agents[dapr]

```

--------------------------------

### Define the starting agent

Source: https://openai.github.io/openai-agents-python/realtime/quickstart

Creates a RealtimeAgent named "Assistant" with instructions for a helpful voice assistant that keeps responses short and conversational.

```python
agent = RealtimeAgent(
    name="Assistant",
    instructions="You are a helpful voice assistant. Keep responses short and conversational.",
)

```

--------------------------------

### Install aiosqlite for AsyncSQLiteSession

Source: https://openai.github.io/openai-agents-python/sessions

Install the aiosqlite package required for AsyncSQLiteSession.

```bash
pip install aiosqlite

```

--------------------------------

### MCPServerStdio.__init__

Source: https://openai.github.io/openai-agents-python/ref/mcp/server

Constructor for MCPServerStdio that initializes the server with parameters and configuration options.

```APIDOC
## MCPServerStdio

### Description
Creates a new MCPServerStdio instance for connecting to a Model Context Protocol (MCP) server over standard input/output (stdio). This constructor initializes the server with the provided parameters and configuration options.

### Method
Constructor

### Signature
```python
__init__(
    params: MCPServerStdioParams,
    cache_tools_list: bool = False,
    name: str | None = None,
    client_session_timeout_seconds: float | None = 5,
    tool_filter: ToolFilter = None,
    use_structured_content: bool = False,
    max_retry_attempts: int = 0,
    retry_backoff_seconds_base: float = 1.0,
    message_handler: MessageHandlerFnT | None = None,
    require_approval: RequireApprovalSetting = None,
    failure_error_function: ToolErrorFunction | None | _UnsetType = _UNSET,
    tool_meta_resolver: MCPToolMetaResolver | None = None,
    custom_data_extractor: MCPToolCustomDataExtractor | None = None,
    retry_backoff_seconds_max: float | None = None,
    *,
    tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
    tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
    max_list_pages: int | None = None,
)
```

### Parameters
- **params** (MCPServerStdioParams) - Required - Parameters for the stdio server, including command, args, env, cwd, encoding, and encoding_error_handler.
- **cache_tools_list** (bool) - Optional - Whether to cache the tools list. Defaults to False.
- **name** (str | None) - Optional - A readable name for the server. If not provided, a default name is generated.
- **client_session_timeout_seconds** (float | None) - Optional - Timeout for client sessions in seconds. Defaults to 5.
- **tool_filter** (ToolFilter) - Optional - Filter for tools.
- **use_structured_content** (bool) - Optional - Whether to use structured content. Defaults to False.
- **max_retry_attempts** (int) - Optional - Maximum number of retry attempts. Defaults to 0.
- **retry_backoff_seconds_base** (float) - Optional - Base backoff time in seconds for retries. Defaults to 1.0.
- **message_handler** (MessageHandlerFnT | None) - Optional - Handler for messages.
- **require_approval** (RequireApprovalSetting) - Optional - Approval requirement setting.
- **failure_error_function** (ToolErrorFunction | None | _UnsetType) - Optional - Function to handle tool errors. Defaults to _UNSET.
- **tool_meta_resolver** (MCPToolMetaResolver | None) - Optional - Resolver for tool metadata.
- **custom_data_extractor** (MCPToolCustomDataExtractor | None) - Optional - Extractor for custom data.
- **retry_backoff_seconds_max** (float | None) - Optional - Maximum backoff time in seconds for retries.
- **tool_input_guardrails** (list[ToolInputGuardrail[Any]] | None) - Optional - Guardrails for tool inputs.
- **tool_output_guardrails** (list[ToolOutputGuardrail[Any]] | None) - Optional - Guardrails for tool outputs.
- **max_list_pages** (int | None) - Optional - Maximum number of pages for listing tools.

### Returns
None

### Example
```python
server = MCPServerStdio(
    params={"command": "python", "args": ["server.py"]},
    name="my-mcp-server",
    cache_tools_list=True,
)
```
```

--------------------------------

### Start PTY exec in Docker container

Source: https://openai.github.io/openai-agents-python/ref/sandbox/sandboxes/docker

Starts a PTY exec in the Docker container, creating a wrapped shell command, starting the exec socket, and launching a reader thread.

```python
async def pty_exec_start(
    self,
    *command: str | Path,
    timeout: float | None = None,
    shell: bool | list[str] = True,
    user: str | User | None = None,
    tty: bool = False,
    yield_time_s: float | None = None,
    max_output_tokens: int | None = None,
) -> PtyExecUpdate:
    docker_user = self._coerce_exec_user(user)
    sanitized_command = self._prepare_exec_command(*command, shell=shell, user=None)
    cmd = [str(c) for c in sanitized_command]
    await self._recover_workspace_root_ready(timeout=timeout)
    workdir = self.state.manifest.root if self._workspace_root_ready else None

    loop = asyncio.get_running_loop()
    container_client = self._container.client
    assert container_client is not None
    api = container_client.api

    entry: _DockerPtyProcessEntry | None = None
    pty_pid_path: Path | None = None
    registered = False
    pruned_entry: _DockerPtyProcessEntry | None = None
    process_id = 0
    process_count = 0

    try:
        pty_pid_path = self._archive_stage_path(name_hint="pty.pid")
        await self._prepare_user_pty_pid_path(path=pty_pid_path, user=docker_user)
        wrapped_cmd = [
            "sh",
            "-lc",
            'mkdir -p "$1" && printf "%s" "$$" > "$2" && shift 2 && exec "$@"',
            "sh",
            sandbox_path_str(pty_pid_path.parent),
            sandbox_path_str(pty_pid_path),
            *cmd,
        ]
        resp = await asyncio.wait_for(
            loop.run_in_executor(
                _DOCKER_EXECUTOR,
                lambda: api.exec_create(
                    self._container.id,
                    wrapped_cmd,
                    stdin=True,
                    stdout=True,
                    stderr=True,
                    tty=tty,
                    workdir=workdir,
                    user=docker_user or "",
                ),
            ),
            timeout=timeout,
        )
        exec_id = cast(str, resp["Id"])
        exec_socket = await asyncio.wait_for(
            loop.run_in_executor(
                _DOCKER_EXECUTOR,
                lambda: self._start_exec_socket(api=api, exec_id=exec_id, tty=tty),
            ),
            timeout=timeout,
        )
        raw_sock = exec_socket.raw_sock
        if not tty:
            try:
                cast(Any, raw_sock).shutdown(socket.SHUT_WR)
            except Exception:
                pass
        entry = _DockerPtyProcessEntry(
            exec_id=exec_id,
            sock=exec_socket,
            raw_sock=raw_sock,
            pid_path=pty_pid_path,
            tty=tty,
        )
        entry.reader_thread = threading.Thread(
            target=self._pump_pty_socket,
            args=(entry, loop),
            daemon=True,
            name=f"agents-docker-pty-{exec_id[:12]}",
        )
        entry.reader_thread.start()
        entry.wait_task = asyncio.create_task(self._watch_pty_exit(entry))
```

--------------------------------

### Create project and virtual environment

Source: https://openai.github.io/openai-agents-python/quickstart

Creates a new project directory and a Python virtual environment. Run once when starting a new project.

```bash
mkdir my_project
cd my_project
python -m venv .venv

```

--------------------------------

### MCPServerSse.__init__

Source: https://openai.github.io/openai-agents-python/ref/mcp/server

Documentation for the MCPServerSse constructor, which creates a new MCP server based on the HTTP with SSE transport.

```APIDOC
## MCPServerSse.__init__

### Description
Creates a new MCP server based on the HTTP with SSE transport. This constructor configures the server with parameters such as the SSE endpoint URL, headers, timeouts, caching behavior, and tool filtering.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    params: MCPServerSseParams,
    cache_tools_list: bool = False,
    name: str | None = None,
    client_session_timeout_seconds: float | None = 5,
    tool_filter: ToolFilter = None,
    use_structured_content: bool = False,
    max_retry_attempts: int = 0,
    retry_backoff_seconds_base: float = 1.0,
    message_handler: MessageHandlerFnT | None = None,
    require_approval: RequireApprovalSetting = None,
    failure_error_function: ToolErrorFunction | None | _UnsetType = _UNSET,
    tool_meta_resolver: MCPToolMetaResolver | None = None,
    custom_data_extractor: MCPToolCustomDataExtractor | None = None,
    retry_backoff_seconds_max: float | None = None,
    tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
    tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
    max_list_pages: int | None = None,
)
```

### Parameters
- **params** (`MCPServerSseParams`) - Required - The params that configure the server. This includes the URL of the server, the headers to send to the server, the timeout for the HTTP request, and the timeout for the SSE connection.
- **cache_tools_list** (`bool`) - Optional - Whether to cache the tools list. If `True`, the tools list will be cached and only fetched from the server once. If `False`, the tools list will be fetched from the server on each call to `list_tools()`. The cache can be invalidated by calling `invalidate_tools_cache()`. You should set this to `True` if you know the server will not change its tools list, because it can drastically improve latency (by avoiding a round-trip to the server every time). Default: `False`.
- **name** (`str | None`) - Optional - A readable name for the server. If not provided, we'll create one from the URL. Default: `None`.
- **client_session_timeout_seconds** (`float | None`) - Optional - The MCP ClientSession read timeout. Positive finite values representable by `datetime.timedelta` and at least one microsecond set a timeout; `None` and `0` disable it. Other values are rejected during server construction. Default: `5`.
- **tool_filter** (`ToolFilter`) - Optional - The tool filter to use for filtering tools. Default: `None`.
- **use_structured_content** (`bool`) - Optional - Whether to use `tool_result.structured_content` when calling an MCP tool. Defaults to False for backwards compatibility - most MCP servers still include the structured content in the `tool_result.content`, and using it by default will cause duplicate content. You can set this to True if you know the server will not duplicate the structured content in the `tool_result.content`. Default: `False`.
- **max_retry_attempts** (`int`) - Optional - Number of times to retry failed list_tools/call_tool calls. Defaults to no retries. Default: `0`.
- **retry_backoff_seconds_base** (`float`) - Optional - The base delay, in seconds, for exponential backoff between retries. Default: `1.0`.
- **message_handler** (`MessageHandlerFnT | None`) - Optional - Optional handler invoked for session messages as delivered by the ClientSession. Default: `None`.
- **require_approval** (`RequireApprovalSetting`) - Optional - Approval policy for tools on this server. Accepts "always"/"never", a dict of tool names to those values, or an object with always/never tool lists. Default: `None`.
- **failure_error_function** (`ToolErrorFunction | None | _UnsetType`) - Optional - Optional function used to convert MCP tool failures into a model-visible error message. If explicitly set to None, tool errors will be raised instead of converted. If left unset, the agent-level configuration (or SDK default) will be used. Default: `_UNSET`.
- **tool_meta_resolver** (`MCPToolMetaResolver | None`) - Optional - Optional callable that produces MCP request metadata (`_meta`) for tool calls. It is invoked by the Agents SDK before calling `call_tool`. Default: `None`.
- **custom_data_extractor** (`MCPToolCustomDataExtractor | None`) - Optional - Optional callable that produces SDK-only custom data for emitted MCP tool output items. Default: `None`.
- **retry_backoff_seconds_max** (`float | None`) - Optional - The non-negative finite maximum delay, in seconds, between retries. Defaults to `None`, which leaves exponential backoff uncapped. Default: `None`.
- **tool_input_guardrails** (`list[ToolInputGuardrail[Any]] | None`) - Optional - Optional list of guardrails applied to every tool on this server before the tool is invoked. Default: `None`.
- **tool_output_guardrails** (`list[ToolOutputGuardrail[Any]] | None`) - Optional - Optional list of guardrails applied to every tool on this server after the tool returns. Default: `None`.
- **max_list_pages** (`int | None`) - Optional - Maximum successful pages per automatic `list_tools()` or `list_prompts()` call. Set a positive integer to bound pagination; `None` (the default) applies no page limit. A final page at the limit succeeds; otherwise `UserError` is raised without returning or caching a partial list. Failed requests follow the existing retry policy and do not reset this budget. This does not limit page size or apply to explicit resource pagination. Default: `None`.

### Source Code
```python
def __init__(
    self,
    params: MCPServerSseParams,
    cache_tools_list: bool = False,
    name: str | None = None,
    client_session_timeout_seconds: float | None = 5,
    tool_filter: ToolFilter = None,
    use_structured_content: bool = False,
    max_retry_attempts: int = 0,
    retry_backoff_seconds_base: float = 1.0,
    message_handler: MessageHandlerFnT | None = None,
    require_approval: RequireApprovalSetting = None,
    failure_error_function: ToolErrorFunction | None | _UnsetType = _UNSET,
    tool_meta_resolver: MCPToolMetaResolver | None = None,
    custom_data_extractor: MCPToolCustomDataExtractor | None = None,
    retry_backoff_seconds_max: float | None = None,
    tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
    tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
    max_list_pages: int | None = None,
)
```
```

--------------------------------

### Install openai-agents[encrypt]

Source: https://openai.github.io/openai-agents-python/sessions/encrypted_session

Install the required encryption extra for encrypted sessions.

```bash
pip install 'openai-agents[encrypt]'

```

--------------------------------

### Install MongoDB extension

Source: https://openai.github.io/openai-agents-python/sessions

Install the MongoDB extension for the OpenAI Agents Python package.

```bash
pip install openai-agents[mongodb]

```

--------------------------------

### MultiProvider.__init__

Source: https://openai.github.io/openai-agents-python/ref/models/multi_provider

Initializes a MultiProvider instance with a provider map and OpenAI provider configuration options.

```APIDOC
## MultiProvider Constructor

### Description
Creates a new MultiProvider instance that routes model requests to the appropriate provider based on model name prefixes.

### Method
Constructor

### Signature
```python
MultiProvider(
    provider_map: MultiProviderMap | None = None,
    openai_api_key: str | None = None,
    openai_base_url: str | None = None,
    openai_client: OpenAI | None = None,
    openai_organization: str | None = None,
    openai_project: str | None = None,
    openai_use_responses: bool = False,
    openai_use_responses_websocket: bool = False,
    openai_strict_feature_validation: bool = False,
    openai_websocket_base_url: str | None = None,
    openai_prefix_mode: str = "alias",
    unknown_prefix_mode: str = "error",
    openai_agent_registration: Optional[Any] = None,
    openai_responses_websocket_options: Optional[Any] = None,
    openai_buffer_streamed_tool_calls: bool = False
)
```

### Parameters
- **provider_map** (MultiProviderMap) - Optional - A mapping of prefixes to ModelProviders. If not provided, a default mapping is used.
- **openai_api_key** (str) - Optional - API key for the OpenAI provider. Defaults to the default API key.
- **openai_base_url** (str) - Optional - Base URL for the OpenAI provider. Defaults to the default base URL.
- **openai_client** (OpenAIClient) - Optional - An existing OpenAI client to use; otherwise a new one is created.
- **openai_organization** (str) - Optional - Organization for the OpenAI provider.
- **openai_project** (str) - Optional - Project for the OpenAI provider.
- **openai_use_responses** (bool) - Optional - Whether to use the OpenAI responses API.
- **openai_use_responses_websocket** (bool) - Optional - Whether to use websocket transport for the OpenAI responses API.
- **openai_strict_feature_validation** (bool) - Optional - Whether to raise a UserError when callers pass Responses-only features to Chat Completions models. Defaults to False.
- **openai_websocket_base_url** (str) - Optional - The websocket base URL for the OpenAI provider. Defaults to the OPENAI_WEBSOCKET_BASE_URL environment variable when set.
- **openai_prefix_mode** (str) - Optional - Controls how "openai/..." model strings are interpreted. "alias" strips the prefix; "model_id" keeps the full string.
- **unknown_prefix_mode** (str) - Optional - Controls handling of unknown prefixes. "error" raises UserError; "model_id" passes the full string through to the OpenAI provider.
- **openai_agent_registration** (object) - Optional agent registration configuration for the OpenAI provider.
- **openai_responses_websocket_options** (object) - Optional low-level websocket keepalive options for the OpenAI Responses websocket transport.
- **openai_buffer_streamed_tool_calls** (bool) - Whether to buffer streamed function tool-call deltas for OpenAI Chat Completions models.

Internal methods `_get_prefix_and_model_name` and `_create_fallback_provider` are also documented, though they are not part of the public API surface.
```

--------------------------------

### MCPServerManager.__init__

Source: https://openai.github.io/openai-agents-python/ref/mcp/manager

Initializes a new MCPServerManager instance with the provided servers and configuration options.

```APIDOC
## MCPServerManager.__init__

### Description
Initializes a new MCPServerManager with the given servers and lifecycle configuration.

### Parameters
- **servers** (Iterable[MCPServer]) - Required - The MCP servers to manage.
- **connect_timeout_seconds** (float | None) - Optional - Lifecycle connect timeout in seconds. Defaults to 10.0. Use None to disable the timeout. Zero is rejected.
- **cleanup_timeout_seconds** (float | None) - Optional - Lifecycle cleanup timeout in seconds. Defaults to 10.0. Use None to disable the timeout. Zero is rejected.
- **drop_failed_servers** (bool) - Optional - If True, removes failed servers from `active_servers` (recommended). If False, `active_servers` will still include all servers. Defaults to True.
- **strict** (bool) - Optional - If True, raises on the first connection failure. If False, failures are recorded and the run can proceed with the remaining servers. Defaults to False.
- **suppress_cancelled_error** (bool) - Optional - If True, suppresses cancellation errors. Defaults to True.
- **connect_in_parallel** (bool) - Optional - If True, uses a dedicated worker task per server to allow concurrent connects while preserving task affinity for cleanup. Defaults to False.

### Returns
- **MCPServerManager** - The manager instance.

### Raises
- **ValueError** - If a lifecycle timeout is zero or negative.

### Example
```python
manager = MCPServerManager(servers, connect_timeout_seconds=10.0, cleanup_timeout_seconds=10.0)
```

## connect_all

### Description
Connects all servers in order and returns the active list.

### Method
async def connect_all(self) -> list[MCPServer]

### Parameters
None

### Returns
- **list[MCPServer]** - The active servers after connection attempts.

### Example
```python
active = await manager.connect_all()
```

## cleanup_all

### Description
Cleans up all connected servers.

### Method
async def cleanup_all(self) -> None

### Parameters
None

### Returns
None

### Example
```python
await manager.cleanup_all()
```

## Properties

### active_servers
Returns the active MCP servers after connection attempts.

### all_servers
Returns all MCP servers managed by this instance.

### failed_servers
Returns a snapshot of MCP servers with recorded failures.

### errors
Returns a snapshot of recorded MCP server errors.

### connect_timeout_seconds
Returns the lifecycle connect timeout.

### cleanup_timeout_seconds
Returns the lifecycle cleanup timeout.```json
{
  
```

--------------------------------

### OpenAIProvider.__init__

Source: https://openai.github.io/openai-agents-python/ref/models/openai_provider

Creates a new OpenAI provider instance with configurable API key, base URL, client, and feature flags.

```APIDOC
## OpenAIProvider.__init__

### Description
Creates a new OpenAI provider instance with configurable client, API settings, and feature flags.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    *,
    api_key: str | None = None,
    base_url: str | None = None,
    websocket_base_url: str | None = None,
    openai_client: AsyncOpenAI | None = None,
    organization: str | None = None,
    project: str | None = None,
    use_responses: bool | None = None,
    use_responses_websocket: bool | None = None,
    strict_feature_validation: bool = False,
    agent_registration: OpenAIAgentRegistrationConfig | dict[str, Any] | None = None,
    responses_websocket_options: OpenAIResponsesWebSocketOptions | None = None,
    buffer_streamed_tool_calls: bool = False,
) -> None
```

### Parameters

- **api_key** (str | None) - Optional - The API key to use for the OpenAI client. If not provided, the default API key is used.
- **base_url** (str | None) - Optional - The base URL to use for the OpenAI client. If not provided, the default base URL is used.
- **websocket_base_url** (str | None) - Optional - The websocket base URL to use for the OpenAI client. If not provided, the OPENAI_WEBSOCKET_BASE_URL environment variable is used when set.
- **openai_client** (AsyncOpenAI | None) - Optional - An existing OpenAI client to use. If provided, api_key, base_url, websocket_base_url, organization, and project must not be provided.
- **organization** (str | None) - Optional - The organization to use for the OpenAI client.
- **project** (str | None) - Optional - The project to use for the OpenAI client.
- **use_responses** (bool | None) - Optional - Whether to use the OpenAI responses API.
- **use_responses_websocket** (bool | None) - Optional - Whether to use websocket transport for the OpenAI responses API.
- **strict_feature_validation** (bool) - Optional - Whether Chat Completions models should raise a UserError when callers pass Responses-only features. Defaults to False.
- **agent_registration** (OpenAIAgentRegistrationConfig | dict[str, Any] | None) - Optional agent registration configuration.
- **responses_websocket_options** (OpenAIResponsesWebSocketOptions | None) - Optional low-level websocket keepalive options for the OpenAI Responses websocket transport.
- **buffer_streamed_tool_calls** (bool) - Whether Chat Completions models should buffer streamed function tool-call deltas and emit them to the SDK only after the provider stream finishes. Defaults to False.

This is a constructor for the OpenAIProvider class, not a direct API endpoint. It is part of the SDK's provider interface that users instantiate to configure how the Agents SDK communicates with OpenAI-compatible APIs.
```

--------------------------------

### start method

Source: https://openai.github.io/openai-agents-python/ref/tracing

Start the trace and optionally mark it as the current trace. Must be called before any spans can be added.

```python
start(mark_as_current: bool = False)
```

--------------------------------

### MultiProvider.__init__

Source: https://openai.github.io/openai-agents-python/ref/models/multi_provider

Initializes a MultiProvider instance with a provider map and optional OpenAI configuration parameters.

```APIDOC
## MultiProvider.__init__

### Description
Initializes a MultiProvider instance with a provider map and optional OpenAI configuration parameters.

### Method
Constructor

### Signature
```python
__init__(
    *,
    provider_map: MultiProviderMap | None = None,
    openai_api_key: str | None = None,
    openai_base_url: str | None = None,
    openai_client: AsyncOpenAI | None = None,
    openai_organization: str | None = None,
    openai_project: str | None = None,
    openai_use_responses: bool | None = None,
    openai_use_responses_websocket: bool | None = None,
    openai_strict_feature_validation: bool = False,
    openai_websocket_base_url: str | None = None,
    openai_prefix_mode: MultiProviderOpenAIPrefixMode = "alias",
    unknown_prefix_mode: MultiProviderUnknownPrefixMode = "error",
    openai_agent_registration: OpenAIAgentRegistrationConfig
    | dict[str, Any]
    | None = None,
    openai_responses_websocket_options: OpenAIResponsesWebSocketOptions
    | None = None,
    openai_buffer_streamed_tool_calls: bool = False,
) -> None
```

### Parameters
All parameters are keyword-only.

- **provider_map** (MultiProviderMap | None) - Optional - A mapping of provider prefixes to provider instances.
- **openai_api_key** (str | None) - Optional - The OpenAI API key to use.
- **openai_base_url** (str | None) - Optional - The base URL for the OpenAI API.
- **openai_client** (AsyncOpenAI | None) - Optional - An existing AsyncOpenAI client instance.
- **openai_organization** (str | None) - Optional - The OpenAI organization ID.
- **openai_project** (str | None) - Optional - The OpenAI project ID.
- **openai_use_responses** (bool | None) - Optional - Whether to use the Responses API.
- **openai_use_responses_websocket** (bool | None) - Optional - Whether to use the Responses WebSocket API.
- **openai_strict_feature_validation** (bool) - Optional - Whether to enforce strict feature validation. Defaults to False.
- **openai_websocket_base_url** (str | None) - Optional - The base URL for the WebSocket connection.
- **openai_prefix_mode** (MultiProviderOpenAIPrefixMode) - Optional - The prefix mode for OpenAI providers. Defaults to "alias".
- **unknown_prefix_mode** (MultiProviderUnknownPrefixMode) - Optional - The behavior when an unknown prefix is encountered. Defaults to "error".
- **openai_agent_registration** (OpenAIAgentRegistrationConfig | dict[str, Any] | None) - Optional - Configuration for agent registration.
- **openai_responses_websocket_options** (OpenAIResponsesWebSocketOptions | None) - Optional - Options for the Responses WebSocket.
- **openai_buffer_streamed_tool_calls** (bool) - Optional - Whether to buffer streamed tool calls. Defaults to False.

### Returns
None
```

--------------------------------

### Install openai-agents viz dependency

Source: https://openai.github.io/openai-agents-python/visualization

Install the optional viz dependency group to enable agent visualization.

```bash
pip install "openai-agents[viz]"
```

--------------------------------

### Install openai-agents with pip

Source: https://openai.github.io/openai-agents-python

Install the openai-agents package using pip. Run this in your terminal before using the SDK.

```bash
pip install openai-agents

```

--------------------------------

### __post_init__ implementation in src/agents/items.py

Source: https://openai.github.io/openai-agents-python/ref/items

Populates tool_name, tool_namespace, and tool_lookup_key from the raw item if not provided. Handles both dict and object raw items, extracting name, namespace, and type fields as appropriate.

```python
def __post_init__(self) -> None:
    """Populate tool_name from the raw item if not provided."""
    if self.tool_name is None:
        # Extract name from raw_item - handle different types
        if isinstance(self.raw_item, dict):
            self.tool_name = self.raw_item.get("name")
        elif hasattr(self.raw_item, "name"):
            self.tool_name = self.raw_item.name
        else:
            self.tool_name = None
    if self.tool_namespace is None:
        if isinstance(self.raw_item, dict):
            namespace = self.raw_item.get("namespace")
        else:
            namespace = getattr(self.raw_item, 
```

--------------------------------

### Capabilities.default() class method

Source: https://openai.github.io/openai-agents-python/ref/sandbox/capabilities/capabilities

Returns a list of default Capability instances: Filesystem, Shell, and Compaction. Use this to obtain the standard set of sandbox capabilities.

```python
class Capabilities:
    @classmethod
    def default(cls) -> list[Capability]:
        return [Filesystem(), Shell(), Compaction()]

```

--------------------------------

### Install the Agents SDK

Source: https://openai.github.io/openai-agents-python/quickstart

Installs the openai-agents package. The comment notes an alternative using `uv add openai-agents`.

```bash
pip install openai-agents # or `uv add openai-agents`, etc

```

--------------------------------

### Run an agent asynchronously with Runner.run()

Source: https://openai.github.io/openai-agents-python/running_agents

Use this async example to run an agent with the Runner class. It creates an Agent with instructions, calls Runner.run() with a user message, and prints the final output. The output is a haiku about recursion.

```python
from agents import Agent, Runner


async def main():
    agent = Agent(name="Assistant", instructions="You are a helpful assistant")

    result = await Runner.run(agent, "Write a haiku about recursion in programming.")
    print(result.final_output)
    # Code within the code,
    # Functions calling themselves,
    # Infinite loop's dance

```

--------------------------------

### start(mark_as_current: bool = False)

Source: https://openai.github.io/openai-agents-python/ref/tracing

Starts the trace and optionally marks it as the current trace. Must be called before any spans can be added.

```APIDOC
## start(mark_as_current: bool = False)

### Description
Starts the trace and optionally marks it as the current trace in the execution context. Must be called before any spans can be added.

### Method
start

### Parameters
- **mark_as_current** (bool) - Optional - If true, marks this trace as the current trace in the execution context. Default: False.

### Notes
- Must be called before any spans can be added
- Only one trace can be current at a time
- Thread-safe when using mark_as_current
```
Tokens:
Raw