Tools

Tools let agents take actions: things like fetching data, running code, calling external APIs, and even using a computer. The SDK supports five categories:

• Hosted OpenAI tools: run alongside the model on OpenAI servers.
• Local runtime tools: run in your environment (computer use, shell, apply patch).
• Function calling: wrap any Python function as a tool.
• Agents as tools: expose an agent as a callable tool without a full handoff.
• Experimental: Codex tool: run workspace-scoped Codex tasks from a tool call.

Choosing a tool type

Use this page as a catalog, then jump to the section that matches the runtime you control.

If you want to...	Start here
Use OpenAI-managed tools (web search, file search, code interpreter, hosted MCP, image generation)	Hosted tools
Run tools in your own process or environment	Local runtime tools
Wrap Python functions as tools	Function tools
Let one agent call another without a handoff	Agents as tools
Run workspace-scoped Codex tasks from an agent	Experimental: Codex tool

Hosted tools

OpenAI offers a few built-in tools when using the OpenAIResponsesModel:

• The WebSearchTool lets an agent search the web.
• The FileSearchTool allows retrieving information from your OpenAI Vector Stores.
• The CodeInterpreterTool lets the LLM execute code in a sandboxed environment.
• The HostedMCPTool exposes a remote MCP server's tools to the model.
• The ImageGenerationTool generates images from a prompt.

Advanced hosted search options:

• FileSearchTool supports filters, ranking_options, and include_search_results in addition to vector_store_ids and max_num_results.
• WebSearchTool supports filters, user_location, and search_context_size.

from agents import Agent, FileSearchTool, Runner, WebSearchTool

agent = Agent(
    name="Assistant",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            max_num_results=3,
            vector_store_ids=["VECTOR_STORE_ID"],
        ),
    ],
)

async def main():
    result = await Runner.run(agent, "Which coffee shop should I go to, taking into account my preferences and the weather today in SF?")
    print(result.final_output)

Hosted container shell + skills

ShellTool also supports OpenAI-hosted container execution. Use this mode when you want the model to run shell commands in a managed container instead of your local runtime.

from agents import Agent, Runner, ShellTool, ShellToolSkillReference

csv_skill: ShellToolSkillReference = {
    "type": "skill_reference",
    "skill_id": "skill_698bbe879adc81918725cbc69dcae7960bc5613dadaed377",
    "version": "1",
}

agent = Agent(
    name="Container shell agent",
    model="gpt-5.2",
    instructions="Use the mounted skill when helpful.",
    tools=[
        ShellTool(
            environment={
                "type": "container_auto",
                "network_policy": {"type": "disabled"},
                "skills": [csv_skill],
            }
        )
    ],
)

result = await Runner.run(
    agent,
    "Use the configured skill to analyze CSV files in /mnt/data and summarize totals by region.",
)
print(result.final_output)

To reuse an existing container in later runs, set environment={"type": "container_reference", "container_id": "cntr_..."}.

What to know:

• Hosted shell is available through the Responses API shell tool.
• container_auto provisions a container for the request; container_reference reuses an existing one.
• container_auto can also include file_ids and memory_limit.
• environment.skills accepts skill references and inline skill bundles.
• With hosted environments, do not set executor, needs_approval, or on_approval on ShellTool.
• network_policy supports disabled and allowlist modes.
• In allowlist mode, network_policy.domain_secrets can inject domain-scoped secrets by name.
• See examples/tools/container_shell_skill_reference.py and examples/tools/container_shell_inline_skill.py for complete examples.
• OpenAI platform guides: Shell and Skills.

Local runtime tools

Local runtime tools execute in your environment and require you to supply implementations:

• ComputerTool: implement the Computer or AsyncComputer interface to enable GUI/browser automation.
• ShellTool: the latest shell tool for both local execution and hosted container execution.
• LocalShellTool: legacy local-shell integration.
• ApplyPatchTool: implement ApplyPatchEditor to apply diffs locally.
• Local shell skills are available with ShellTool(environment={"type": "local", "skills": [...]}).

