OpenAI Agents SDK：工具与将 Agent 用作工具OpenAI Agents SDK: 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: execute for the model on OpenAI servers.
• Local/runtime execution tools: ComputerTool and ApplyPatchTool always run in your environment, while ShellTool can run locally or in a hosted container.
• FunctionTool instances: 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.

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.
• The ToolSearchTool lets the model load deferred tools, namespaces, or hosted MCP servers on demand.
• The ProgrammaticToolCallingTool lets the model coordinate eligible tools from generated JavaScript.

Advanced hosted search options:

• FileSearchTool supports filters, ranking_options, and include_search_results in addition to vector_store_ids and max_num_results. Set max_num_results to an integer from 1 through 50; None or zero uses the provider default.
• WebSearchTool supports filters, user_location, search_context_size, external_web_access, search_content_types, and image_settings.

Set search_content_types to include "image" when the web search should return images, and also include "text" when the model needs supporting text results. image_settings.max_results requests a positive number of image results, while image_settings.caption requests short descriptions when available. When "image" is present, the SDK automatically requests web_search_call.results. Those raw results are stored on the web_search_call item in RunResult.raw_responses, separately from the assistant message, and can include image_url, source_website_url, thumbnail_url, and caption. See the OpenAI image search results guide.

Hosted tool search

Tool search lets OpenAI Responses models defer large tool surfaces until runtime, so the model loads only the subset it needs for the current turn. This is useful when you have many function tools, namespace groups, or hosted MCP servers and want to reduce tool-schema tokens without exposing every tool up front.

Start with hosted tool search when the candidate tools are already known when you build the agent. If your application needs to decide what to load dynamically, the Responses API also supports client-executed tool search, but the standard Runner does not auto-execute that mode.

What to know:

• Hosted tool search is available only with OpenAI Responses models.
• Add exactly one ToolSearchTool() when you configure deferred-loading surfaces on an agent.
• Searchable surfaces include @function_tool(defer_loading=True), tool_namespace(name=..., description=..., tools=[...]), and HostedMCPTool(tool_config={..., "defer_loading": True}).
• Deferred-loading function tools must be paired with ToolSearchTool(). Namespace-only setups may also use ToolSearchTool() to let the model load the right group on demand.
• tool_namespace() groups FunctionTool instances under a shared namespace name and description. This is usually the best fit when you have many related tools, such as crm, billing, or shipping.
• OpenAI's official best-practice guidance is Use namespaces where possible.
• Prefer namespaces or hosted MCP servers over many individually deferred functions when possible. They usually give the model a better high-level search surface and better token savings.
• Namespaces can mix immediate and deferred tools. Tools without defer_loading=True remain callable immediately, while deferred tools in the same namespace are loaded through tool search.
• As a rule of thumb, keep each namespace fairly small, ideally fewer than 10 functions.
• Named tool_choice cannot target bare namespace names or deferred-only tools. Prefer auto, required, or a real top-level callable tool name.
• ToolSearchTool(execution="client") is for manual Responses orchestration. If the model emits a client-executed tool_search_call, the standard Runner raises instead of executing it for you.
• Tool search activity appears in RunResult.new_items and in RunItemStreamEvent with dedicated item and event types.
• See examples/tools/tool_search.py for complete runnable examples covering both namespaced loading and top-level deferred tools.
• Official platform guide: Tool search.

Programmatic Tool Calling

Programmatic Tool Calling lets a supported OpenAI Responses model generate JavaScript that calls eligible tools, combines their outputs, and returns one result to the model. It is useful for bounded workflows that benefit from loops, branching, parallel calls, or intermediate calculations without a model round trip after every tool call.

The generated program runs in a fresh hosted V8 environment. It does not have Node.js APIs, filesystem or network access, or a persistent process. The program can interact only with tools that you explicitly allow.

What to know:

