使用 OpenAI Agents SDK 进行多智能体投资组合协作

来源: https://developers.openai.com/cookbook/examples/agents_sdk/multi-agent-portfolio-collaboration/multi_agent_portfolio_collaboration 抓取时间: 2026-07-21 16:25:34

介绍

本指南面向已经熟悉 OpenAI 模型和 LLM 智能体的读者，希望了解如何编排一组智能体来完成现实世界的复杂任务。 您将学到的内容 在本笔记本中，您将学习如何使用 OpenAI Agents SDK 设计和实现复杂的多智能体协作系统。具体来说，您将看到如何：

• 构建一个工作流，其中多个专业智能体（宏观、基本面、量化）在投资组合经理智能体的领导下协作，以解决具有挑战性的投资研究问题。
• 使用 "智能体即工具" 方法，其中一个中心智能体编排并调用其他智能体作为特定子任务的工具。
• 在一个集成工作流中利用 SDK 支持的所有主要工具类型（自定义 Python 函数、代码解释器和 Web 搜索等托管工具，以及外部 MCP 服务器）。
• 应用智能体模式中的模块化、并行性和可观察性最佳实践。

为什么这很重要 "智能体即工具" 模式是构建透明、可审计和可扩展的多智能体协作的有力方式。此示例演示了如何使用 OpenAI Agents SDK 结合深度专业化、并行执行和强大的编排。 通过本指南，您将拥有一个清晰的蓝图，用于构建您自己的多智能体工作流，进行研究、分析或任何受益于专家协作的复杂任务。

目录

1. 什么是多智能体协作？
2. 协作模式：交接 vs. 智能体即工具
3. 架构概述
4. 支持的工具类型
5. 设置
6. 运行工作流
7. 首席投资组合经理（PM）智能体
8. 分解首席投资组合经理智能体
9. 示例输出
10. 构建智能体的最佳实践
11. 进一步阅读与最佳实践

什么是多智能体协作？

多智能体协作 意味着多个自主智能体（LLM "节点"）协调实现一个总体目标，而这个目标对于单个智能体来说很难处理。每个智能体处理特定的子任务或专业领域，而不是使用一个单一的大型提示词，编排层将这些智能体 "节点" 连接成一个连贯的工作流。这种方法对于复杂系统很有用——例如，财务分析可能会被分解为宏观经济分析、公司基本面分析和量化信号分析，每个部分由不同的智能体专家处理。智能体共享信息，它们的结果被组合以产生最终输出。

协作模式：交接 vs. 智能体即工具

OpenAI Agents SDK 支持多种智能体协作模式：

• 交接协作： 一个智能体可以在问题处理过程中 将控制权交接 给另一个智能体。在交接架构中，每个智能体都了解其他智能体，并可以决定何时听从更合适的智能体。这对于开放式或对话式工作流非常灵活，但可能使维护任务的全局视图变得更加困难。阅读 SDK 文档了解更多。
• 智能体即工具： 在这种方法中，一个智能体（通常是中央规划器或管理器）将其他智能体当作工具调用。子智能体不会接管对话；相反，主智能体针对特定子任务调用它们，并合并它们的结果。这种模型保持单一控制线程（主智能体编排一切），并倾向于简化协调。此仓库使用智能体即工具模型： 投资组合经理智能体保持负责，在需要其他专家的专业知识时使用它们作为工具。这种选择保持了整体推理的透明性，并允许子任务的并行执行，这对于复杂分析非常理想。

有关这些协作模式的更多信息，请参阅 OpenAI Agents SDK 文档。

架构概述

我们的系统遵循 中心辐射型设计。投资组合经理智能体 是中心（中央协调器），专业智能体 是辐射。用户的查询（例如 "计划的降息会如何影响我的 GOOGL 持仓？"）首先发送给投资组合经理。投资组合经理智能体被提示分解问题并委托给适当的专业智能体。它将每个专家视为可调用的工具，调用它们来完成其分析部分。这三个智能体都向投资组合经理报告，然后投资组合经理为用户合成最终答案。

支持的工具类型

Agents SDK 的一个关键优势是定义智能体可以使用的 工具 的灵活性。工具可以从简单的 Python 函数到外部服务。在本项目中，我们使用：