from agents import Agent, ApplyPatchTool, ShellTool
from agents.computer import AsyncComputer
from agents.editor import ApplyPatchResult, ApplyPatchOperation, ApplyPatchEditor


class NoopComputer(AsyncComputer):
    environment = "browser"
    dimensions = (1024, 768)
    async def screenshot(self): return ""
    async def click(self, x, y, button): ...
    async def double_click(self, x, y): ...
    async def scroll(self, x, y, scroll_x, scroll_y): ...
    async def type(self, text): ...
    async def wait(self): ...
    async def move(self, x, y): ...
    async def keypress(self, keys): ...
    async def drag(self, path): ...


class NoopEditor(ApplyPatchEditor):
    async def create_file(self, op: ApplyPatchOperation): return ApplyPatchResult(status="completed")
    async def update_file(self, op: ApplyPatchOperation): return ApplyPatchResult(status="completed")
    async def delete_file(self, op: ApplyPatchOperation): return ApplyPatchResult(status="completed")


async def run_shell(request):
    return "shell output"


agent = Agent(
    name="Local tools agent",
    tools=[
        ShellTool(executor=run_shell),
        ApplyPatchTool(editor=NoopEditor()),
        # ComputerTool expects a Computer/AsyncComputer implementation; omitted here for brevity.
    ],
)

Function tools

You can use any Python function as a tool. The Agents SDK will setup the tool automatically:

• The name of the tool will be the name of the Python function (or you can provide a name)
• Tool description will be taken from the docstring of the function (or you can provide a description)
• The schema for the function inputs is automatically created from the function's arguments
• Descriptions for each input are taken from the docstring of the function, unless disabled

We use Python's inspect module to extract the function signature, along with griffe to parse docstrings and pydantic for schema creation.

import json

from typing_extensions import TypedDict, Any

from agents import Agent, FunctionTool, RunContextWrapper, function_tool


class Location(TypedDict):
    lat: float
    long: float

@function_tool  # (1)!
async def fetch_weather(location: Location) -> str:
    # (2)!
    """Fetch the weather for a given location.

    Args:
        location: The location to fetch the weather for.
    """
    # In real life, we'd fetch the weather from a weather API
    return "sunny"


@function_tool(name_override="fetch_data")  # (3)!
def read_file(ctx: RunContextWrapper[Any], path: str, directory: str | None = None) -> str:
    """Read the contents of a file.

    Args:
        path: The path to the file to read.
        directory: The directory to read the file from.
    """
    # In real life, we'd read the file from the file system
    return "<file contents>"


agent = Agent(
    name="Assistant",
    tools=[fetch_weather, read_file],  # (4)!
)

for tool in agent.tools:
    if isinstance(tool, FunctionTool):
        print(tool.name)
        print(tool.description)
        print(json.dumps(tool.params_json_schema, indent=2))
        print()

1. You can use any Python types as arguments to your functions, and the function can be sync or async.
2. Docstrings, if present, are used to capture descriptions and argument descriptions
3. Functions can optionally take the context (must be the first argument). You can also set overrides, like the name of the tool, description, which docstring style to use, etc.
4. You can pass the decorated functions to the list of tools.

Expand to see output

fetch_weather
Fetch the weather for a given location.
{
"$defs": {
  "Location": {
    "properties": {
      "lat": {
        "title": "Lat",
        "type": "number"
      },
      "long": {
        "title": "Long",
        "type": "number"
      }
    },
    "required": [
      "lat",
      "long"
    ],
    "title": "Location",
    "type": "object"
  }
},
"properties": {
  "location": {
    "$ref": "#/$defs/Location",
    "description": "The location to fetch the weather for."
  }
},
"required": [
  "location"
],
"title": "fetch_weather_args",
"type": "object"
}

fetch_data
Read the contents of a file.
{
"properties": {
  "path": {
    "description": "The path to the file to read.",
    "title": "Path",
    "type": "string"
  },
  "directory": {
    "anyOf": [
      {
        "type": "string"
      },
      {
        "type": "null"
      }
    ],
    "default": null,
    "description": "The directory to read the file from.",
    "title": "Directory"
  }
},
"required": [
  "path"
],
"title": "fetch_data_args",
"type": "object"
}

