当前位置：首页 > news >正文

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

news 来源：原创 2025/8/16 12:57:53

英文文档原文详见 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.csdn.net/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. 如果超出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

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

代理模块

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 类方法

RunConfig 数据类

model 类-属性 instance-attribute

model_provider 类属性实例属性

model_settings 类属性实例属性

handoff_input_filter 类属性实例属性

input_guardrails 类属性实例属性

output_guardrails 类属性 instance-attribute

tracing_disabled 类属性 instance-attribute

trace_include_sensitive_data 类属性 instance-attribute

workflow_name 类属性 instance-attribute

trace_id 类属性 instance-attribute

group_id 类属性实例属性

trace_metadata 类属性实例属性

相关文章：

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

get_system_prompt `async`

`Runner`

Run `async` `类方法`

run_sync `类方法`

run_streamed `类方法`

RunConfig `数据类`

model `类-属性` `instance-attribute`

model_provider `类属性实例属性`

model_settings `类属性实例属性`

handoff_input_filter `类属性实例属性`

input_guardrails `类属性实例属性`

output_guardrails `类属性` `instance-attribute`

tracing_disabled `类属性` `instance-attribute`

trace_include_sensitive_data `类属性` `instance-attribute`

workflow_name `类属性` `instance-attribute`

trace_id `类属性` `instance-attribute`

group_id `类属性实例属性`

trace_metadata `类属性实例属性`