• Programmatic Tool Calling is available only with supported OpenAI Responses models. ProgrammaticToolCallingTool() and tool_choice="programmatic_tool_calling" are rejected by Chat Completions models and non-Responses backends.
• Add at most one ProgrammaticToolCallingTool() to an agent. The agent must also expose at least one programmatically callable tool, a ToolSearchTool() backed by a namespace, deferred function, or deferred hosted MCP server, or an opaque prompt-managed tool surface. A bare ToolSearchTool() without a searchable surface is rejected.
• allowed_callers controls how a tool may be invoked. Omitting it allows direct model calls only. Use ["programmatic"] for program-only access or ["direct", "programmatic"] to allow both.
• SDK tool types that can opt in are FunctionTool, CustomTool, ShellTool, ApplyPatchTool, HostedMCPTool, and CodeInterpreterTool. Function, custom, shell, and apply-patch tools expose allowed_callers directly. For hosted MCP and code interpreter, set allowed_callers inside tool_config.
• For @function_tool(allowed_callers=[...]), a structured return annotation such as a Pydantic model, TypedDict, or dataclass automatically becomes a strict object output schema, and the returned value is validated against that schema before it is returned to the program. Use output_type=... when the function has no usable annotation, or the lower-level output_json_schema={...} escape hatch when you already have a strict object schema. output_type and output_json_schema are mutually exclusive. Return annotations of str, Any, or None do not create an output schema. For a schema-backed program-owned call, the default failure formatter is disabled because its free-form text does not satisfy the output schema. A handler exception therefore propagates unless you provide a custom failure_error_function that returns schema-conforming JSON.
• Program-owned SDK tools still use the normal Runner lifecycle. Tool input and output guardrails, hooks, timeouts, concurrency limits, approvals, sessions, and RunState pause/resume behavior continue to apply, and the SDK preserves each child call's program caller relationship.
• Model-request retries use a stricter replay-safety boundary whenever ProgrammaticToolCallingTool() is present, even before a program executes. The SDK disables provider-managed retries and WebSocket pre-event retries for these requests. A Runner retry policy retries only when provider advice explicitly marks the replay safe; retry_policies.network_error() by itself does not override this boundary.
• Approval-sensitive or high-impact tools are usually better kept as direct calls so a person can review each action before it becomes part of a larger program. If a program-owned call pauses for approval, resolve the interruption through RunState and resume the original run as usual.
• Programmatic Tool Calling can be combined with hosted tool search. The model must load deferred tools before a generated program can call them.
• A program item and its ordinary program-owned child tool calls appear as ToolCallItem entries. The matching program_output appears as a ToolCallOutputItem. Hosted MCP approval requests and tool catalogs use specialized MCP items and stream events instead. See Results and Streaming for inspection details.
• See examples/tools/programmatic_tool_calling.py for a complete concurrent inventory-planning example.
• Official platform guide: Programmatic Tool Calling.

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.

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 outside the model response itself. The model still decides when to call them, but your application or configured execution environment performs the actual work.

ComputerTool and ApplyPatchTool always require local implementations that you provide. ShellTool spans both modes: use the hosted-container configuration above when you want managed execution, or the local runtime configuration below when you want commands to run in your own process.

Local runtime tools 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": [...]}).

Shell action timeouts use positive integer milliseconds for a finite timeout. The SDK treats both 0 and None as no explicit timeout before calling a local ShellTool executor because zero does not have a portable meaning across executor implementations; other values are rejected before executor invocation. This is specific to the timeout field: max_output_length=0 remains a supported request for empty captured output.

Approval for local shell and file edits

Local ShellTool and ApplyPatchTool default to needs_approval=False. With this setting, the SDK can invoke your executor or editor without requesting approval. Your implementation determines where commands run or files change and must enforce the intended resource permissions and isolation; SDK approval does not provide a sandbox.

For commands or file edits that require review, set needs_approval=True on the tool, or provide a callable policy that returns True for calls that require approval. Without an on_approval callback, the run pauses before invoking the executor or editor and returns pending requests in result.interruptions. Approve or reject those requests through RunState, then resume the run as described in the human-in-the-loop guide.

To decide immediately in application code, set both needs_approval and on_approval. The SDK invokes on_approval only when the call requires approval and has no existing approval decision; setting the callback alone does not enable approval. See examples/tools/shell.py for a CLI prompt and examples/tools/shell_human_in_the_loop.py for manual interruption handling. The examples/tools/apply_patch.py example instead prompts inside its editor before changing files.

Keep needs_approval=False when your application intentionally authorizes automatic execution, for example through an executor that enforces your sandbox policy. Hosted shell environments do not support the SDK's local needs_approval or on_approval settings.

ComputerTool and the Responses computer tool