Returning images or files from function tools

In addition to returning text outputs, you can return one or many images or files as the output of a function tool. To do so, you can return any of:

• Images: ToolOutputImage (or the TypedDict version, ToolOutputImageDict)
• Files: ToolOutputFileContent (or the TypedDict version, ToolOutputFileContentDict)
• Text: either a string or stringable objects, or ToolOutputText (or the TypedDict version, ToolOutputTextDict)

Custom function tools

Sometimes, you don't want to use a Python function as a tool. You can directly create a FunctionTool if you prefer. You'll need to provide:

• name
• description
• params_json_schema, which is the JSON schema for the arguments
• on_invoke_tool, which is an async function that receives a ToolContext and the arguments as a JSON string, and returns tool output (for example, text, structured tool output objects, or a list of outputs).

from typing import Any

from pydantic import BaseModel

from agents import RunContextWrapper, FunctionTool



def do_some_work(data: str) -> str:
    return "done"


class FunctionArgs(BaseModel):
    username: str
    age: int


async def run_function(ctx: RunContextWrapper[Any], args: str) -> str:
    parsed = FunctionArgs.model_validate_json(args)
    return do_some_work(data=f"{parsed.username} is {parsed.age} years old")


tool = FunctionTool(
    name="process_user",
    description="Processes extracted user data",
    params_json_schema=FunctionArgs.model_json_schema(),
    on_invoke_tool=run_function,
)

Automatic argument and docstring parsing

As mentioned before, we automatically parse the function signature to extract the schema for the tool, and we parse the docstring to extract descriptions for the tool and for individual arguments. Some notes on that:

1. The signature parsing is done via the inspect module. We use type annotations to understand the types for the arguments, and dynamically build a Pydantic model to represent the overall schema. It supports most types, including Python primitives, Pydantic models, TypedDicts, and more.
2. We use griffe to parse docstrings. Supported docstring formats are google, sphinx and numpy. We attempt to automatically detect the docstring format, but this is best-effort and you can explicitly set it when calling function_tool. You can also disable docstring parsing by setting use_docstring_info to False.

The code for the schema extraction lives in agents.function_schema.

Constraining and describing arguments with Pydantic Field

You can use Pydantic's Field to add constraints (e.g. min/max for numbers, length or pattern for strings) and descriptions to tool arguments. As in Pydantic, both forms are supported: default-based (arg: int = Field(..., ge=1)) and Annotated (arg: Annotated[int, Field(..., ge=1)]). The generated JSON schema and validation include these constraints.

from typing import Annotated
from pydantic import Field
from agents import function_tool

# Default-based form
@function_tool
def score_a(score: int = Field(..., ge=0, le=100, description="Score from 0 to 100")) -> str:
    return f"Score recorded: {score}"

# Annotated form
@function_tool
def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score from 0 to 100")]) -> str:
    return f"Score recorded: {score}"

Function tool timeouts

You can set per-call timeouts for async function tools with @function_tool(timeout=...).

import asyncio
from agents import Agent, Runner, function_tool


@function_tool(timeout=2.0)
async def slow_lookup(query: str) -> str:
    await asyncio.sleep(10)
    return f"Result for {query}"


agent = Agent(
    name="Timeout demo",
    instructions="Use tools when helpful.",
    tools=[slow_lookup],
)

When a timeout is reached, the default behavior is timeout_behavior="error_as_result", which sends a model-visible timeout message (for example, Tool 'slow_lookup' timed out after 2 seconds.).

You can control timeout handling:

• timeout_behavior="error_as_result" (default): return a timeout message to the model so it can recover.
• timeout_behavior="raise_exception": raise ToolTimeoutError and fail the run.
• timeout_error_function=...: customize the timeout message when using error_as_result.

import asyncio
from agents import Agent, Runner, ToolTimeoutError, function_tool


