OpenAI Agents SDK 中文文档 中文教程 （8）
英文文档原文详见 OpenAI Agents SDK
https://openai.github.io/openai-agents-python/
本文是OpenAI-agents-sdk-python使用翻译软件翻译后的中文文档/教程。分多个帖子发布，帖子的目录如下：
(1) OpenAI 代理 SDK， 介绍及快速入门
(2)OpenAI agents sdk, agents，运行agents，结果，流，工具，交接
(3) OpenAi agents sdk, 跟踪，上下文管理，护栏
(4) Openai agents sdk, 编排多个代理，模型，配置SDK
(5)(6)..等等，后面的都放到openai agents sdk的这个专栏https://blog.csdn.net/wtsolutions/category_12916751.html里面了，大家可以到专栏里面看到所有的目录，欢迎订阅这个专栏。
目录
Items
TResponse module-attribute
TResponseInputItem module-attribute
TResponseOutputItem module-attribute
TResponseStreamEvent 模块属性
ToolCallItemTypes 模块属性
RunItem module-attribute
RunItemBase 数据类
agent instance-attribute
raw_item instance-attribute
to_input_item
MessageOutputItem 数据类
raw_item instance-attribute
HandoffCallItem 数据类
raw_item instance-attribute
HandoffOutputItem 数据类
raw_item instance-attribute
source_agent instance-attribute
target_agent instance-attribute
ToolCallItem 数据类
raw_item instance-attribute
ToolCallOutputItem 数据类
raw_item instance-attribute
output 实例属性
ReasoningItem 数据类
raw_item instance-attribute
ModelResponse 数据类
output 实例属性
usage 实例属性
referenceable_id instance-attribute
to_input_items
ItemHelpers
extract_last_content 类方法
extract_last_text 类方法
input_to_new_input_list 类方法
text_message_outputs 类方法
text_message_output 类方法
tool_call_output_item 类方法
Run context
RunContextWrapper 数据类
context 实例属性
usage 类-attribute 实例-属性
Usage
使用情况 数据类
requests 类-属性-实例-属性
input_tokens 类属性 instance-attribute
output_tokens 类属性实例属性
total_tokens 类属性 instance-attribute
Exceptions
AgentsException （代理例外）
超出最大转数
ModelBehaviorError
UserError （用户错误）
InputGuardrailTripwire触发
guardrail_result instance-attribute
OutputGuardrailTripwire触发
guardrail_result instance-attribute
Guardrails
GuardrailFunctionOutput 数据类
output_info instance-attribute
tripwire_triggered instance-attribute
InputGuardrailResult 数据类
护栏 实例属性
output 实例属性
OutputGuardrailResult 数据类
护栏 实例属性
agent_output instance-attribute
agent instance-attribute
output 实例属性
InputGuardrail 数据类
guardrail_function instance-attribute
name 类-属性-实例-属性
OutputGuardrail 数据类
guardrail_function instance-attribute
name 类-属性-实例-属性
input_guardrail
output_guardrail
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(...): ...