• MCP（模型上下文协议）服务器： 用于以标准化方式将智能体连接到外部工具和数据源。本项目使用一个本地 MCP 服务器获取 Yahoo Finance 数据（参见 mcp/yahoo_finance_server.py）。了解更多：OpenAI MCP 文档 | MCP 规范
• OpenAI 托管工具： 托管工具是 OpenAI 提供的内置、托管工具，无需自定义实现。它们开箱即用地提供强大的功能，例如 代码解释器（用于量化/统计分析）和 Web 搜索（用于获取最新新闻和数据）。这些工具易于集成，由 OpenAI 维护，允许智能体执行高级操作，如代码执行和实时信息检索，无需额外设置。
• 自定义工具： 自定义工具是您定义并注册为智能体工具的任何 Python 函数。Agents SDK 使这变得简单：只需装饰您的函数，SDK 将自动提取其名称、文档字符串和输入架构。这对于领域特定逻辑、数据访问或工作流扩展非常理想。在我们的项目中，我们使用自定义工具访问 FRED 经济数据（参见 FRED API）并执行文件系统操作。

自定义工具使您拥有完全的灵活性，可以将智能体的功能扩展到内置或托管工具之外。查看 SDK 关于函数工具的文档。

想要添加更多工具吗？ SDK 支持广泛的工具类型，包括 Web 搜索、文件搜索、代码执行等。查看 SDK 文档中支持的完整工具列表。

设置

# 安装所需依赖
!pip install -r requirements.txt

在运行工作流之前，请设置您的环境变量：

• OPENAI_API_KEY（用于 OpenAI 访问）
• FRED_API_KEY（用于 FRED 经济数据，请参阅 FRED API 密钥说明）

import os

missing = []
if not os.environ.get('OPENAI_API_KEY'):
    missing.append('OPENAI_API_KEY')
if not os.environ.get('FRED_API_KEY'):
    missing.append('FRED_API_KEY')

if missing:
    print(f"Missing environment variable(s): {', '.join(missing)}. Please set them before running the workflow.")
else:
    print("All required API keys are set.")

运行工作流

编辑问题为您想要的任何内容，但保留日期字段以提高准确性！ 免责声明： 此示例仅用于教育目的。在做出任何投资决定之前，请咨询合格的金融专业人士 工作流通过向首席投资组合经理（PM）智能体发送用户请求来启动。PM 智能体编排整个过程，根据需要委托给专业智能体和工具。您可以使用 OpenAI Traces 实时监控工作流，它提供对每个智能体和工具调用的详细可见性。 编辑下面代码中的 question 为您想要的任何内容，但保留日期字段以提高准确性！ 注意： 根据任务的复杂性，此请求可能需要长达 10 分钟的时间。

import datetime
import json
import os
from pathlib import Path
from contextlib import AsyncExitStack
from agents import Runner, add_trace_processor, trace
from agents.tracing.processors import BatchTraceProcessor
from utils import FileSpanExporter, output_file
from investment_agents.config import build_investment_agents
import asyncio

add_trace_processor(BatchTraceProcessor(FileSpanExporter()))

async def run_workflow():
    if "OPENAI_API_KEY" not in os.environ:
        raise EnvironmentError("OPENAI_API_KEY not set — set it as an environment variable before running.")

    today_str = datetime.date.today().strftime("%B %d, %Y")
    question = (
        f"Today is {today_str}. "
        "How would the planned interest rate reduction effect my holdings in GOOGL if they were to happen?"
        "Considering all the factors effecting its price right now (Macro, Technical, Fundamental, etc.), what is a realistic price target by the end of the year?"
    )
    bundle = build_investment_agents()

    async with AsyncExitStack() as stack:
        for agent in [getattr(bundle, "fundamental", None), getattr(bundle, "quant", None)]:
            if agent is None:
                continue
            for server in getattr(agent, "mcp_servers", []):
                await server.connect()
                await stack.enter_async_context(server)

        print("Running multi-agent workflow with tracing enabled...\n")
        with trace(
            "Investment Research Workflow",
            metadata={"question": question[:512]}
        ) as workflow_trace:
            print(
                f"\n🔗 View the trace in the OpenAI console: "
                f"https://platform.openai.com/traces/trace?trace_id={workflow_trace.trace_id}\n"
            )

            response = None
            try:
                response = await asyncio.wait_for(
                    Runner.run(bundle.head_pm, question, max_turns=40),
                    timeout=1200
                )
            except asyncio.TimeoutError:
                print("\n❌ Workflow timed out after 20 minutes.")

            report_path = None
            try:
                if hasattr(response, 'final_output'):
                    output = response.final_output
                    if isinstance(output, str):
                        data = json.loads(output)
                        if isinstance(data, dict) and 'file' in data:
                            report_path = output_file(data['file'])
            except Exception as e:
                print(f"Could not parse investment report path: {e}")

            print(f"Workflow Completed Response from Agent: {response.final_output if hasattr(response, 'final_output') else response}, investment report created: {report_path if report_path else '[unknown]'}")

