5354555657

classToolOutputText(BaseModel):"""Represents a tool output that should be sent to the model as text."""type:Literal["text"]="text"text:str

6061626364

classToolOutputTextDict(TypedDict,total=False):"""TypedDict variant for text tool outputs."""type:Literal["text"]text:str

676869707172737475767778798081828384

classToolOutputImage(BaseModel):"""Represents a tool output that should be sent to the model as an image.    You can provide either an `image_url` (URL or data URL) or a `file_id` for previously uploaded    content. The optional `detail` can control vision detail.    """type:Literal["image"]="image"image_url:str|None=Nonefile_id:str|None=Nonedetail:Literal["low","high","auto"]|None=None@model_validator(mode="after")defcheck_at_least_one_required_field(self)->ToolOutputImage:"""Validate that at least one of image_url or file_id is provided."""ifself.image_urlisNoneandself.file_idisNone:raiseValueError("At least one of image_url or file_id must be provided")returnself

87888990919293

classToolOutputImageDict(TypedDict,total=False):"""TypedDict variant for image tool outputs."""type:Literal["image"]image_url:NotRequired[str]file_id:NotRequired[str]detail:NotRequired[Literal["low","high","auto"]]

 96 97 98 99100101102103104105106107108109110111112113114

classToolOutputFileContent(BaseModel):"""Represents a tool output that should be sent to the model as a file.    Provide one of `file_data` (base64), `file_url`, or `file_id`. You may also    provide an optional `filename` when using `file_data` to hint file name.    """type:Literal["file"]="file"file_data:str|None=Nonefile_url:str|None=Nonefile_id:str|None=Nonefilename:str|None=None@model_validator(mode="after")defcheck_at_least_one_required_field(self)->ToolOutputFileContent:"""Validate that at least one of file_data, file_url, or file_id is provided."""ifself.file_dataisNoneandself.file_urlisNoneandself.file_idisNone:raiseValueError("At least one of file_data, file_url, or file_id must be provided")returnself

117118119120121122123124

classToolOutputFileContentDict(TypedDict,total=False):"""TypedDict variant for file content tool outputs."""type:Literal["file"]file_data:NotRequired[str]file_url:NotRequired[str]file_id:NotRequired[str]filename:NotRequired[str]

133134135136137138139140141142

@dataclassclassFunctionToolResult:tool:FunctionTool"""The tool that was run."""output:Any"""The output of the tool."""run_item:RunItem"""The run item that was produced as a result of the tool call."""

145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191

@dataclassclassFunctionTool:"""A tool that wraps a function. In most cases, you should use  the `function_tool` helpers to    create a FunctionTool, as they let you easily wrap a Python function.    """name:str"""The name of the tool, as shown to the LLM. Generally the name of the function."""description:str"""A description of the tool, as shown to the LLM."""params_json_schema:dict[str,Any]"""The JSON schema for the tool's parameters."""on_invoke_tool:Callable[[ToolContext[Any],str],Awaitable[Any]]"""A function that invokes the tool with the given context and parameters. The params passed    are:    1. The tool run context.    2. The arguments from the LLM, as a JSON string.    You must return a one of the structured tool output types (e.g. ToolOutputText, ToolOutputImage,    ToolOutputFileContent) or a string representation of the tool output, or a list of them,    or something we can call `str()` on.    In case of errors, you can either raise an Exception (which will cause the run to fail) or    return a string error message (which will be sent back to the LLM).    """strict_json_schema:bool=True"""Whether the JSON schema is in strict mode. We **strongly** recommend setting this to True,    as it increases the likelihood of correct JSON input."""is_enabled:bool|Callable[[RunContextWrapper[Any],AgentBase],MaybeAwaitable[bool]]=True"""Whether the tool is enabled. Either a bool or a Callable that takes the run context and agent    and returns whether the tool is enabled. You can use this to dynamically enable/disable a tool    based on your context/state."""# Tool-specific guardrailstool_input_guardrails:list[ToolInputGuardrail[Any]]|None=None"""Optional list of input guardrails to run before invoking this tool."""tool_output_guardrails:list[ToolOutputGuardrail[Any]]|None=None"""Optional list of output guardrails to run after invoking this tool."""def__post_init__(self):ifself.strict_json_schema:self.params_json_schema=ensure_strict_json_schema(self.params_json_schema)

