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

英文文档原文详见 OpenAI Agents SDK

本文是OpenAI-agents-sdk-python使用翻译软件翻译后的中文文档/教程。分多个帖子发布，帖子的目录如下：

(1) OpenAI 代理 SDK， 介绍及快速入门

(2)OpenAI agents sdk, agents，运行agents，结果，流，工具，交接

(3) OpenAi agents sdk, 跟踪，上下文管理，护栏

(4) Openai agents sdk, 编排多个代理，模型，配置SDK

编排多个代理

编排是指应用程序中的代理流。哪些代理运行，以什么顺序运行，他们如何决定接下来会发生什么？有两种主要方法可以编排代理：

1. 允许 LLM 做出决策：这使用 LLM 的智能来计划、推理并据此决定采取什么步骤。
2. 通过代码编排：通过代码确定代理的流程。

您可以混合和匹配这些模式。每个选项都有自己的权衡，如下所述。

通过 LLM 进行编排

代理是配备说明、工具和交接的 LLM。这意味着，给定一个开放式任务，LLM 可以自主规划它将如何处理该任务，使用工具采取行动和获取数据，并使用交接将任务委派给子代理。例如，研究代理可以配备以下工具：

• 通过网络搜索在线查找信息
• 文件搜索和检索，用于搜索专有数据和连接
• 使用计算机在计算机上执行作
• 执行代码以进行数据分析
• 将工作交给擅长规划、报告撰写等的专业代理。

当任务是开放式的，并且您希望依赖 LLM 的智能时，此模式非常有用。这里最重要的策略是：

1. 投资于好的提示。明确哪些工具可用，如何使用它们，以及它必须在哪些参数中运行。
2. 监控您的应用并对其进行迭代。查看哪里出了问题，并迭代您的提示。
3. 允许代理反省和改进。例如，在循环中运行它，并让它自我批评;或者，提供错误消息并让它改进。
4. 拥有擅长一项任务的专业代理，而不是拥有期望擅长任何事情的通用代理。
5. 投资于评估。这使您可以训练代理改进并更好地完成任务。

通过代码进行编排

虽然通过 LLM 进行编排功能强大，但通过代码进行编排使任务在速度、成本和性能方面更具确定性和可预测性。这里的常见模式是：

• 使用结构化输出生成格式正确的数据，您可以使用代码进行检查。例如，您可以要求代理将任务分类为几个类别，然后根据类别选择下一个代理。
• 通过将一个代理的输出转换为下一个代理的输入来链接多个代理。您可以将诸如撰写博客文章之类的任务分解为一系列步骤 - 做研究、写大纲、写博客文章、批评它，然后改进它。
• 与评估和提供反馈的代理一起循环运行执行任务的代理，直到评估代理说输出通过特定标准。while
• 并行运行多个代理，例如通过 Python 基元（如 .当您有多个彼此不依赖的任务时，这对于速度非常有用。asyncio.gather

我们在 examples/agent_patterns 中提供了许多示例。

模型

代理 SDK 提供对 OpenAI 模型的开箱即用支持，有两种风格：

• 推荐：OpenAIResponsesModel，它使用新的响应 API 调用 OpenAI API。
• OpenAIChatCompletionsModel，它使用聊天完成 API 调用 OpenAI API。

混合和匹配模型

在单个工作流程中，您可能希望为每个代理使用不同的模型。例如，您可以使用更小、更快的模型进行分类，而使用更大、功能更强大的模型进行复杂任务。配置 Agent 时，您可以通过以下方式选择特定模型：

1. 传递 OpenAI 模型的名称。
2. 传递任何模型名称 + 可以将该名称映射到 Model 实例的 ModelProvider。
3. 直接提供 Model 实现。

注意

虽然我们的开发工具包同时支持 OpenAIResponsesModel 和 OpenAIChatCompletionsModel 形状，但我们建议为每个工作流使用单个模型形状，因为这两个形状支持一组不同的功能和工具。如果您的工作流程需要混合和匹配模型形状，请确保您使用的所有功能在两者上都可用。