# 在 Jupyter 笔记本单元格中运行：
await run_workflow()

分解首席投资组合经理智能体

首席投资组合经理（PM）智能体是整个工作流的协调器。它协调一组四个专业智能体，每个智能体专注于不同的专业领域。这种设计是有意为之：用每一种可能的责任重载单个智能体会导致肤浅、通用的输出，并使您的系统随着时间的推移难以维护或改进。

为什么这种设计？

通过将问题分解为专门的智能体——每个智能体都有明确的角色——您会获得：

• 更深入、更高质量的研究： 每个智能体都可以专注于其领域，使用适合工作的正确工具和提示词。PM 智能体将这些观点整合在一起，以获得更细致、更稳健的答案。
• 模块化和清晰度： 您可以更新、测试或改进一个智能体而不会影响其他智能体。这使您的系统随着需求的发展更容易维护和扩展。
• 通过并行性获得更快的结果： 独立智能体可以同时工作，大大减少完成复杂、多部分分析的时间。
• 一致性和可审计性： 结构化的、提示词驱动的工作流确保每次运行都遵循最佳实践，易于调试，并产生您可以信任和审查的输出。

这种方法非常适合任何您想要深度、专业化和可靠性的应用程序——无论您是在构建研究助手、决策支持工具，还是任何受益于专家协作和编排的系统。 我们在实践中如何实现这一点：

• 每个专业智能体（基本面、宏观、量化）都使用 SDK 的 function_tool 装饰器包装为可调用工具，具有自定义名称和描述。这使 PM 智能体的工具集明确且对 LLM 友好。
• 首席 PM 智能体使用 run_all_specialists_parallel 工具并发调用所有三个专家，利用 parallel_tool_calls=True 获得最大速度和效率。
• 智能体的提示词从 Markdown 文件（pm_base.md）加载，不仅编码了公司的理念，还编码了详细的工具使用规则和逐步工作流。这确保每次运行都是一致的、可审计的，并与最佳实践保持一致。
• 在收集和审查专家输出后，PM 智能体使用专用的备忘录编辑器工具来组装、格式化和最终确定投资报告。这种关注点分离使工作流保持模块化且易于扩展。
• 该系统专为可扩展性而设计：您可以添加新的专业智能体、更换工具或更新提示词，而不会破坏整体编排逻辑。所有工具调用、智能体决策和输出都捕获在 OpenAI Traces 中，以实现完全透明和调试。

这些实现选择直接支持上述好处——实现了深度、模块化和可靠的多智能体研究工作流，易于维护、审计和改进。

首席投资组合经理智能体：代码

from agents import Agent, ModelSettings, function_tool
from utils import load_prompt, DISCLAIMER

def build_head_pm_agent(fundamental, macro, quant, memo_edit_tool):
    def make_agent_tool(agent, name, description):
        @function_tool(name_override=name, description_override=description)
        async def agent_tool(input):
            return await specialist_analysis_func(agent, input)
        return agent_tool
    fundamental_tool = make_agent_tool(fundamental, "fundamental_analysis", "Generate the Fundamental Analysis section.")
    macro_tool = make_agent_tool(macro, "macro_analysis", "Generate the Macro Environment section.")
    quant_tool = make_agent_tool(quant, "quantitative_analysis", "Generate the Quantitative Analysis section.")

    @function_tool(name_override="run_all_specialists_parallel", description_override="Run all three specialist analyses (fundamental, macro, quant) in parallel and return their results as a dict.")
    async def run_all_specialists_tool(fundamental_input, macro_input, quant_input):
        return await run_all_specialists_parallel(
            fundamental, macro, quant,
            fundamental_input, macro_input, quant_input
        )

    return Agent(
        name="Head Portfolio Manager Agent",
        instructions=(load_prompt("pm_base.md") + DISCLAIMER),
        model="gpt-4.1",
        tools=[fundamental_tool, macro_tool, quant_tool, memo_edit_tool, run_all_specialists_tool],
        model_settings=ModelSettings(parallel_tool_calls=True, tool_choice="auto", temperature=0)
    )

首席 PM 系统提示词：强制执行最佳实践