@function_tool(timeout=1.5, timeout_behavior="raise_exception")
async def slow_tool() -> str:
    await asyncio.sleep(5)
    return "done"


agent = Agent(name="Timeout hard-fail", tools=[slow_tool])

try:
    await Runner.run(agent, "Run the tool")
except ToolTimeoutError as e:
    print(f"{e.tool_name} timed out in {e.timeout_seconds} seconds")

Note

Timeout configuration is supported only for async @function_tool handlers.

Handling errors in function tools

When you create a function tool via @function_tool, you can pass a failure_error_function. This is a function that provides an error response to the LLM in case the tool call crashes.

• By default (i.e. if you don't pass anything), it runs a default_tool_error_function which tells the LLM an error occurred.
• If you pass your own error function, it runs that instead, and sends the response to the LLM.
• If you explicitly pass None, then any tool call errors will be re-raised for you to handle. This could be a ModelBehaviorError if the model produced invalid JSON, or a UserError if your code crashed, etc.

from agents import function_tool, RunContextWrapper
from typing import Any

def my_custom_error_function(context: RunContextWrapper[Any], error: Exception) -> str:
    """A custom function to provide a user-friendly error message."""
    print(f"A tool call failed with the following error: {error}")
    return "An internal server error occurred. Please try again later."

@function_tool(failure_error_function=my_custom_error_function)
def get_user_profile(user_id: str) -> str:
    """Fetches a user profile from a mock API.
     This function demonstrates a 'flaky' or failing API call.
    """
    if user_id == "user_123":
        return "User profile for user_123 successfully retrieved."
    else:
        raise ValueError(f"Could not retrieve profile for user_id: {user_id}. API returned an error.")

If you are manually creating a FunctionTool object, then you must handle errors inside the on_invoke_tool function.

Agents as tools

In some workflows, you may want a central agent to orchestrate a network of specialized agents, instead of handing off control. You can do this by modeling agents as tools.

from agents import Agent, Runner
import asyncio

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You translate the user's message to Spanish",
)

french_agent = Agent(
    name="French agent",
    instructions="You translate the user's message to French",
)

orchestrator_agent = Agent(
    name="orchestrator_agent",
    instructions=(
        "You are a translation agent. You use the tools given to you to translate."
        "If asked for multiple translations, you call the relevant tools."
    ),
    tools=[
        spanish_agent.as_tool(
            tool_name="translate_to_spanish",
            tool_description="Translate the user's message to Spanish",
        ),
        french_agent.as_tool(
            tool_name="translate_to_french",
            tool_description="Translate the user's message to French",
        ),
    ],
)

async def main():
    result = await Runner.run(orchestrator_agent, input="Say 'Hello, how are you?' in Spanish.")
    print(result.final_output)

Customizing tool-agents

The agent.as_tool function is a convenience method to make it easy to turn an agent into a tool. It supports common runtime options such as max_turns, run_config, hooks, previous_response_id, conversation_id, session, and needs_approval. It also supports structured input with parameters, input_builder, and include_input_schema. For advanced orchestration (for example, conditional retries, fallback behavior, or chaining multiple agent calls), use Runner.run directly in your tool implementation:

@function_tool
async def run_my_agent() -> str:
    """A tool that runs the agent with custom configs"""

    agent = Agent(name="My agent", instructions="...")

    result = await Runner.run(
        agent,
        input="...",
        max_turns=5,
        run_config=...
    )

    return str(result.final_output)

Structured input for tool-agents

By default, Agent.as_tool() expects a single string input ({"input": "..."}), but you can expose a structured schema by passing parameters (a Pydantic model or dataclass type).

Additional options:

• include_input_schema=True includes the full JSON Schema in the generated nested input.
• input_builder=... lets you fully customize how structured tool arguments become nested agent input.
• RunContextWrapper.tool_input contains the parsed structured payload inside the nested run context.

from pydantic import BaseModel, Field


class TranslationInput(BaseModel):
    text: str = Field(description="Text to translate.")
    source: str = Field(description="Source language.")
    target: str = Field(description="Target language.")


