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

 英文文档原文详见 OpenAI Agents SDKhttps://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.youkuaiyun.com/wtsolutions/category_12916751.html里面了，大家可以到专栏里面看到所有的目录，欢迎订阅这个专栏。

---

目录

代理模块

set_default_openai_key

set_default_openai_client

set_default_openai_api

set_tracing_export_api_key

set_tracing_disabled

set_trace_processors

enable_verbose_stdout_logging

Agents

代理 数据类

name 实例属性

instructions 类-属性 instance-attribute

handoff_description 类属性 instance-attribute

handoffs 类-attribute 实例-属性

model 类-属性 instance-attribute

model_settings 类属性实例属性

tools 类-属性 instance-attribute

input_guardrails 类属性实例属性

output_guardrails 类属性 instance-attribute

output_type 类属性 instance-attribute

hooks 类属性 instance-attribute

克隆

as_tool

get_system_prompt async

Runner

跑步者

Run async 类方法

run_sync 类方法

run_streamed classmethod

RunConfig dataclass

model class-attribute instance-attribute

model_provider class-attribute instance-attribute

model_settings class-attribute instance-attribute

handoff_input_filter class-attribute instance-attribute

input_guardrails class-attribute instance-attribute

output_guardrails class-attribute instance-attribute

tracing_disabled class-attribute instance-attribute

trace_include_sensitive_data 类属性 instance-attribute

workflow_name 类属性 instance-attribute

trace_id 类属性 instance-attribute

group_id 类属性实例属性

trace_metadata 类属性实例属性

---

代理模块

set_default_openai_key

set_default_openai_key(
    key: str, use_for_tracing: bool = True
) -> None

设置用于 LLM 请求的默认 OpenAI API 密钥（以及可选的 tracing（））。这是 仅当尚未设置 OPENAI_API_KEY 环境变量时才需要。

如果提供，将使用此键而不是 OPENAI_API_KEY 环境变量。

参数：

名字	类型	描述	违约
key	str	要使用的 OpenAI 密钥。	必填
use_for_tracing	bool	是否也使用此 key 向 OpenAI 发送跟踪。默认为 True 如果为 False，则需要设置 OPENAI_API_KEY 环境变量或调用 set_tracing_export_api_key（） 替换为要用于跟踪的 API 密钥。	True

源码 src/agents/__init__.py

set_default_openai_client

set_default_openai_client(
    client: AsyncOpenAI, use_for_tracing: bool = True
) -> None

设置用于 LLM 请求和/或跟踪的默认 OpenAI 客户端。如果提供，则此 client 而不是默认的 OpenAI 客户端。

参数：

名字	类型	描述	违约
client	AsyncOpenAI	要使用的 OpenAI 客户端。	必填
use_for_tracing	bool	是否使用此客户端的 API 密钥上传跟踪。如果为 False，则 您需要设置 OPENAI_API_KEY 环境变量或调用 set_tracing_export_api_key（） 替换为要用于跟踪的 API 密钥。	True

源码 src/agents/__init__.py

set_default_openai_api

set_default_openai_api(
    api: Literal["chat_completions", "responses"],
) -> None

设置用于 OpenAI LLM 请求的默认 API。默认情况下，我们将使用响应 API 但你可以将其设置为改用聊天补全 API。

源码 src/agents/__init__.py

set_tracing_export_api_key

set_tracing_export_api_key(api_key: str) -> None

设置后端导出器的 OpenAI API 密钥。

源码 src/agents/tracing/__init__.py

set_tracing_disabled

set_tracing_disabled(disabled: bool) -> None

设置是否全局禁用跟踪。

源码 src/agents/tracing/__init__.py

set_trace_processors

set_trace_processors(
    processors: list[TracingProcessor],
) -> None

设置跟踪处理器列表。这将替换当前的处理器列表。

源码 src/agents/tracing/__init__.py

enable_verbose_stdout_logging

enable_verbose_stdout_logging()

启用对 stdout 的详细日志记录。这对于调试很有用。

源码 src/agents/__init__.py

Agents

代理 数据类

基地：Generic[TContext]

