OpenAI Agents SDK 中文文档中文教程（7）-阿南达文事网

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

`Streaming events`

StreamEvent `模块属性`

代码语言：javascript代码运行次数：0运行复制

StreamEvent: TypeAlias = Union[
    RawResponsesStreamEvent,
    RunItemStreamEvent,
    AgentUpdatedStreamEvent,
]

来自代理的流式处理事件。

RawResponsesStreamEvent `数据类`

来自 LLM 的流式处理事件。这些是 “原始” 事件，即它们直接传递来自 LLM。

源码src/agents/stream_events.py

data `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

data: TResponseStreamEvent

来自 LLM 的原始响应流式处理事件。

类型 `类-属性` `实例-属性`

代码语言：javascript代码运行次数：0运行复制

type: Literal['raw_response_event'] = 'raw_response_event'

事件的类型。

RunItemStreamEvent `数据类`

将 .当代理处理 LLM 响应时，它将为新消息、工具调用、工具输出、切换等生成这些事件。RunItem

源码src/agents/stream_events.py

name `实例属性`

代码语言：javascript代码运行次数：0运行复制

name: Literal[
    "message_output_created",
    "handoff_requested",
    "handoff_occured",
    "tool_called",
    "tool_output",
    "reasoning_item_created",
]

事件的名称。

item `实例属性`

代码语言：javascript代码运行次数：0运行复制

item: RunItem

创建的项。

AgentUpdatedStreamEvent `数据类`

通知有新代理正在运行的事件。

源码src/agents/stream_events.py

new_agent `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

new_agent: Agent[Any]

新代理。

`Handoffs`

HandoffInputFilter `模块属性`

代码语言：javascript代码运行次数：0运行复制

HandoffInputFilter: TypeAlias = Callable[
    [HandoffInputData], HandoffInputData
]

过滤传递给下一个代理的输入数据的函数。

HandoffInputData `数据类`

源码src/agents/handoffs.py

input_history `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

input_history: str | tuple[TResponseInputItem, ...]

调用之前的输入历史记录。Runner.run()

pre_handoff_items `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

pre_handoff_items: tuple[RunItem, ...]

在代理轮到调用切换的位置之前生成的项目。

new_items `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

new_items: tuple[RunItem, ...]

当前代理回合期间生成的新物品，包括触发 Handoff 和表示 Handoff 输出响应的工具输出消息。

Handoff `数据类`

基地：Generic[TContext]

移交是指代理将任务委派给另一个代理。例如，在客户支持方案中，您可能有一个“分类代理”，它确定哪个代理应该处理用户的请求，以及专门从事不同计费、帐户管理等领域。

源码src/agents/handoffs.py

tool_name `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

tool_name: str

表示移交的工具的名称。

tool_description `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

tool_description: str

表示移交的工具的描述。

input_json_schema `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

input_json_schema: dict[str, Any]

移交输入的 JSON 架构。如果 handoff 不接受输入，则可以为空。

on_invoke_handoff `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

on_invoke_handoff: Callable[
    [RunContextWrapper[Any], str],
    Awaitable[Agent[TContext]],
]

调用 handoff 的函数。传递的参数包括： 1. handoff 运行上下文 2. 来自 LLM 的参数，以 JSON 字符串形式。如果 input_json_schema 为空，则为空字符串。

必须返回代理。

agent_name `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

agent_name: str

要移交给的代理的名称。

input_filter `类属性` `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

input_filter: HandoffInputFilter | None = None

过滤传递给下一个代理的输入的函数。默认情况下，新的代理可以看到整个对话历史记录。在某些情况下，您可能希望过滤输入，例如以删除较旧的输入，或从现有输入中删除工具。

该函数将接收到目前为止的整个对话历史记录，包括输入项触发 Handoff 和表示 Handoff 工具输出的 Tool Call 输出项。

您可以根据需要自由修改输入历史记录或新项目。下一个代理运行将接收。handoff_input_data.all_items

重要提示：在流式处理模式下，我们不会因为此功能而流式处理任何内容。这之前生成的项目已经被流式传输。

strict_json_schema `类属性` `instance-attribute`

代码语言：javascript代码运行次数：0运行复制

strict_json_schema: bool = True

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

切换

代码语言：javascript代码运行次数：0运行复制

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]

代码语言：javascript代码运行次数：0运行复制

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]

代码语言：javascript代码运行次数：0运行复制

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]

代码语言：javascript代码运行次数：0运行复制

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 `异步`

代码语言：javascript代码运行次数：0运行复制

on_agent_start(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
) -> None

在调用代理之前调用。每次当前代理更改时调用。

on_agent_end `async`

代码语言：javascript代码运行次数：0运行复制

on_agent_end(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    output: Any,
) -> None

当代理生成最终输出时调用。

on_handoff `async`

代码语言：javascript代码运行次数：0运行复制

on_handoff(
    context: RunContextWrapper[TContext],
    from_agent: Agent[TContext],
    to_agent: Agent[TContext],
) -> None

发生切换时调用。

on_tool_start `async`

代码语言：javascript代码运行次数：0运行复制

on_tool_start(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    tool: Tool,
) -> None

在调用工具之前调用。

on_tool_end `async`

代码语言：javascript代码运行次数：0运行复制

on_tool_end(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    tool: Tool,
    result: str,
) -> None

在调用工具后调用。

代理钩子

基地：Generic[TContext]

一个类，用于接收特定代理的各种生命周期事件的回调。您可以将此项设置为“打开”以接收该特定代理的事件。agent.hooks

子类化并覆盖您需要的方法。

on_start `async`

代码语言：javascript代码运行次数：0运行复制

on_start(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
) -> None

在调用代理之前调用。每次将正在运行的代理更改为此代理。

on_end `async`

代码语言：javascript代码运行次数：0运行复制

on_end(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    output: Any,
) -> None

当代理生成最终输出时调用。

on_handoff `async`

代码语言：javascript代码运行次数：0运行复制

on_handoff(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    source: Agent[TContext],
) -> None

在将代理移交给时调用。是正在处理的代理去这个代理。source

on_tool_start `async`

代码语言：javascript代码运行次数：0运行复制

on_tool_start(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    tool: Tool,
) -> None

在调用工具之前调用。

on_tool_end `async`

代码语言：javascript代码运行次数：0运行复制

on_tool_end(
    context: RunContextWrapper[TContext],
    agent: Agent[TContext],
    tool: Tool,
    result: str,
) -> None

在调用工具后调用。

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。原始发表：2025-03-17，如有侵权请联系 cloudcommunity@tencent 删除sdkopenai代理工具教程

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