OpenAI Agents SDK 中文文档 中文教程 （7）
英文文档原文详见 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里面了，大家可以到专栏里面看到所有的目录，欢迎订阅这个专栏。
目录
Streaming events
StreamEvent 模块属性
RawResponsesStreamEvent 数据类
data instance-attribute
类型 类-属性 实例-属性
RunItemStreamEvent 数据类
name 实例属性
item 实例属性
AgentUpdatedStreamEvent 数据类
new_agent instance-attribute
Handoffs
HandoffInputFilter 模块属性
HandoffInputData 数据类
input_history instance-attribute
pre_handoff_items instance-attribute
new_items instance-attribute
Handoff 数据类
tool_name instance-attribute
tool_description instance-attribute
input_json_schema instance-attribute
on_invoke_handoff instance-attribute
agent_name instance-attribute
input_filter 类属性 instance-attribute
strict_json_schema 类属性 instance-attribute
切换
Lifecycle
RunHooks
on_agent_start 异步
on_agent_end async
on_handoff async
on_tool_start async
on_tool_end async
代理钩子
on_start async
on_end async
on_handoff async
on_tool_start async
on_tool_end async
Streaming events
StreamEvent 模块属性
StreamEvent: TypeAlias = Union[
RawResponsesStreamEvent,
RunItemStreamEvent,
AgentUpdatedStreamEvent,
]
来自代理的流式处理事件。
RawResponsesStreamEvent 数据类
来自 LLM 的流式处理事件。这些是 “原始” 事件，即它们直接传递 来自 LLM。
源码src/agents/stream_events.py
|
|
|
data instance-attribute
data: TResponseStreamEvent
来自 LLM 的原始响应流式处理事件。
类型 类-属性 实例-属性
type: Literal['raw_response_event'] = 'raw_response_event'
事件的类型。
RunItemStreamEvent 数据类
将 .当代理处理 LLM 响应时，它将 为新消息、工具调用、工具输出、切换等生成这些事件。RunItem
src/agents/stream_events.py
|
|
|
name 实例属性
name: Literal[
"message_output_created",
"handoff_requested",
"handoff_occured",
"tool_called",
"tool_output",
"reasoning_item_created",
]
事件的名称。
item 实例属性
item: RunItem
创建的项。
AgentUpdatedStreamEvent 数据类
通知有新代理正在运行的事件。
源码src/agents/stream_events.py
|
|
|
new_agent instance-attribute
new_agent: Agent[Any]
新代理。
Handoffs
HandoffInputFilter 模块属性
HandoffInputFilter: TypeAlias = Callable[
[HandoffInputData], HandoffInputData
]
过滤传递给下一个代理的输入数据的函数。
HandoffInputData 数据类
src/agents/handoffs.py
|
|
|
input_history instance-attribute
input_history: str | tuple[TResponseInputItem, ...]
调用之前的输入历史记录。Runner.run()
pre_handoff_items instance-attribute
pre_handoff_items: tuple[RunItem, ...]
在代理轮到调用切换的位置之前生成的项目。
new_items instance-attribute
new_items: tuple[RunItem, ...]
当前代理回合期间生成的新物品，包括触发 Handoff 和表示 Handoff 输出响应的工具输出消息。
Handoff 数据类
基地：Generic[TContext]
移交是指代理将任务委派给另一个代理。 例如，在客户支持方案中，您可能有一个“分类代理”，它确定 哪个代理应该处理用户的请求，以及专门从事不同 计费、帐户管理等领域。
源码src/agents/handoffs.py
|
|
|
tool_name instance-attribute
tool_name: str
表示移交的工具的名称。
tool_description instance-attribute
tool_description: str
表示移交的工具的描述。
input_json_schema instance-attribute
input_json_schema: dict[str, Any]
移交输入的 JSON 架构。如果 handoff 不接受输入，则可以为空。
on_invoke_handoff instance-attribute
on_invoke_handoff: Callable[
[RunContextWrapper[Any], str],
Awaitable[Agent[TContext]],
]
调用 handoff 的函数。传递的参数包括： 1. handoff 运行上下文 2. 来自 LLM 的参数，以 JSON 字符串形式。如果 input_json_schema 为空，则为空字符串。
必须返回代理。
agent_name instance-attribute
agent_name: str
要移交给的代理的名称。
input_filter 类属性 instance-attribute
input_filter: HandoffInputFilter | None = None
过滤传递给下一个代理的输入的函数。默认情况下，新的 代理可以看到整个对话历史记录。在某些情况下，您可能希望过滤输入，例如 以删除较旧的输入，或从现有输入中删除工具。
该函数将接收到目前为止的整个对话历史记录，包括输入项 触发 Handoff 和表示 Handoff 工具输出的 Tool Call 输出项。
您可以根据需要自由修改输入历史记录或新项目。下一个代理 运行将接收 。handoff_input_data.all_items
重要提示：在流式处理模式下，我们不会因为此功能而流式处理任何内容。这 之前生成的项目已经被流式传输。
strict_json_schema 类属性 instance-attribute
strict_json_schema: bool = True
输入 JSON 架构是否处于严格模式。我们强烈建议将此设置为 True，因为它增加了正确 JSON 输入的可能性。
切换
handoff(
agent: Agent[TContext],
*,
tool_name_override: str | None = None,
tool_description_override: str | None = None,
input_filter: Callable[
[HandoffInputData], HandoffInputData
]
| None = None,
) -> Handoff[TContext]
handoff(
agent: Agent[TContext],
*,
on_handoff: OnHandoffWithInput[THandoffInput],
input_type: type[THandoffInput],
tool_description_override: str | None = None,
tool_name_override: str | None = None,
input_filter: Callable[
[HandoffInputData], HandoffInputData
]
| None = None,
) -> Handoff[TContext]
handoff(
agent: Agent[TContext],
*,
on_handoff: OnHandoffWithoutInput,
tool_description_override: str | None = None,
tool_name_override: str | None = None,
input_filter: Callable[
[HandoffInputData], HandoffInputData
]
| None = None,
) -> Handoff[TContext]
handoff(
agent: Agent[TContext],
tool_name_override: str | None = None,
tool_description_override: str | None = None,
on_handoff: OnHandoffWithInput[THandoffInput]
| OnHandoffWithoutInput
| None = None,
input_type: type[THandoffInput] | None = None,
input_filter: Callable[
[HandoffInputData], HandoffInputData
]
| None = None,
) -> Handoff[TContext]
从代理创建移交。
参数：
| 名字 | 类型 | 描述 | 违约 |
|---|---|---|---|
agent |
Agent[TContext] |
要移交给的代理，或返回代理的函数。 |
必填 |
tool_name_override |
str | None |
表示切换的工具名称的可选覆盖。 |
None |
tool_description_override |
str | None |
工具描述的可选 override 表示切换。 |
None |
on_handoff |
OnHandoffWithInput[THandoffInput] | OnHandoffWithoutInput | None |
在调用切换时运行的函数。 |
None |
input_type |
type[THandoffInput] | None |
移交的输入类型。如果提供，将验证输入 针对这种类型。仅当您传递的函数接受输入时才有意义。 |
None |
input_filter |
Callable[[HandoffInputData], HandoffInputData] | None |
一个函数，用于筛选传递给下一个代理的输入。 |
None |
Lifecycle
RunHooks
基地：Generic[TContext]
一个类，用于接收代理运行中各种生命周期事件的回调。Subclass 和 覆盖您需要的方法。
on_agent_start 异步
on_agent_start(
context: RunContextWrapper[TContext],
agent: Agent[TContext],
) -> None
在调用代理之前调用。每次当前代理更改时调用。
on_agent_end async
on_agent_end(
context: RunContextWrapper[TContext],
agent: Agent[TContext],
output: Any,
) -> None
当代理生成最终输出时调用。
on_handoff async
on_handoff(
context: RunContextWrapper[TContext],
from_agent: Agent[TContext],
to_agent: Agent[TContext],
) -> None
发生切换时调用。
on_tool_start async
on_tool_start(
context: RunContextWrapper[TContext],
agent: Agent[TContext],
tool: Tool,
) -> None
在调用工具之前调用。
on_tool_end async
on_tool_end(
context: RunContextWrapper[TContext],
agent: Agent[TContext],
tool: Tool,
result: str,
) -> None
在调用工具后调用。
代理钩子
基地：Generic[TContext]
一个类，用于接收特定代理的各种生命周期事件的回调。您可以 将此项设置为“打开”以接收该特定代理的事件。agent.hooks
子类化并覆盖您需要的方法。
on_start async
on_start(
context: RunContextWrapper[TContext],
agent: Agent[TContext],
) -> None
在调用代理之前调用。每次将正在运行的代理更改为此 代理。
on_end async
on_end(
context: RunContextWrapper[TContext],
agent: Agent[TContext],
output: Any,
) -> None
当代理生成最终输出时调用。
on_handoff async
on_handoff(
context: RunContextWrapper[TContext],
agent: Agent[TContext],
source: Agent[TContext],
) -> None
在将代理移交给时调用。是正在处理的代理 去这个代理。source
on_tool_start async
on_tool_start(
context: RunContextWrapper[TContext],
agent: Agent[TContext],
tool: Tool,
) -> None
在调用工具之前调用。
on_tool_end async
on_tool_end(
context: RunContextWrapper[TContext],
agent: Agent[TContext],
tool: Tool,
result: str,
) -> None
在调用工具后调用。