代理是一种 AI 模型，配置了说明、工具、护栏、交接等。

我们强烈建议传递 ，这是代理的 “system prompt”。在 此外，您还可以将 ，这是代理的人类可读描述，用于 在 Tools/Handoffs 中使用代理时。instructionsdescription

代理在上下文类型上是通用的。上下文是您创建的 （可变） 对象。是的 传递给工具函数、交接、护栏等。

源码 src/agents/agent.py

name 实例属性

name: str

代理的名称。

instructions 类-属性 instance-attribute

instructions: (
    str
    | Callable[
        [RunContextWrapper[TContext], Agent[TContext]],
        MaybeAwaitable[str],
    ]
    | None
) = None

代理的说明。当这个 agent 是 时，会作为 “system prompt” 调用。描述代理应执行的作以及它的响应方式。

可以是字符串，也可以是为代理动态生成指令的函数。如果 您提供了一个函数，它将使用 Context 和 Agent 实例调用。它必须 返回一个字符串。

handoff_description 类属性 instance-attribute

handoff_description: str | None = None

代理的描述。当代理用作切换时，会使用此 URL，以便 LLM 知道它的作用以及何时调用它。

handoffs 类-attribute 实例-属性

handoffs: list[Agent[Any] | Handoff[TContext]] = field(
    default_factory=list
)

Handoff 是代理可以委派给的子代理。您可以提供 handoffs 列表， 代理可以选择委托给他们（如果相关）。允许分离关注点和 模块性。

model 类-属性 instance-attribute

model: str | Model | None = None

调用 LLM 时要使用的模型实现。

默认情况下，如果未设置，代理将使用 中配置的默认模型。model_settings.DEFAULT_MODEL

model_settings 类属性实例属性

model_settings: ModelSettings = field(
    default_factory=ModelSettings
)

配置特定于模型的优化参数（例如 temperature、top_p）。

tools 类-属性 instance-attribute

tools: list[Tool] = field(default_factory=list)

代理可以使用的工具列表。

input_guardrails 类属性实例属性

input_guardrails: list[InputGuardrail[TContext]] = field(
    default_factory=list
)

在生成 响应。仅当代理是链中的第一个代理时，才运行。

output_guardrails 类属性 instance-attribute

output_guardrails: list[OutputGuardrail[TContext]] = field(
    default_factory=list
)

生成响应后，对代理的最终输出运行的检查列表。 仅当代理生成最终输出时运行。

output_type 类属性 instance-attribute

output_type: type[Any] | None = None

输出对象的类型。如果未提供，则输出将为 。str

hooks 类属性 instance-attribute

hooks: AgentHooks[TContext] | None = None

一个类，用于接收此代理的各种生命周期事件的回调。

克隆

clone(**kwargs: Any) -> Agent[TContext]

创建代理的副本，并更改给定的参数。例如，您可以执行以下作：

new_agent = agent.clone(instructions="New instructions")

源码 src/agents/agent.py

as_tool

as_tool(
    tool_name: str | None,
    tool_description: str | None,
    custom_output_extractor: Callable[
        [RunResult], Awaitable[str]
    ]
    | None = None,
) -> Tool

将此代理转换为可由其他代理调用的工具。

这与 handoffs 在两个方面不同： 1. 在交接中，新座席会收到对话历史记录。在此工具中，新代理 接收生成的 Input。 2. 在交接中，新座席接管对话。在此工具中，新代理是 作为工具调用，并且对话由原始代理继续。

参数：

名字	类型	描述	违约
tool_name	str | None	工具的名称。如果未提供，将使用代理的名称。	必填
tool_description	str | None	工具的描述，应说明它的作用以及 何时使用它。	必填
custom_output_extractor	Callable[[RunResult], Awaitable[str]] | None	从代理中提取输出的函数。如果不是 ，则将使用来自代理的最后一条消息。	None

源码 src/agents/agent.py

get_system_prompt async

get_system_prompt(
    run_context: RunContextWrapper[TContext],
) -> str | None

获取代理的系统提示符。

源码 src/agents/agent.py

Runner

跑步者

源码src/agents/run.py

Run async 类方法