translator_tool = translator_agent.as_tool(
    tool_name="translate_text",
    tool_description="Translate text between languages.",
    parameters=TranslationInput,
    include_input_schema=True,
)

See examples/agent_patterns/agents_as_tools_structured.py for a complete runnable example.

Approval gates for tool-agents

Agent.as_tool(..., needs_approval=...) uses the same approval flow as function_tool. If approval is required, the run pauses and pending items appear in result.interruptions; then use result.to_state() and resume after calling state.approve(...) or state.reject(...). See the Human-in-the-loop guide for the full pause/resume pattern.

Custom output extraction

In certain cases, you might want to modify the output of the tool-agents before returning it to the central agent. This may be useful if you want to:

• Extract a specific piece of information (e.g., a JSON payload) from the sub-agent's chat history.
• Convert or reformat the agent’s final answer (e.g., transform Markdown into plain text or CSV).
• Validate the output or provide a fallback value when the agent’s response is missing or malformed.

You can do this by supplying the custom_output_extractor argument to the as_tool method:

async def extract_json_payload(run_result: RunResult) -> str:
    # Scan the agent’s outputs in reverse order until we find a JSON-like message from a tool call.
    for item in reversed(run_result.new_items):
        if isinstance(item, ToolCallOutputItem) and item.output.strip().startswith("{"):
            return item.output.strip()
    # Fallback to an empty JSON object if nothing was found
    return "{}"


json_tool = data_agent.as_tool(
    tool_name="get_data_json",
    tool_description="Run the data agent and return only its JSON payload",
    custom_output_extractor=extract_json_payload,
)

Streaming nested agent runs

Pass an on_stream callback to as_tool to listen to streaming events emitted by the nested agent while still returning its final output once the stream completes.

from agents import AgentToolStreamEvent


async def handle_stream(event: AgentToolStreamEvent) -> None:
    # Inspect the underlying StreamEvent along with agent metadata.
    print(f"[stream] {event['agent'].name} :: {event['event'].type}")


billing_agent_tool = billing_agent.as_tool(
    tool_name="billing_helper",
    tool_description="Answer billing questions.",
    on_stream=handle_stream,  # Can be sync or async.
)

What to expect:

• Event types mirror StreamEvent["type"]: raw_response_event, run_item_stream_event, agent_updated_stream_event.
• Providing on_stream automatically runs the nested agent in streaming mode and drains the stream before returning the final output.
• The handler may be synchronous or asynchronous; each event is delivered in order as it arrives.
• tool_call is present when the tool is invoked via a model tool call; direct calls may leave it None.
• See examples/agent_patterns/agents_as_tools_streaming.py for a complete runnable sample.

Conditional tool enabling

You can conditionally enable or disable agent tools at runtime using the is_enabled parameter. This allows you to dynamically filter which tools are available to the LLM based on context, user preferences, or runtime conditions.

import asyncio
from agents import Agent, AgentBase, Runner, RunContextWrapper
from pydantic import BaseModel

class LanguageContext(BaseModel):
    language_preference: str = "french_spanish"

def french_enabled(ctx: RunContextWrapper[LanguageContext], agent: AgentBase) -> bool:
    """Enable French for French+Spanish preference."""
    return ctx.context.language_preference == "french_spanish"

# Create specialized agents
spanish_agent = Agent(
    name="spanish_agent",
    instructions="You respond in Spanish. Always reply to the user's question in Spanish.",
)

french_agent = Agent(
    name="french_agent",
    instructions="You respond in French. Always reply to the user's question in French.",
)

# Create orchestrator with conditional tools
orchestrator = Agent(
    name="orchestrator",
    instructions=(
        "You are a multilingual assistant. You use the tools given to you to respond to users. "
        "You must call ALL available tools to provide responses in different languages. "
        "You never respond in languages yourself, you always use the provided tools."
    ),
    tools=[
        spanish_agent.as_tool(
            tool_name="respond_spanish",
            tool_description="Respond to the user's question in Spanish",
            is_enabled=True,  # Always enabled
        ),
        french_agent.as_tool(
            tool_name="respond_french",
            tool_description="Respond to the user's question in French",
            is_enabled=french_enabled,
        ),
    ],
)

