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

Items

TResponse module-attribute

TResponse = Response

OpenAI SDK 中 Response 类型的类型别名。

TResponseInputItem module-attribute

TResponseInputItem = ResponseInputItemParam

OpenAI SDK 中 ResponseInputItemParam 类型的类型别名。

TResponseOutputItem module-attribute

TResponseOutputItem = ResponseOutputItem

OpenAI 开发工具包中 ResponseOutputItem 类型的类型别名。

TResponseStreamEvent 模块属性

TResponseStreamEvent = ResponseStreamEvent

OpenAI SDK 中 ResponseStreamEvent 类型的类型别名。

ToolCallItemTypes 模块属性

ToolCallItemTypes: TypeAlias = Union[
    ResponseFunctionToolCall,
    ResponseComputerToolCall,
    ResponseFileSearchToolCall,
    ResponseFunctionWebSearch,
]

表示工具调用项的类型。

RunItem module-attribute

RunItem: TypeAlias = Union[
    MessageOutputItem,
    HandoffCallItem,
    HandoffOutputItem,
    ToolCallItem,
    ToolCallOutputItem,
    ReasoningItem,
]

由代理生成的项目。

RunItemBase 数据类

基地：Generic[T]ABC

源码src/agents/items.py

agent instance-attribute

agent: Agent[Any]

运行导致生成此项目的代理。

raw_item instance-attribute

raw_item: T

运行中的原始 Responses 项。这将始终是一个输出项（即 或输入项 （即 ）。openai.types.responses.ResponseOutputItemopenai.types.responses.ResponseInputItemParam

to_input_item

to_input_item() -> TResponseInputItem

将此项转换为适合传递给模型的输入项。

源码src/agents/items.py

MessageOutputItem 数据类

基地：RunItemBase[ResponseOutputMessage]

表示来自 LLM 的消息。

源码src/agents/items.py

raw_item instance-attribute

raw_item: ResponseOutputMessage

原始响应输出消息。

HandoffCallItem 数据类

基地：RunItemBase[ResponseFunctionToolCall]

表示从一个代理切换到另一个代理的工具调用。

源码src/agents/items.py

raw_item instance-attribute

raw_item: ResponseFunctionToolCall

表示切换的原始响应函数工具调用。

HandoffOutputItem 数据类

基地：RunItemBase[TResponseInputItem]

表示 handoff 的输出。

源码src/agents/items.py

raw_item instance-attribute

raw_item: TResponseInputItem

表示正在进行的切换的原始输入项。

source_agent instance-attribute

source_agent: Agent[Any]

进行交接的代理。

target_agent instance-attribute

target_agent: Agent[Any]

正在移交给的代理。

ToolCallItem 数据类

基地：RunItemBase[ToolCallItemTypes]

表示工具调用，例如函数调用或计算机作调用。

源码src/agents/items.py

raw_item instance-attribute

raw_item: ToolCallItemTypes

原始工具调用项。

ToolCallOutputItem 数据类

基地：RunItemBase[Union[FunctionCallOutput, ComputerCallOutput]]

表示工具调用的输出。

源码src/agents/items.py

raw_item instance-attribute

raw_item: FunctionCallOutput | ComputerCallOutput

模型中的原始项。

output 实例属性

output: str

工具调用的输出。

ReasoningItem 数据类

基地：RunItemBase[ResponseReasoningItem]

表示推理项。

源码src/agents/items.py

raw_item instance-attribute

raw_item: ResponseReasoningItem

原始推理项。

ModelResponse 数据类

源码src/agents/items.py

output 实例属性

output: list[TResponseOutputItem]

模型生成的输出（消息、工具调用等）列表

usage 实例属性

usage: Usage

响应的使用情况信息。

referenceable_id instance-attribute

referenceable_id: str | None

响应的 ID，可用于在对 型。并非所有模型提供程序都支持。

to_input_items

to_input_items() -> list[TResponseInputItem]

将输出转换为适合传递给模型的输入项列表。

源码src/agents/items.py

ItemHelpers

源码src/agents/items.py

extract_last_content 类方法

extract_last_content(message: TResponseOutputItem) -> str

从消息中提取最后一个文本内容或拒绝。

源码src/agents/items.py

extract_last_text 类方法

extract_last_text(
    message: TResponseOutputItem,
) -> str | None

从消息中提取最后一个文本内容（如果有）。忽略拒绝。

