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

代理模块

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 环境变量。

参数：

源码 src/agents/__init__.py

set_default_openai_client

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

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

参数：

源码 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. 在交接中，新座席接管对话。在此工具中，新代理是 作为工具调用，并且对话由原始代理继续。

参数：

源码 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 异常。

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

参数：

返回：

源码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 异常。

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

参数：

返回：

源码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 异常。

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

参数：

返回：

源码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

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