PM 智能体的系统提示词（参见 prompts/pm_base.md）是工作流的核心。它编码了：

• 公司的理念（原创性、风险意识、挑战共识）
• 明确的工具使用规则（何时使用并行工具、如何结构化输入）
• 稳健的多步骤工作流（确定任务类型、提供指导、审查输出、组装备忘录、处理缺失数据）

此提示词确保每次运行都是：

• 一致的： 每次都遵循相同的高标准和流程。
• 可审计的： 每个步骤、工具调用和决策在追踪中都是可见的。
• 高质量的： 输出是原创的、有风险意识的，并经过严格审查。

# 渲染首席投资组合经理智能体使用的实际系统提示词
from pathlib import Path
from IPython.display import Markdown, display

pm_prompt_path = Path("prompts/pm_base.md")
if pm_prompt_path.exists():
    with pm_prompt_path.open("r", encoding="utf-8") as f:
        content = f.read()
    display(Markdown(content))
else:
    print("System prompt not found at prompts/pm_base.md")

示例输出

这是通过工作流生成的投资报告的示例。您的输出将写入目录中的 outputs 文件夹。 点击展开投资备忘录

投资备忘录：Alphabet Inc. (GOOGL) — 计划降息的影响（2025 年 5 月）

执行摘要

Alphabet Inc. (GOOGL) 当前股价为每股 171.42 美元，市值为 1.88 万亿美元，市盈率为 16.91。投资论点适度看好：虽然美联储计划降息是温和的利好因素，但它不是 GOOGL 价格走势的主要驱动因素。最具原创性的差异化见解——完全符合我们公司的愿景——是 GOOGL 对利率的直接敏感度适中（与 10 年期收益率的最大周相关性约为 0.29），真正的风险/回报取决于 AI 驱动增长的可持续性、行业轮换和监管逆风。这一论点得到了稳健的技术面、强劲的基本面和压倒性的分析师情绪的支持，但受到 AI 乐观情绪消退或宏观/监管冲击出现的风险的制约。共识观点有证据支持：GOOGL 的业务仍然具有弹性，但变体观点——降息未能刺激科技或行业轮换限制回报——不应被忽视。主要风险包括监管行动、宏观经济不确定性以及 AI 叙事发生变化的可能性。在最好的情况下，GOOGL 到 2025 年底可能达到 200–210 美元；在最坏的情况下，重新测试 160–170 美元是合理的。这份备忘录通过关注情景规划、原创量化分析以及对共识和变体观点的批判性评估，体现了公司的愿景。

基本面视角

Alphabet 的核心业务由其在数字广告（谷歌搜索、YouTube）的主导地位以及不断增长的云和 AI 部门驱动。截至最新季度（2025 年第一季度），收入为 902 亿美元，净收入为 345 亿美元，每股收益为 2.81 美元，净利润率为 38.3%。利润率在过去一年有所改善，公司在 AI 和云领域的规模和领导力提供了持久的护城河。然而，最近的分析师目标价格已向下修正（Bernstein：165 美元，UBS：209 美元，Wolfe：210 美元），反映出对监管和宏观经济风险的谨慎态度。共识观点是合理的：虽然 Alphabet 的财务实力和创新是明确的，但监管审查和宏观逆风（例如，经济衰退期间广告预算减少）是真实的风险。最具原创性的见解是公司适应和创新的能力，可能会减轻一些风险。分析是基于证据的，最近的季度数据显示利润率稳定或提高：

最近的分析师情绪压倒性地积极，目前有 56 个买入、12 个持有和 0 个卖出建议：

基本面观点通过关注证据、情景规划而不是简单地遵循共识，与公司愿景保持一致。与公司愿景的主要分歧在于，如果分析未能考虑监管或宏观冲击的影响，但这一点在这里得到了解决。

宏观视角

宏观经济环境好坏参半。美国实际 GDP 正在增长（23.5 万亿美元，2025 年第一季度），失业率较低（4.2%），通胀仍然高企（CPI：320.3）。美联储将利率维持在 4.25–4.50%，立场耐心，关注不断演变的风险。美元强劲（DXY：123.4），最近的关税带来了不确定性。投资者正从美国科技股转向亚洲股市，反映出对高估值和海外更好增长前景的担忧。宏观共识观点是降息将支持科技估值，但变体观点——得到我们公司愿景支持——是行业轮换和贸易政策可能抵消这些好处。尾部风险情景包括降息支持 GOOGL 的基本情况（目标价 180–190 美元），以及贸易紧张或行业轮换限制回报的下行情况。分析是基于证据的，使用 FRED 数据和最近的政策声明，并明确考虑了最佳和最坏情况。宏观观点通过挑战共识和规划多种结果，完全符合公司愿景。