源码src/agents/items.py

input_to_new_input_list 类方法

input_to_new_input_list(
    input: str | list[TResponseInputItem],
) -> list[TResponseInputItem]

将字符串或输入项列表转换为输入项列表。

源码src/agents/items.py

text_message_outputs 类方法

text_message_outputs(items: list[RunItem]) -> str

连接消息输出项列表中的所有文本内容。

源码src/agents/items.py

text_message_output 类方法

text_message_output(message: MessageOutputItem) -> str

从单个消息输出项中提取所有文本内容。

源码src/agents/items.py

tool_call_output_item 类方法

tool_call_output_item(
    tool_call: ResponseFunctionToolCall, output: str
) -> FunctionCallOutput

从工具调用及其输出创建工具调用输出项。

Run context

RunContextWrapper 数据类

基地：Generic[TContext]

这将包装您传递给 的 context 对象。它还包含 到目前为止代理运行的使用情况的信息。Runner.run()

注意：上下文不会传递给 LLM。它们是将依赖项和数据传递给代码的一种方式 您实现工具函数、回调、钩子等。

源码src/agents/run_context.py

context 实例属性

context: TContext

上下文对象（或 None），由您传递给Runner.run()

usage 类-attribute 实例-属性

usage: Usage = field(default_factory=Usage)

到目前为止，代理的使用情况正在运行。对于流式响应，在 处理流的最后一个块。

Usage

使用情况 数据类

源码src/agents/usage.py

requests 类-属性-实例-属性

requests: int = 0

向 LLM API 发出的请求总数。

input_tokens 类属性 instance-attribute

input_tokens: int = 0

在所有请求中发送的输入令牌总数。

output_tokens 类属性实例属性

output_tokens: int = 0

所有请求中收到的输出令牌总数。

total_tokens 类属性 instance-attribute

total_tokens: int = 0

所有请求中发送和接收的令牌总数。

Exceptions

AgentsException （代理例外）

基地：Exception

代理 SDK 中所有异常的基类。

源码src/agents/exceptions.py

超出最大转数

基地：AgentsException

当超过最大圈数时引发异常。

源码src/agents/exceptions.py

ModelBehaviorError

基地：AgentsException

当模型执行意外作时引发异常，例如调用未执行 存在或提供格式错误的 JSON。

源码src/agents/exceptions.py

UserError （用户错误）

基地：AgentsException

当用户使用 SDK 出错时引发异常。

源码src/agents/exceptions.py

InputGuardrailTripwire触发

基地：AgentsException

触发护栏绊线时引发异常。

源码src/agents/exceptions.py

guardrail_result instance-attribute

guardrail_result: InputGuardrailResult = guardrail_result

触发的护栏的结果数据。

OutputGuardrailTripwire触发

基地：AgentsException

触发护栏绊线时引发异常。

源码src/agents/exceptions.py

guardrail_result instance-attribute

guardrail_result: OutputGuardrailResult = guardrail_result

触发的护栏的结果数据。

Guardrails

GuardrailFunctionOutput 数据类

护栏函数的输出。

源码src/agents/guardrail.py

output_info instance-attribute

output_info: Any

有关护栏输出的可选信息。例如，护栏可以包括 有关它执行的检查的信息和精细结果。

tripwire_triggered instance-attribute

tripwire_triggered: bool

绊线是否已触发。如果触发，代理的执行将停止。

InputGuardrailResult 数据类

护栏运行的结果。

源码src/agents/guardrail.py

护栏 实例属性

guardrail: InputGuardrail[Any]

运行的护栏。

output 实例属性

output: GuardrailFunctionOutput

护栏函数的输出。

OutputGuardrailResult 数据类

护栏运行的结果。

源码src/agents/guardrail.py

护栏 实例属性

guardrail: OutputGuardrail[Any]

运行的护栏。

agent_output instance-attribute

agent_output: Any

护栏检查的代理的输出。

agent instance-attribute

agent: Agent[Any]

护栏检查的代理。

output 实例属性

output: GuardrailFunctionOutput

护栏函数的输出。

InputGuardrail 数据类

基地：Generic[TContext]

输入护栏是与代理执行并行运行的检查。 它们可用于执行以下作： - 检查输入的消息是否偏离主题 - 如果检测到意外输入，则接管代理执行的控制权

你可以使用装饰器将函数转换为 ， 或 手动创建。@input_guardrail()InputGuardrailInputGuardrail