ComputerTool is still a local harness: you provide a Computer or AsyncComputer implementation, and the SDK maps that harness onto the OpenAI Responses API computer surface.

When an Agent does not set model, normal SDK model-selection precedence applies. The built-in SDK default, currently gpt-5.6-luna, supports computer use. If OPENAI_DEFAULT_MODEL or RunConfig.model overrides that default, select a model that supports computer use. Set model on the agent when you want to choose a different capability and cost profile for the computer-use workload. The example below uses the gpt-5.6 alias, which OpenAI routes to GPT-5.6 Sol; you can instead select another model that supports computer use, such as GPT-5.6 Terra or GPT-5.6 Luna.

For explicit requests to a model that supports the GA built-in computer tool, such as gpt-5.6, the SDK sends the payload {"type": "computer"}. For requests to the older computer-use-preview model, the SDK continues to send the preview payload {"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}. This mirrors the platform's migration from computer-use-preview:

• Model: computer-use-preview -> gpt-5.6-sol
• Tool selector: computer_use_preview -> computer
• Computer call shape: one action per computer_call -> batched actions[] on computer_call
• Truncation: ModelSettings(truncation="auto") required on the preview path -> not required on the GA path

The SDK chooses that wire shape from the effective model on the actual Responses request. If you use a prompt template and the request omits model because the prompt owns it, the SDK keeps the preview-compatible computer payload unless you either make a supported GA model such as model="gpt-5.6" explicit or force the GA selector with ModelSettings(tool_choice="computer") or ModelSettings(tool_choice="computer_use").

When a ComputerTool is present, tool_choice="computer", "computer_use", and "computer_use_preview" are all accepted and normalized to the built-in selector that matches the effective request model. Without a ComputerTool, those strings still behave like ordinary function names.

This distinction matters when ComputerTool is backed by a ComputerProvider factory. The GA computer payload does not need environment or dimensions at serialization time, so serialization can occur before a factory has produced a Computer or AsyncComputer instance. Preview-compatible serialization still needs a resolved Computer or AsyncComputer instance so the SDK can send environment, display_width, and display_height.

At runtime, both paths still use the same local harness. Preview responses emit computer_call items with a single action; GA responses can emit batched actions[], and the SDK executes them in order before producing a computer_call_output screenshot item. See examples/tools/computer_use.py for a runnable Playwright-based harness.

Pending computer safety checks

The Responses API can include pending_safety_checks in a computer_call to flag concerns for your application to review. Each check has an id and optional code and message fields that describe the type of concern and provide details. These checks come from the API; the Agents SDK passes them to your callback. See the Responses API reference for pending_safety_checks and acknowledged_safety_checks, and the computer-use safety guidance for application-level precautions.

Configure ComputerTool.on_safety_check to decide whether to proceed with a flagged computer call. The SDK invokes this callback only when the call includes pending checks, before executing the call's actions.

The callback receives one ComputerToolSafetyCheckData at a time. Return True to acknowledge that check. Return False to raise UserError before the call's actions or screenshot execute. The SDK requires all reported checks to be acknowledged when a callback is configured. The callback can be synchronous or asynchronous.

If on_safety_check is omitted, the SDK proceeds with execution and leaves the checks unacknowledged. The SDK does not prompt a person automatically. Configure the callback explicitly when your application requires review of flagged calls. For example, this conservative policy rejects every flagged call:

To allow reviewed calls, replace reject_flagged_call with a callback that presents data.safety_check and the proposed data.tool_call to your application's reviewer, waits for a decision, and returns that decision. Treat unknown check codes as requiring review as well.

Computer calls without pending checks do not invoke this callback. Enforce any policy that must apply to every computer action in your computer harness. To collect a person's decision, your callback must arrange that interaction and return the decision; the SDK does not populate RunResult.interruptions or use the pause-and-resume flow described in Human-in-the-loop.

Function tools

You can use any Python function as a tool. The Agents SDK will set up 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

Tools created by @tool expose the original Python callable through the read-only __wrapped__ attribute. This is useful for inspection and testing, but calling it directly bypasses the tool runtime pipeline, including schema validation, context injection, guardrails, timeouts, failure handling, and tracing. Hand-built FunctionTool instances do not expose __wrapped__.

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

When you are using OpenAI Responses models, @function_tool(defer_loading=True) hides a function tool until ToolSearchTool() loads it. You can also group related function tools with tool_namespace(). See Hosted tool search for the full setup and constraints.

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 run context as their 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

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).

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. For Google-style docstrings, the parser also accepts an Args:, Arguments:, Params:, or Parameters: section immediately after summary text without an intervening blank line.

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.