run(
    starting_agent: Agent[TContext],
    input: str | list[TResponseInputItem],
    *,
    context: TContext | None = None,
    max_turns: int = DEFAULT_MAX_TURNS,
    hooks: RunHooks[TContext] | None = None,
    run_config: RunConfig | None = None,
) -> RunResult

从给定代理开始运行工作流程。代理将循环运行，直到最终 output 生成。循环运行如下： 1. 使用给定的输入调用代理。 2. 如果有最终输出（即代理生成 type 为 的东西），则循环终止。 3. 如果有切换，我们将使用新代理再次运行循环。 4. 否则，我们将运行工具调用（如果有），然后重新运行循环。agent.output_type

在两种情况下，代理可能会引发异常： 1. 如果超出max_turns，则会引发 MaxTurnsExceeded 异常。 2. 如果触发了护栏绊线，则会引发 GuardrailTripwireTriggered 异常。

请注意，仅运行第一个代理的输入护栏。

参数：

名字	类型	描述	违约
starting_agent	Agent[TContext]	要运行的启动代理。	必填
input	str | list[TResponseInputItem]	代理的初始输入。您可以为用户消息传递单个字符串 或输入项列表。	必填
context	TContext | None	用于运行代理的上下文。	None
max_turns	int	运行代理的最大轮次。一个转弯定义为 1 AI 调用（包括可能发生的任何工具调用）。	DEFAULT_MAX_TURNS
hooks	RunHooks[TContext] | None	一个对象，用于接收各种生命周期事件的回调。	None
run_config	RunConfig | None	整个代理运行的全局设置。	None

返回：

类型	描述
RunResult	包含所有输入、护栏结果和最后一个
RunResult	代理。代理可能会执行切换，因此我们不知道输出的具体类型。

源码src/agents/run.py

run_sync 类方法

run_sync(
    starting_agent: Agent[TContext],
    input: str | list[TResponseInputItem],
    *,
    context: TContext | None = None,
    max_turns: int = DEFAULT_MAX_TURNS,
    hooks: RunHooks[TContext] | None = None,
    run_config: RunConfig | None = None,
) -> RunResult

从给定代理开始同步运行工作流程。请注意，这只是包装了方法，因此如果已经存在一个事件循环（例如，在 async 中 函数，或者在 Jupyter 笔记本或异步上下文（如 FastAPI）中）。对于这些情况，请使用 方法。runrun

代理将在循环中运行，直到生成最终输出。循环运行如下： 1. 使用给定的输入调用代理。 2. 如果有最终输出（即代理生成 type 为 的东西），则循环终止。 3. 如果有切换，我们将使用新代理再次运行循环。 4. 否则，我们将运行工具调用（如果有），然后重新运行循环。agent.output_type

在两种情况下，代理可能会引发异常： 1. 如果超出max_turns，则会引发 MaxTurnsExceeded 异常。 2. 如果触发了护栏绊线，则会引发 GuardrailTripwireTriggered 异常。

请注意，仅运行第一个代理的输入护栏。

参数：

名字	类型	描述	违约
starting_agent	Agent[TContext]	要运行的启动代理。	必填
input	str | list[TResponseInputItem]	代理的初始输入。您可以为用户消息传递单个字符串 或输入项列表。	必填
context	TContext | None	用于运行代理的上下文。	None
max_turns	int	运行代理的最大轮次。一个转弯定义为 1 AI 调用（包括可能发生的任何工具调用）。	DEFAULT_MAX_TURNS
hooks	RunHooks[TContext] | None	一个对象，用于接收各种生命周期事件的回调。	None
run_config	RunConfig | None	整个代理运行的全局设置。	None

返回：

类型	描述
RunResult	包含所有输入、护栏结果和最后一个
RunResult	代理。代理可能会执行切换，因此我们不知道输出的具体类型。

源码src/agents/run.py

run_streamed 类方法

run_streamed(
    starting_agent: Agent[TContext],
    input: str | list[TResponseInputItem],
    context: TContext | None = None,
    max_turns: int = DEFAULT_MAX_TURNS,
    hooks: RunHooks[TContext] | None = None,
    run_config: RunConfig | None = None,
) -> RunResultStreaming