194195196197198199200201202203204205206207208209210211212213214215216217

@dataclassclassFileSearchTool:"""A hosted tool that lets the LLM search through a vector store. Currently only supported with    OpenAI models, using the Responses API.    """vector_store_ids:list[str]"""The IDs of the vector stores to search."""max_num_results:int|None=None"""The maximum number of results to return."""include_search_results:bool=False"""Whether to include the search results in the output produced by the LLM."""ranking_options:RankingOptions|None=None"""Ranking options for search."""filters:Filters|None=None"""A filter to apply based on file attributes."""@propertydefname(self):return"file_search"

220221222223224225226227228229230231232233234235236237

@dataclassclassWebSearchTool:"""A hosted tool that lets the LLM search the web. Currently only supported with OpenAI models,    using the Responses API.    """user_location:UserLocation|None=None"""Optional location for the search. Lets you customize results to be relevant to a location."""filters:WebSearchToolFilters|None=None"""A filter to apply based on file attributes."""search_context_size:Literal["low","medium","high"]="medium""""The amount of context to use for the search."""@propertydefname(self):return"web_search"

240241242243244245246247248249250251252253254

@dataclassclassComputerTool:"""A hosted tool that lets the LLM control a computer."""computer:Computer|AsyncComputer"""The computer implementation, which describes the environment and dimensions of the computer,    as well as implements the computer actions like click, screenshot, etc.    """on_safety_check:Callable[[ComputerToolSafetyCheckData],MaybeAwaitable[bool]]|None=None"""Optional callback to acknowledge computer tool safety checks."""@propertydefname(self):return"computer_use_preview"

257258259260261262263264265266267268269270271

@dataclassclassComputerToolSafetyCheckData:"""Information about a computer tool safety check."""ctx_wrapper:RunContextWrapper[Any]"""The run context."""agent:Agent[Any]"""The agent performing the computer action."""tool_call:ResponseComputerToolCall"""The computer tool call."""safety_check:PendingSafetyCheck"""The pending safety check to acknowledge."""

274275276277278279280281282

@dataclassclassMCPToolApprovalRequest:"""A request to approve a tool call."""ctx_wrapper:RunContextWrapper[Any]"""The run context."""data:McpApprovalRequest"""The data from the MCP tool approval request."""

285286287288289290291292

classMCPToolApprovalFunctionResult(TypedDict):"""The result of an MCP tool approval function."""approve:bool"""Whether to approve the tool call."""reason:NotRequired[str]"""An optional reason, if rejected."""

301302303304305306307308309310311312313314315316317318319

@dataclassclassHostedMCPTool:"""A tool that allows the LLM to use a remote MCP server. The LLM will automatically list and    call tools, without requiring a round trip back to your code.    If you want to run MCP servers locally via stdio, in a VPC or other non-publicly-accessible    environment, or you just prefer to run tool calls locally, then you can instead use the servers    in `agents.mcp` and pass `Agent(mcp_servers=[...])` to the agent."""tool_config:Mcp"""The MCP tool config, which includes the server URL and other settings."""on_approval_request:MCPToolApprovalFunction|None=None"""An optional function that will be called if approval is requested for an MCP tool. If not    provided, you will need to manually add approvals/rejections to the input and call    `Runner.run(...)` again."""@propertydefname(self):return"hosted_mcp"

322323324325326327328329330331

@dataclassclassCodeInterpreterTool:"""A tool that allows the LLM to execute code in a sandboxed environment."""tool_config:CodeInterpreter"""The tool config, which includes the container and other settings."""@propertydefname(self):return"code_interpreter"

334335336337338339340341342343

