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]]