from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
import asyncio

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You only speak Spanish.",
    model="o3-mini", 

) english_agent = Agent( name="English agent", instructions="You only speak English", model=OpenAIChatCompletionsModel( model="gpt-4o", openai_client=AsyncOpenAI() ), ) triage_agent = Agent( name="Triage agent", instructions="Handoff to the appropriate agent based on the language of the request.", handoffs=[spanish_agent, english_agent], model="gpt-3.5-turbo", ) async def main(): result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?") print(result.final_output)

使用其他 LLM 提供商

许多提供商还支持 OpenAI API 格式，这意味着您可以将 a 传递给现有的 OpenAI 模型实现并轻松使用它们。 用于为您选择的模型配置调优参数（例如温度top_p）。base_urlModelSettings

external_client = AsyncOpenAI(
    api_key="EXTERNAL_API_KEY",
    base_url="https://api.external.com/v1/",
)

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You only speak Spanish.",
    model=OpenAIChatCompletionsModel(
        model="EXTERNAL_MODEL_NAME",
        openai_client=external_client,
    ),
    model_settings=ModelSettings(temperature=0.5),
)

配置 SDK

API 密钥和客户端

默认情况下，SDK 会在导入 LLM 请求和跟踪后立即查找环境变量。如果您无法在应用程序启动之前设置该环境变量，则可以使用 set_default_openai_key（） 函数来设置键。OPENAI_API_KEY

from agents import set_default_openai_key

set_default_openai_key("sk-...")

或者，您也可以配置要使用的 OpenAI 客户端。默认情况下，SDK 使用环境变量中的 API 密钥或上面设置的默认密钥创建实例。您可以使用 set_default_openai_client（） 函数更改此设置。AsyncOpenAI

from openai import AsyncOpenAI
from agents import set_default_openai_client

custom_client = AsyncOpenAI(base_url="...", api_key="...")
set_default_openai_client(custom_client)

最后，您还可以自定义使用的 OpenAI API。默认情况下，我们使用 OpenAI 响应 API。您可以通过 set_default_openai_api（） 函数覆盖此函数以使用 Chat Completions API。

from agents import set_default_openai_api

set_default_openai_api("chat_completions")

描图

默认情况下，跟踪处于启用状态。默认情况下，它使用上一节中的 OpenAI API 密钥（即环境变量或您设置的默认密钥）。您可以通过 set_tracing_export_api_key 函数专门设置用于跟踪的 API 密钥。

from agents import set_tracing_export_api_key

set_tracing_export_api_key("sk-...")

您还可以使用 set_tracing_disabled（） 函数完全禁用跟踪。

from agents import set_tracing_disabled

set_tracing_disabled(True)

调试日志记录

SDK 有两个 Python 记录器，未设置任何处理程序。默认情况下，这意味着 warnings 和 errors 将发送到 ，但其他日志将被禁止。stdout

要启用详细日志记录，请使用 enable_verbose_stdout_logging（） 函数。

from agents import enable_verbose_stdout_logging

enable_verbose_stdout_logging()

或者，您可以通过添加处理程序、过滤器、格式化程序等来自定义日志。您可以在 Python 日志记录指南中阅读更多内容。

import logging

logger =  logging.getLogger("openai.agents") # or openai.agents.tracing for the Tracing logger

# To make all logs show up
logger.setLevel(logging.DEBUG)
# To make info and above show up
logger.setLevel(logging.INFO)
# To make warning and above show up
logger.setLevel(logging.WARNING)
# etc

# You can customize this as needed, but this will output to `stderr` by default
logger.addHandler(logging.StreamHandler())

日志中的敏感数据

某些日志可能包含敏感数据（例如，用户数据）。如果要禁止记录此数据，请设置以下环境变量。

要禁用记录 LLM 输入和输出：

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1

要禁用日志记录工具输入和输出：

export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1