@dataclassclassImageGenerationTool:"""A tool that allows the LLM to generate images."""tool_config:ImageGeneration"""The tool config, which image generation settings."""@propertydefname(self):return"image_generation"

346347348349350351352353354

@dataclassclassLocalShellCommandRequest:"""A request to execute a command on a shell."""ctx_wrapper:RunContextWrapper[Any]"""The run context."""data:LocalShellCall"""The data from the local shell tool call."""

361362363364365366367368369370371372373374

@dataclassclassLocalShellTool:"""A tool that allows the LLM to execute commands on a shell.    For more details, see:    https://platform.openai.com/docs/guides/tools-local-shell    """executor:LocalShellExecutor"""A function that executes a command on a shell."""@propertydefname(self):return"local_shell"

377378379380381382

@dataclassclassShellCallOutcome:"""Describes the terminal condition of a shell command."""type:Literal["exit","timeout"]exit_code:int|None=None

389390391392393394395396397398399400401402403404405

@dataclassclassShellCommandOutput:"""Structured output for a single shell command execution."""stdout:str=""stderr:str=""outcome:ShellCallOutcome=field(default_factory=_default_shell_outcome)command:str|None=Noneprovider_data:dict[str,Any]|None=None@propertydefexit_code(self)->int|None:returnself.outcome.exit_code@propertydefstatus(self)->Literal["completed","timeout"]:return"timeout"ifself.outcome.type=="timeout"else"completed"

408409410411412413414

@dataclassclassShellResult:"""Result returned by a shell executor."""output:list[ShellCommandOutput]max_output_length:int|None=Noneprovider_data:dict[str,Any]|None=None

417418419420421422423

@dataclassclassShellActionRequest:"""Action payload for a next-generation shell call."""commands:list[str]timeout_ms:int|None=Nonemax_output_length:int|None=None

426427428429430431432433

@dataclassclassShellCallData:"""Normalized shell call data provided to shell executors."""call_id:straction:ShellActionRequeststatus:Literal["in_progress","completed"]|None=Noneraw:Any|None=None

436437438439440441

@dataclassclassShellCommandRequest:"""A request to execute a modern shell call."""ctx_wrapper:RunContextWrapper[Any]data:ShellCallData

448449450451452453454455456457

@dataclassclassShellTool:"""Next-generation shell tool. LocalShellTool will be deprecated in favor of this."""executor:ShellExecutorname:str="shell"@propertydeftype(self)->str:return"shell"

460461462463464465466467468469

@dataclassclassApplyPatchTool:"""Hosted apply_patch tool. Lets the model request file mutations via unified diffs."""editor:ApplyPatchEditorname:str="apply_patch"@propertydeftype(self)->str:return"apply_patch"

487488489

defdefault_tool_error_function(ctx:RunContextWrapper[Any],error:Exception)->str:"""The default tool error function, which just returns a generic error message."""returnf"An error occurred while running the tool. Please try again. Error:{str(error)}"

526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674