For variadic parameters, an annotation describes each collected value. The SDK therefore applies Annotated[..., Field(...)] constraints to each value supplied through *args or **kwargs, while omitted variadic parameters remain valid empty collections.

The SDK ignores Field(description=...) in the annotation of a variadic parameter (*args or **kwargs). To describe the collected parameter, use a parameter entry in the function docstring or a string in Annotated, for example *scores: Annotated[int, "Exam scores", Field(ge=0, le=100)]. When docstring parsing is enabled and both sources provide a description, the docstring description takes precedence.

For **kwargs, use @tool(strict_mode=False) and supply the keyword values in the nested object named after the parameter. For example, a tool with **scores: int receives {"scores": {"exam": 90}}.

Annotate scalar positional values as *args: T. If each positional value is itself a homogeneous tuple, use *args: tuple[T, ...]; the SDK rejects fixed-length tuple annotations such as *args: tuple[int, str] because one fixed tuple shape cannot describe a variadic sequence of positional values.

Function tool timeouts

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

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.

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.

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.

Customizing tool-agents

agent.as_tool is a convenience method for turning 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.

The state options configure the nested agent run started by the tool call; the parent run's conversation state is not inherited automatically. To share client-managed history between the parent and nested runs, explicitly pass the same session to both. As with Runner.run, choose one state strategy for the nested run: a client-managed session, or server-managed continuation through previous_response_id or conversation_id.

Structured input for tool-agents

By default, Agent.as_tool() expects an object with one string field, input ({"input": "..."}), but you can expose a structured schema by passing parameters (a Pydantic model type or a 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.

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:

Inside a custom extractor, the nested RunResult also exposes agent_tool_invocation, which is useful when you need the outer tool name, call ID, or raw arguments while post-processing the nested result. See the Results guide.

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.

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.

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:

• Request-scoped capability visibility
• Environment-specific tool availability (dev vs prod)
• A/B testing different tool configurations
• Dynamic tool filtering based on runtime state

For locally configured function tools, the runner also reevaluates is_enabled before invocation. However, is_enabled controls visibility and dispatch; it does not replace authorization that depends on the tool arguments or the resource being accessed. Enforce those checks inside the tool implementation, or use tool input guardrails and approvals when appropriate. MCP servers must authorize their own protected operations.

See context management for a pattern that applies one application policy across function tools, MCP tools, and handoffs.

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.

Use it when you want the main agent to delegate a bounded workspace task to Codex without leaving the current run. 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.

Start with these option groups:

• Execution surface: sandbox_mode and working_directory define where Codex can operate. Pair them together, and set skip_git_repo_check=True when the working directory is not inside a Git repository.
• Thread defaults: default_thread_options=ThreadOptions(...) configures the model, reasoning effort, approval policy, additional directories, network access, and web search mode. Prefer web_search_mode over the legacy web_search_enabled.
• Turn defaults: default_turn_options=TurnOptions(...) configures per-turn behavior such as idle_timeout_seconds and the optional cancellation signal.
• Tool I/O: tool calls must include at least one inputs item with { "type": "text", "text": ... } or { "type": "local_image", "path": ... }. output_schema lets you require structured Codex responses.

Thread reuse and persistence are separate controls:

• persist_session=True reuses one Codex thread for repeated calls to the same tool instance.
• use_run_context_thread_id=True stores and reuses the thread ID in run context across runs that share the same mutable context object.
• Thread ID precedence is: per-call thread_id, then run-context thread ID (if enabled), then the configured thread_id option.
• The default run-context key is codex_thread_id for name="codex" and codex_thread_id_<suffix> for name="codex_<suffix>". Override it with run_context_thread_id_key.

Runtime configuration:

• 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.
• 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.

Reference:

• Codex tool API reference
• ThreadOptions reference
• TurnOptions reference
• See examples/tools/codex.py and examples/tools/codex_same_thread.py for complete runnable samples.