护栏返回 .如果 是 ，则代理 执行将立即停止并引发异常GuardrailResultresult.tripwire_triggeredTrueInputGuardrailTripwireTriggered

源码src/agents/guardrail.py

guardrail_function instance-attribute

guardrail_function: Callable[
    [
        RunContextWrapper[TContext],
        Agent[Any],
        str | list[TResponseInputItem],
    ],
    MaybeAwaitable[GuardrailFunctionOutput],
]

一个函数，用于接收代理输入和上下文，并返回一个 .结果标记绊线是否被触发，并且可以选择选择 包括有关 Guardrail 输出的信息。GuardrailResult

name 类-属性-实例-属性

name: str | None = None

护栏的名称，用于跟踪。如果未提供，我们将使用护栏 函数的名称。

OutputGuardrail 数据类

基地：Generic[TContext]

输出护栏是在代理的最终输出上运行的检查。 它们可用于检查输出是否通过某些验证标准

你可以使用装饰器将函数转换为 ， 或手动创建一个。@output_guardrail()OutputGuardrailOutputGuardrail

护栏返回 .如果是 ，将引发异常。GuardrailResultresult.tripwire_triggeredTrueOutputGuardrailTripwireTriggered

源码src/agents/guardrail.py

guardrail_function instance-attribute

guardrail_function: Callable[
    [RunContextWrapper[TContext], Agent[Any], Any],
    MaybeAwaitable[GuardrailFunctionOutput],
]

一个函数，它接收最终代理、其输出和上下文，并返回一个 .结果标记绊线是否被触发，并且可以选择选择 包括有关 Guardrail 输出的信息。GuardrailResult

name 类-属性-实例-属性

name: str | None = None

护栏的名称，用于跟踪。如果未提供，我们将使用护栏 函数的名称。

input_guardrail

input_guardrail(
    func: _InputGuardrailFuncSync[TContext_co],
) -> InputGuardrail[TContext_co]

input_guardrail(
    func: _InputGuardrailFuncAsync[TContext_co],
) -> InputGuardrail[TContext_co]

input_guardrail(
    *, name: str | None = None
) -> Callable[
    [
        _InputGuardrailFuncSync[TContext_co]
        | _InputGuardrailFuncAsync[TContext_co]
    ],
    InputGuardrail[TContext_co],
]

input_guardrail(
    func: _InputGuardrailFuncSync[TContext_co]
    | _InputGuardrailFuncAsync[TContext_co]
    | None = None,
    *,
    name: str | None = None,
) -> (
    InputGuardrail[TContext_co]
    | Callable[
        [
            _InputGuardrailFuncSync[TContext_co]
            | _InputGuardrailFuncAsync[TContext_co]
        ],
        InputGuardrail[TContext_co],
    ]
)

将 sync 或 async 函数转换为 . 它可以直接使用（无括号）或与关键字 args 一起使用，例如：InputGuardrail

@input_guardrail
def my_sync_guardrail(...): ...

@input_guardrail(name="guardrail_name")
async def my_async_guardrail(...): ...

源码src/agents/guardrail.py

output_guardrail

output_guardrail(
    func: _OutputGuardrailFuncSync[TContext_co],
) -> OutputGuardrail[TContext_co]

output_guardrail(
    func: _OutputGuardrailFuncAsync[TContext_co],
) -> OutputGuardrail[TContext_co]

output_guardrail(
    *, name: str | None = None
) -> Callable[
    [
        _OutputGuardrailFuncSync[TContext_co]
        | _OutputGuardrailFuncAsync[TContext_co]
    ],
    OutputGuardrail[TContext_co],
]

output_guardrail(
    func: _OutputGuardrailFuncSync[TContext_co]
    | _OutputGuardrailFuncAsync[TContext_co]
    | None = None,
    *,
    name: str | None = None,
) -> (
    OutputGuardrail[TContext_co]
    | Callable[
        [
            _OutputGuardrailFuncSync[TContext_co]
            | _OutputGuardrailFuncAsync[TContext_co]
        ],
        OutputGuardrail[TContext_co],
    ]
)

将 sync 或 async 函数转换为 . 它可以直接使用（无括号）或与关键字 args 一起使用，例如：OutputGuardrail

@output_guardrail
def my_sync_guardrail(...): ...

@output_guardrail(name="guardrail_name")
async def my_async_guardrail(...): ...