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

wtsolutions

已于 2025-03-14 20:02:53 修改

阅读量1k

点赞数 18

CC 4.0 BY-SA版权

分类专栏： openai agents sdk 文章标签： python openai sdk 中文教程文档

于 2025-03-13 08:46:45 首次发布

本文链接：https://blog.youkuaiyun.com/wtsolutions/article/details/146221554

openai agents sdk 专栏收录该内容

8 篇文章

订阅专栏

英文文档原文详见 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的这个专栏里面了，大家可以到专栏里面看到所有的目录，欢迎订阅这个专栏。

编排多个代理

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

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

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

通过 LLM 进行编排

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

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

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

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

通过代码进行编排

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

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

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

模型

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

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

混合和匹配模型

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

传递 OpenAI 模型的名称。
传递任何模型名称 + 可以将该名称映射到 Model 实例的 ModelProvider。
直接提供 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