量化视角

量化分析证实，GOOGL 对利率的直接敏感度适中。与 10 年期国债收益率的平均周相关性为 0.29，与联邦基金利率的平均周相关性为 0.05，表明利率变化不是 GOOGL 回报的主要驱动因素。技术面稳健：GOOGL 高于关键移动平均线，动量为正，波动率适中。情景分析显示，降息是温和的利好因素，但如果该举措已经被定价，或者技术面崩溃，5–10% 的回调是可能的。分析师情绪强烈为正，基本面（收入、利润率）正在改善。量化统计摘要：

关键图表和图像：

量化观点在关注情景分析和适度利率敏感度方面是原创的，并且通过不简单地遵循共识与公司愿景保持一致。局限性包括疫情后数据窗口较短，以及 GOOGL 的价格受到利率以外的多种因素（AI、广告市场、监管）驱动的事实。

投资组合经理视角

PM 综合认为，所有三个专业部分都收敛于适度看好的前景，2025 年底的现实目标价格为 190–210 美元。最具原创性的见解是 GOOGL 的直接利率敏感度适中，真正的风险是 AI 驱动的增长能否继续，或者行业轮换和监管逆风是否会限制回报。量化部分在强调稳健的技术面和情绪方面表现出色，但也指出了下行情景中 160–170 美元重新测试的风险。基本面和宏观部分强调了监测监管和贸易政策的重要性。如果低配大盘科技股，现在是一个合理的入场点，但头寸规模应反映行业轮换或宏观失望的风险。变体观点——降息未能刺激科技或 AI 叙事发生变化——不应被忽视。头寸规模和风险管理是关键，完全符合公司的情景规划和差异化见解的愿景。

建议与问题回答

建议是维持或适度增加对 GOOGL 的敞口，特别是如果低配大盘科技股，基本情况下 2025 年底目标价为 200–210 美元。这通过关注原创的、基于证据的情景分析，而不是简单地遵循共识，体现了公司愿景。该建议的合理性在于稳健的基本面、积极的技术面和强劲的分析师情绪，但受到行业轮换、监管行动或 AI 叙事变化的风险的制约。如果这些风险成为现实，重新测试 160–170 美元是可能的。规模和风险管理应反映这些情景。这种方法是差异化的、证据驱动的，完全符合公司的愿景。 备忘录结束 免责声明：我是一个 AI 语言模型，不是注册投资顾问。提供的信息是教育性和一般性的。在做出任何投资决定之前，请咨询合格的金融专业人士。

构建智能体的最佳实践

最有效的智能体系统结合了模块化的智能体设计、清晰的工具定义、并行执行和结构化的提示词。这种方法——OpenAI Agents SDK 的核心——使您的工作流健壮、可扩展，并且易于调试或扩展。 OpenAI Agents SDK 支持这些最佳实践的关键功能：

• 智能体循环： 自动处理工具调用、LLM 推理和工作流控制。
• Python 优先编排： 使用熟悉的 Python 模式链接、组合和编排智能体。
• 交接： 在智能体之间委派任务以实现专业化和模块化。
• 护栏： 验证输入/输出并在错误时尽早中断以提高可靠性。
• 函数工具： 将任何 Python 函数注册为工具，具有自动架构和验证功能。
• 追踪： 可视化、调试和监控工作流的每一步，以实现完全透明。

精心设计的工具、深思熟虑的编排和谨慎的模型选择的结合对于构建有效的智能体系统至关重要。在这个示例中，我们使用 GPT-4.1 系列模型，因为它们具有强大的分析和工具使用能力（参见 GPT-4.1 提示词指南）。关于更深层次的架构最佳实践，请参阅随附的 构建智能体实用指南（PDF）。通过将这些元素结合在一起，您将获得一个健壮、可扩展且易于调试或扩展的系统。 请尝试使用您自己的投资问题的示例，并分享任何反馈！祝您构建愉快。

进一步阅读与最佳实践

• OpenAI Agents SDK 文档
• OpenAI Agents SDK：多智能体编排
• OpenAI Agents SDK：工具列表
• OpenAI Agents SDK：MCP 文档
• MCP 规范
• OpenAI Cookbook
• (GPT-4.1 提示词指南)
• 构建智能体实用指南（PDF）