在流式处理模式下从给定代理运行工作流。返回的 result 对象 包含可用于在生成语义事件时对其进行流式处理的方法。

代理将在循环中运行，直到生成最终输出。循环运行如下： 1. 使用给定的输入调用代理。 2. 如果有最终输出（即代理生成 type 为 的东西），则循环终止。 3. 如果有切换，我们将使用新代理再次运行循环。 4. 否则，我们将运行工具调用（如果有），然后重新运行循环。agent.output_type

在两种情况下，代理可能会引发异常： 1. 如果超出max_turns，则会引发 MaxTurnsExceeded 异常。 2. 如果触发了护栏绊线，则会引发 GuardrailTripwireTriggered 异常。

请注意，仅运行第一个代理的输入护栏。

参数：

名字	类型	描述	违约
starting_agent	Agent[TContext]	要运行的启动代理。	必填
input	str | list[TResponseInputItem]	代理的初始输入。您可以为用户消息传递单个字符串 或输入项列表。	必填
context	TContext | None	用于运行代理的上下文。	None
max_turns	int	运行代理的最大轮次。一个转弯定义为 1 AI 调用（包括可能发生的任何工具调用）。	DEFAULT_MAX_TURNS
hooks	RunHooks[TContext] | None	一个对象，用于接收各种生命周期事件的回调。	None
run_config	RunConfig | None	整个代理运行的全局设置。	None

返回：

类型	描述
RunResultStreaming	一个 result 对象，其中包含有关运行的数据，以及用于流式传输事件的方法。

源码src/agents/run.py

RunConfig 数据类

配置整个代理程序运行的设置。

源码src/agents/run.py

model 类-属性 instance-attribute

model: str | Model | None = None

用于整个代理运行的模型。如果设置，将覆盖在每个 代理。下面传入的 model_provider 必须能够解析此模型名称。

model_provider 类属性实例属性

model_provider: ModelProvider = field(
    default_factory=OpenAIProvider
)

查找字符串模型名称时使用的模型提供程序。默认为 OpenAI。

model_settings 类属性实例属性

model_settings: ModelSettings | None = None

配置全局模型设置。任何非 null 值都将覆盖特定于代理的模型 设置。

handoff_input_filter 类属性实例属性

handoff_input_filter: HandoffInputFilter | None = None

应用于所有 handoff 的全局输入过滤器。如果已设置，则 将优先。输入过滤器允许您编辑发送到新 代理。有关更多详细信息，请参阅 中的文档。Handoff.input_filterHandoff.input_filter

input_guardrails 类属性实例属性

input_guardrails: list[InputGuardrail[Any]] | None = None

要在初始运行输入上运行的输入护栏列表。

output_guardrails 类属性 instance-attribute

output_guardrails: list[OutputGuardrail[Any]] | None = None

要在运行的最终输出上运行的输出护栏列表。

tracing_disabled 类属性 instance-attribute

tracing_disabled: bool = False

是否为代理运行禁用跟踪。如果禁用，我们将不会跟踪代理运行。

trace_include_sensitive_data 类属性 instance-attribute

trace_include_sensitive_data: bool = True

我们是否包含可能敏感的数据（例如：工具调用的输入/输出或 LLM 代）的 Trace 中。如果为 False，我们仍将为这些事件创建 span，但 敏感数据将不包括在内。

workflow_name 类属性 instance-attribute

workflow_name: str = 'Agent workflow'

运行的名称，用于跟踪。应该是运行的逻辑名称，例如 “代码生成工作流”或“客户支持代理”。

trace_id 类属性 instance-attribute

trace_id: str | None = None

用于跟踪的自定义跟踪 ID。如果未提供，我们将生成新的跟踪 ID。

group_id 类属性实例属性

group_id: str | None = None

用于跟踪的分组标识符，用于链接同一对话中的多个跟踪 或过程。例如，您可以使用聊天会话 ID。

trace_metadata 类属性实例属性

trace_metadata: dict[str, Any] | None = None

要包含在跟踪中的其他元数据的可选字典。