async def main():
    context = RunContextWrapper(LanguageContext(language_preference="french_spanish"))
    result = await Runner.run(orchestrator, "How are you?", context=context.context)
    print(result.final_output)

asyncio.run(main())

The is_enabled parameter accepts:

• Boolean values: True (always enabled) or False (always disabled)
• Callable functions: Functions that take (context, agent) and return a boolean
• Async functions: Async functions for complex conditional logic

Disabled tools are completely hidden from the LLM at runtime, making this useful for:

• Feature gating based on user permissions
• Environment-specific tool availability (dev vs prod)
• A/B testing different tool configurations
• Dynamic tool filtering based on runtime state

Experimental: Codex tool

The codex_tool wraps the Codex CLI so an agent can run workspace-scoped tasks (shell, file edits, MCP tools) during a tool call. This surface is experimental and may change. By default, the tool name is codex. If you set a custom name, it must be codex or start with codex_. When an agent includes multiple Codex tools, each must use a unique name (including vs non-Codex tools).

from agents import Agent
from agents.extensions.experimental.codex import ThreadOptions, TurnOptions, codex_tool

agent = Agent(
    name="Codex Agent",
    instructions="Use the codex tool to inspect the workspace and answer the question.",
    tools=[
        codex_tool(
            sandbox_mode="workspace-write",
            working_directory="/path/to/repo",
            default_thread_options=ThreadOptions(
                model="gpt-5.2-codex",
                model_reasoning_effort="low",
                network_access_enabled=True,
                web_search_mode="disabled",
                approval_policy="never",
            ),
            default_turn_options=TurnOptions(
                idle_timeout_seconds=60,
            ),
            persist_session=True,
        )
    ],
)

What to know:

• Auth: set CODEX_API_KEY (preferred) or OPENAI_API_KEY, or pass codex_options={"api_key": "..."}.
• Runtime: codex_options.base_url overrides the CLI base URL.
• Binary resolution: set codex_options.codex_path_override (or CODEX_PATH) to pin the CLI path. Otherwise the SDK resolves codex from PATH, then falls back to the bundled vendor binary.
• Environment: codex_options.env fully controls the subprocess environment. When it is provided, the subprocess does not inherit os.environ.
• Stream limits: codex_options.codex_subprocess_stream_limit_bytes (or OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES) controls stdout/stderr reader limits. Valid range is 65536 to 67108864; default is 8388608.
• Inputs: tool calls must include at least one item in inputs with { "type": "text", "text": ... } or { "type": "local_image", "path": ... }.
• Thread defaults: configure default_thread_options for model_reasoning_effort, web_search_mode (preferred over legacy web_search_enabled), approval_policy, and additional_directories.
• Turn defaults: configure default_turn_options for idle_timeout_seconds and cancellation signal.
• Safety: pair sandbox_mode with working_directory; set skip_git_repo_check=True outside Git repos.
• Run-context thread persistence: use_run_context_thread_id=True stores and reuses thread_id in run context, across runs that share that context. This requires a mutable run context (for example, dict or a writable object field).
• Run-context key defaults: the stored key defaults to codex_thread_id for name="codex", or codex_thread_id_<suffix> for name="codex_<suffix>". Set run_context_thread_id_key to override.
• Thread ID precedence: per-call thread_id input takes priority, then run-context thread_id (if enabled), then the configured thread_id option.
• Streaming: on_stream receives thread/turn lifecycle events and item events (reasoning, command_execution, mcp_tool_call, file_change, web_search, todo_list, and error item updates).
• Outputs: results include response, usage, and thread_id; usage is added to RunContextWrapper.usage.
• Structure: output_schema enforces structured Codex responses when you need typed outputs.
• See examples/tools/codex.py and examples/tools/codex_same_thread.py for complete runnable samples.