deffunction_tool(func:ToolFunction[...]|None=None,*,name_override:str|None=None,description_override:str|None=None,docstring_style:DocstringStyle|None=None,use_docstring_info:bool=True,failure_error_function:ToolErrorFunction|None=default_tool_error_function,strict_mode:bool=True,is_enabled:bool|Callable[[RunContextWrapper[Any],AgentBase],MaybeAwaitable[bool]]=True,)->FunctionTool|Callable[[ToolFunction[...]],FunctionTool]:"""    Decorator to create a FunctionTool from a function. By default, we will:    1. Parse the function signature to create a JSON schema for the tool's parameters.    2. Use the function's docstring to populate the tool's description.    3. Use the function's docstring to populate argument descriptions.    The docstring style is detected automatically, but you can override it.    If the function takes a `RunContextWrapper` as the first argument, it *must* match the    context type of the agent that uses the tool.    Args:        func: The function to wrap.        name_override: If provided, use this name for the tool instead of the function's name.        description_override: If provided, use this description for the tool instead of the            function's docstring.        docstring_style: If provided, use this style for the tool's docstring. If not provided,            we will attempt to auto-detect the style.        use_docstring_info: If True, use the function's docstring to populate the tool's            description and argument descriptions.        failure_error_function: If provided, use this function to generate an error message when            the tool call fails. The error message is sent to the LLM. If you pass None, then no            error message will be sent and instead an Exception will be raised.        strict_mode: Whether to enable strict mode for the tool's JSON schema. We *strongly*            recommend setting this to True, as it increases the likelihood of correct JSON input.            If False, it allows non-strict JSON schemas. For example, if a parameter has a default            value, it will be optional, additional properties are allowed, etc. See here for more:            https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#supported-schemas        is_enabled: Whether the tool is enabled. Can be a bool or a callable that takes the run            context and agent and returns whether the tool is enabled. Disabled tools are hidden            from the LLM at runtime.    """def_create_function_tool(the_func:ToolFunction[...])->FunctionTool:schema=function_schema(func=the_func,name_override=name_override,description_override=description_override,docstring_style=docstring_style,use_docstring_info=use_docstring_info,strict_json_schema=strict_mode,)asyncdef_on_invoke_tool_impl(ctx:ToolContext[Any],input:str)->Any:try:json_data:dict[str,Any]=json.loads(input)ifinputelse{}exceptExceptionase:if_debug.DONT_LOG_TOOL_DATA:logger.debug(f"Invalid JSON input for tool{schema.name}")else:logger.debug(f"Invalid JSON input for tool{schema.name}:{input}")raiseModelBehaviorError(f"Invalid JSON input for tool{schema.name}:{input}")fromeif_debug.DONT_LOG_TOOL_DATA:logger.debug(f"Invoking tool{schema.name}")else:logger.debug(f"Invoking tool{schema.name} with input{input}")try:parsed=(schema.params_pydantic_model(**json_data)ifjson_dataelseschema.params_pydantic_model())exceptValidationErrorase:raiseModelBehaviorError(f"Invalid JSON input for tool{schema.name}:{e}")fromeargs,kwargs_dict=schema.to_call_args(parsed)ifnot_debug.DONT_LOG_TOOL_DATA:logger.debug(f"Tool call args:{args}, kwargs:{kwargs_dict}")ifinspect.iscoroutinefunction(the_func):ifschema.takes_context:result=awaitthe_func(ctx,*args,**kwargs_dict)else:result=awaitthe_func(*args,**kwargs_dict)else:ifschema.takes_context:result=the_func(ctx,*args,**kwargs_dict)else:result=the_func(*args,**kwargs_dict)if_debug.DONT_LOG_TOOL_DATA:logger.debug(f"Tool{schema.name} completed.")else:logger.debug(f"Tool{schema.name} returned{result}")returnresultasyncdef_on_invoke_tool(ctx:ToolContext[Any],input:str)->Any:try:returnawait_on_invoke_tool_impl(ctx,input)exceptExceptionase:iffailure_error_functionisNone:raiseresult=failure_error_function(ctx,e)ifinspect.isawaitable(result):returnawaitresult_error_tracing.attach_error_to_current_span(SpanError(message="Error running tool (non-fatal)",data={"tool_name":schema.name,"error":str(e),},))if_debug.DONT_LOG_TOOL_DATA:logger.debug(f"Tool{schema.name} failed")else:logger.error(f"Tool{schema.name} failed:{input}{e}",exc_info=e,)returnresultreturnFunctionTool(name=schema.name,description=schema.descriptionor"",params_json_schema=schema.params_json_schema,on_invoke_tool=_on_invoke_tool,strict_json_schema=strict_mode,is_enabled=is_enabled,)# If func is actually a callable, we were used as @function_tool with no parenthesesifcallable(func):return_create_function_tool(func)# Otherwise, we were used as @function_tool(...), so return a decoratordefdecorator(real_func:ToolFunction[...])->FunctionTool:return_create_function_tool(real_func)returndecorator