OpenAI Agents SDK 中文文档 中文教程 （6）

英文文档原文详见 OpenAI Agents SDK

/

Tools

工具 module-attribute

Tool = Union[
    FunctionTool,
    FileSearchTool,
    WebSearchTool,
    ComputerTool,
]

可在代理中使用的工具。

FunctionTool 数据类

包装函数的工具。在大多数情况下，您应该使用帮助程序来 创建一个 FunctionTool，因为它们让你可以轻松地包装一个 Python 函数。function_tool

源码 src/agents/tool.py

name 实例属性

name: str

工具的名称，如 LLM 所示。通常是函数的名称。

描述 instance-attribute

description: str

工具的描述，如 LLM 所示。

params_json_schema instance-attribute

params_json_schema: dict[str, Any]

工具参数的 JSON 架构。

on_invoke_tool instance-attribute

on_invoke_tool: Callable[
    [RunContextWrapper[Any], str], Awaitable[str]
]

使用给定上下文和参数调用工具的函数。传递的参数 是： 1. 工具运行上下文。 2. 来自 LLM 的参数，以 JSON 字符串形式。

您必须返回工具输出的字符串表示。如果出现错误，您可以执行以下任一作 引发 Exception （这将导致运行失败） 或返回字符串错误消息 （该 将被发送回 LLM）。

strict_json_schema 类属性 instance-attribute

strict_json_schema: bool = True

JSON 架构是否处于严格模式。我们强烈建议将此设置为 True， 因为它增加了正确 JSON 输入的可能性。

FileSearchTool 数据类

一个托管工具，允许 LLM 在向量存储中进行搜索。目前仅支持 OpenAI 模型，使用响应 API。

源码 src/agents/tool.py

vector_store_ids instance-attribute

vector_store_ids: list[str]

要搜索的向量存储的 ID。

max_num_results 类属性 instance-attribute

max_num_results: int | None = None

要返回的最大结果数。

include_search_results 类属性实例属性

include_search_results: bool = False

是否将搜索结果包含在 LLM 生成的输出中。

ranking_options 类属性 instance-attribute

ranking_options: RankingOptions | None = None

搜索的排名选项。

filters 类-属性 instance-attribute

filters: Filters | None = None

要根据文件属性应用的过滤器。

WebSearchTool 数据类

一个托管工具，可让 LLM 搜索 Web。目前仅支持 OpenAI 模型， 使用响应 API。

源码 src/agents/tool.py

user_location 类属性 instance-attribute

user_location: UserLocation | None = None

搜索的可选位置。允许您自定义结果以与位置相关。

search_context_size 类属性实例属性

search_context_size: Literal["low", "medium", "high"] = (
    "medium"
)

用于搜索的上下文量。

ComputerTool 数据类

一个托管工具，可让 LLM 控制计算机。

源码 src/agents/tool.py

computer instance-attribute

computer: Computer | AsyncComputer

计算机实现，描述计算机的环境和尺寸， 以及实现单击、屏幕截图等计算机作。

default_tool_error_function

default_tool_error_function(
    ctx: RunContextWrapper[Any], error: Exception
) -> str

默认工具 error 函数，它只返回一般错误消息。

源码 src/agents/tool.py

function_tool

function_tool(
    func: ToolFunction[...],
    *,
    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 = None,
) -> FunctionTool

function_tool(
    *,
    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 = None,
) -> Callable[[ToolFunction[...]], FunctionTool]

function_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,
) -> (
    FunctionTool
    | Callable[[ToolFunction[...]], FunctionTool]
)

Decorator 从函数创建 FunctionTool。默认情况下，我们将： 1. 解析函数签名，为工具的参数创建 JSON 架构。 2. 使用函数的文档字符串填充工具的描述。 3. 使用函数的文档字符串填充参数描述。 系统会自动检测文档字符串样式，但您可以覆盖它。

如果函数将 a 作为第一个参数，则它必须与 使用该工具的代理程序的 context 类型。RunContextWrapper

参数：

Results

RunResultBase 数据类

基地：ABC

源码src/agents/result.py

input 实例属性

input: str | list[TResponseInputItem]

原始输入项，即调用 run（） 之前的项。这可能是一个 mutated version （如果存在改变输入的 Handoff 输入过滤器）。

new_items instance-attribute

new_items: list[RunItem]

代理运行期间生成的新项目。这些包括新消息、工具 调用及其输出等。

raw_responses instance-attribute

raw_responses: list[ModelResponse]

模型在代理运行期间生成的原始 LLM 响应。

final_output instance-attribute

final_output: Any

最后一个代理的输出。

input_guardrail_results instance-attribute

input_guardrail_results: list[InputGuardrailResult]

输入消息的护栏结果。

output_guardrail_results instance-attribute

output_guardrail_results: list[OutputGuardrailResult]

代理的最终输出的 Guardrail 结果。

last_agent abstractmethod 属性

last_agent: Agent[Any]

运行的最后一个代理程序。

final_output_as

final_output_as(
    cls: type[T], raise_if_incorrect_type: bool = False
) -> T

一种将最终输出强制转换为特定类型的便捷方法。默认情况下，强制转换 仅适用于 Typechecker。如果设置为 True，我们将引发一个 TypeError 如果最终输出不是给定类型。raise_if_incorrect_type

参数：

返回：

源码src/agents/result.py

to_input_list

to_input_list() -> list[TResponseInputItem]

创建新的输入列表，将原始输入与生成的所有新项合并。

源码src/agents/result.py

RunResult 数据类

基地：RunResultBase

源码src/agents/result.py

last_agent 属性

last_agent: Agent[Any]

运行的最后一个代理程序。

RunResultStreaming 数据类

基地：RunResultBase

代理在流式处理模式下运行的结果。您可以使用该方法 在生成语义事件时接收语义事件。stream_events

流式处理方法将引发： - 如果代理超过max_turns限制，则出现 MaxTurnsExceeded 异常。 - 如果护栏跳闸，则出现 GuardrailTripwireTriggered 异常。

源码src/agents/result.py

current_agent instance-attribute

current_agent: Agent[Any]

当前正在运行的代理。

current_turn instance-attribute

current_turn: int

当前轮次编号。

max_turns instance-attribute

max_turns: int

代理可以运行的最大轮次。

final_output instance-attribute

final_output: Any

代理的最终输出。在代理完成运行之前，此字段为 None。

is_complete 类属性 instance-attribute

is_complete: bool = False

代理是否已完成运行。

last_agent 属性

last_agent: Agent[Any]

运行的最后一个代理程序。随着代理运行的进行而更新，因此真正的最后一个代理 仅在代理运行完成后可用。

stream_events async

stream_events() -> AsyncIterator[StreamEvent]

在生成新项时流式传输新项的增量。我们使用的是 OpenAI 响应 API，所以这些是语义事件：每个事件都有一个字段 描述事件的类型以及该事件的数据。type

这将引发： - 如果代理超过max_turns限制，则出现 MaxTurnsExceeded 异常。 - 如果护栏跳闸，则出现 GuardrailTripwireTriggered 异常。