企业官网建设流程全解析

mcp-agent 实战：用 Orchestrator + EvaluatorOptimizer 构建 AI 金融分析报告流水线——以 sample_report.md 为范例拆解

【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent

本技术指南以开源项目 mcp-agent 中金融分析示例（mcp_financial_analyzer）的产出物 sample_report.md 为骨架，深入剖析一份"机构级"AI 投资分析报告从数据采集、质量校验、投资分析到报告落盘的全流程生成机制。读完本文，你将掌握：多智能体编排（Orchestrator）与评估-优化循环（EvaluatorOptimizer）如何协作产出高质量报告、报告每章背后的生成 Agent 与提示词设计思路、以及如何基于 示例入口脚本 配置和运行你自己的股票分析器。

一、范例报告是什么：从 sample_report.md 说起

sample_report.md是 mcp-agent 仓库中mcp_financial_analyzer示例针对 Duolingo（NASDAQ: DUOL）自动生成的一份完整投资分析报告。它并非人工撰写的静态模板，而是由四个各司其职的 LLM Agent 协同工作、经由"数据采集 → 质量评审 → 投资分析 → 报告撰写"四步流水线实时生成的产出物。报告日期为 2025 年 7 月 16 日，核心结论包括：

• 现价 $360.67（当日 ±4.7%），市值约 $166.2 亿美元，52 周区间 $145.05 - $544.93，处于区间 66% 位置；
• 最新季度（Q1 2025）EPS 实际 $0.72 对预期 $0.52（超出 38.46%），营收实际 $2.3074 亿对预期 $2.2315 亿（超出 3.32%），同比营收增长 37.7%；
• P/E 高达 188.95，显著高于行业均值，提示高增长预期已被充分定价；
• 最终建议：谨慎乐观（Cautious optimism），置信度 Medium——财报基本面强劲但估值偏高，需在成长性与估值风险间权衡。

需要注意的是：报告中的具体数字是该示例在某次运行时获取的样本数据，仅供参考，不构成任何投资建议。它的真正价值在于示范了一种可复制的工程范式：如何用 MCP 服务器（Google 搜索、网页抓取、文件系统）加上分层 Agent 提示词，把"研究一家公司"这种开放性任务拆解成有质量门槛、可验证、可落盘的流水线。

二、流水线总览：四个 Agent + 两个工作流组件

示例的核心编排逻辑全部位于 main.py，其架构在 示例 README 中有清晰的 ASCII 流程说明，可概括为如下调用链：

Orchestrator（总控编排） ├── research_quality_controller（EvaluatorOptimizerLLM 包装） │ ├── data_collector Agent（g-search + fetch）→ 采集数据 │ └── data_evaluator Agent（纯 LLM）→ 质量评审并反馈 │ └── 循环直到评分 ≥ GOOD ├── financial_analyst Agent（纯 LLM）→ 投资分析 └── report_writer Agent（filesystem）→ 生成报告并写入文件

2.1 数据采集 Agent：data_collector

data_collector挂载了["g-search", "fetch"]两个 MCP 服务器，负责按四个板块采集信息：

1. 当前市场数据：现价、当日涨跌（金额与百分比）、成交量、52 周区间——搜索词如"{COMPANY_NAME} stock price today current"；
2. 最新财报：EPS 实际值与预估、营收实际值与预估、beat/miss 百分比、同比增速——搜索词如"{COMPANY_NAME} earnings vs estimates beat miss"；
3. 近 7 天新闻：3-5 条带日期、来源和影响评估的标题——搜索词如"{COMPANY_NAME} analyst ratings upgrade downgrade"；
4. 关键财务指标：P/E、市值、其他可得比率——搜索词如"{COMPANY_NAME} PE ratio market cap financial metrics"。

该 Agent 的提示词在 main.py 中强制规定了输出格式：每个板块都必须给出Source: [URL and date]，并要求"使用精确数字而非约数、标注数据时间戳、缺失数据要显式说明"。这正是样例报告中每个数据点都带有来源 URL 的原因。

2.2 质量评审 Agent：data_evaluator

data_evaluator不挂载任何服务器（server_names=[]），是纯粹的"裁判" Agent。其提示词定义了三维评审标准：

• 完整性（Completeness）：现价、EPS 实际 vs 预估、营收实际 vs 预估、至少 3 条带日期来源的新闻、关键财务指标、来源引用，六项缺一不可；
• 准确性（Accuracy）：数字必须具体（不能用 "around"、"approximately"）、日期要新、来源须可信、无未经解释的矛盾信息；
• 时效性（Currency）：股价须为当日或最近交易日数据、财报须为最近季度、新闻须来自最近 7 天。

评审输出采用固定格式：分别对 Completeness / Accuracy / Currency 给出 EXCELLENT / GOOD / FAIR / POOR 评级及评语，最后给出 OVERALL RATING 和改进反馈。更关键的是它有一条硬性规则：若缺少"精确现价+变动、最新季度 EPS 实际 vs 预估、最新季度营收实际 vs 预估、至少 2 个近期可信新闻来源"中的任意一项，总评不得超过 FAIR。

2.3 EvaluatorOptimizerLLM：质量闭环

research_quality_controller = EvaluatorOptimizerLLM(optimizer=research_agent, evaluator=research_evaluator, llm_factory=OpenAIAugmentedLLM, min_rating=QualityRating.GOOD)将采集与评审两方绑定成循环：数据先由data_collector生成，再由data_evaluator结构化评分；若未达到min_rating，则把评审反馈拼入 refinement prompt，驱动data_collector再次采集改进，直到达标或达到max_refinements（示例中为MAX_ITERATIONS = 3）。

从源码 evaluator_optimizer.py 可以看到质量等级的底层定义：

class QualityRating(int, Enum): POOR = 0 # Major improvements needed FAIR = 1 # Several improvements needed GOOD = 2 # Minor improvements possible EXCELLENT = 3 # No improvements needed

其generate()方法（evaluator_optimizer.py）在while refinement_count < self.max_refinements循环中依次执行"初始生成 → 结构化评估（generate_structured(response_model=EvaluationResult)）→ 判定达标 → 未达标则带着feedback.focus_areas生成改进版"，并始终保留历史最高评分的那份响应（best_response）作为最终输出。循环过程中产生的每次refinement_history、评分与反馈都会被写入 tracing span，便于事后审计数据质量的演进过程。

2.4 投资分析 Agent：financial_analyst

financial_analyst同样不挂服务器，其职责是把已验证的数据转化为洞见（main.py），要求输出六部分：股价表现分析、财报分析、新闻影响评估、投资论点（Bull Case / Bear Case 各 Top 3，且每条必须有数据支撑）、估值视角、风险评估。样例报告中的"Bull Case - Key Strengths"（营收盈利超预期、用户基数扩张、低负债率 0.06）与"Bear Case - Key Concerns"（高 P/E、成交量萎缩、对分析师评级敏感）正是这一 Agent 的产出形态。

2.5 报告撰写 Agent：report_writer

report_writer挂载["filesystem"]服务器，其提示词（main.py）内嵌了一份完整的报告骨架模板——这就是 sample_report.md 章节结构的直接来源：从# {COMPANY} - Comprehensive Financial Analysis标题、报告日期、分析师署名，到 Executive Summary、Current Market Performance、Financial Performance、Recent Developments、Investment Analysis、Risk Factors、Investment Conclusion、Data Sources & Methodology 九大章节，再到字数要求（1200-1800 词）和"所有结论必须来自已验证数据、不得添加无依据的推测"的硬约束。最终报告通过 filesystem 服务器保存到{output_path}，文件名为{company}_report_{timestamp}.md，位于company_reports/目录。

三、Orchestrator：串联整条流水线的总调度

Orchestrator(llm_factory=OpenAIAugmentedLLM, available_agents=[research_quality_controller, analyst_agent, report_writer], plan_type="full")是总控。plan_type="full"意味着先由 planner LLM 一次性生成完整计划再逐步执行；每个 step 内的子任务会并行执行（executor.execute_many(futures)），上一步结果作为下一步的上下文（format_plan_result）链式传递（见 orchestrator.py）。

主任务 prompt（main.py）明确指示了三个步骤：

1. 使用research_quality_controller采集高质量财务数据（该组件会自动评估并改进研究直至达到 GOOD 质量）；
2. 使用financial_analyst分析数据并提炼关键洞见；
3. 使用report_writer生成完整报告并保存到指定路径。

Orchestrator 源码中值得注意的设计细节：其默认RequestParams设use_history=False（多步工作流暂不支持历史追踪）并把maxTokens提到 16384（orchestrator.py）；planner 使用generate_structured以 Pydantic 模型（Plan/NextStep）约束计划输出；若 planner 指派了available_agents中不存在的 Agent 会直接抛错提示补加 Agent。

四、环境与配置：如何复现这条流水线

4.1 依赖安装

参考 示例 README 的步骤：

# 进入示例目录 cd examples/usecases/mcp_financial_analyzer # 同步项目依赖与示例专属依赖 uv sync uv pip install -r requirements.txt # 内容：mcp-agent / openai / anthropic # 安装 Google 搜索 MCP 服务器（本示例必需） npm install -g g-search-mcp

4.2 配置文件解析

配置文件 声明了三个 MCP 服务器与默认模型：

execution_engine: asyncio mcp: servers: fetch: # 通用网页抓取 command: "uvx" args: ["mcp-server-fetch"] g-search: # Google 搜索 command: "npx" args: ["-y", "g-search-mcp"] filesystem: # 报告落盘 command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem"] openai: default_model: gpt-4o

程序启动时会动态调整 filesystem 服务器的参数：若配置中存在filesystem，则把当前工作目录os.getcwd()追加到其args，使报告能写入当前目录；若未检测到g-search服务器则打印警告并终止（main.py）。

4.3 密钥与运行

复制 secrets 示例 并填入 OpenAI API Key：

cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml # 编辑 secrets 文件，将 openai.api_key 替换为真实密钥

运行（第一个参数为要分析的公司名，缺省为 Apple）：

uv run main.py "Apple" uv run main.py "Microsoft" uv run main.py "Duolingo"

程序执行流程：创建company_reports/输出目录 → 生成带时间戳的{company}_report_{timestamp}.md路径 → 以RequestParams(model="gpt-4o")调用orchestrator.generate_str()→ 校验输出文件是否存在并记录结果。

五、范例报告章节逐段拆解：每个小节在讲什么、为什么这么写

以下对照 sample_report.md 的九大章节，说明每章的信息价值与生成要点（各章均由report_writer按模板填充，数据全部来自前序 Agent 的已验证输出）：

1. Executive Summary（执行摘要）：两分钟内读完的关键结论区——现价、市值、2-3 句投资论点、带置信度（High/Medium/Low）的总体建议。读者先看这一节即可决定是否继续深入。
2. Current Market Performance（当前市场表现）：交易指标 + 技术面解读。样例中成交量较均值下降 42.77% 但股价企稳，被解读为"财报扎实支撑下的投资者持续关注"。
3. Financial Performance（财务表现）：最新季度财报的 beat/miss 幅度（EPS +38.46%、营收 +3.32%）与同比增速（+37.7%），以及估值视角下的 P/E 分析。
4. Recent Developments（近期动态）：7 天内影响股价的新闻清单（每条标注日期、来源、正/负/中性影响）与分析师活动综述。
5. Investment Analysis（投资分析）：Bull Case 三条优势与 Bear Case 三条隐忧的对称呈现，每条均绑定具体数据；最后给出估值评估（P/E 188.95 反映高增长预期，须警惕回调风险）。
6. Risk Factors（风险因素）：公司特有风险（用户粘性依赖、在线教育竞争）与市场/行业风险（监管变化、消费支出周期性）的分层罗列。
7. Investment Conclusion（投资结论）：综合评估 + 明确建议 + 公平价值估计（本样例因市场波动大未给出具体目标价，如实标注"未提供"）。
8. Data Sources & Methodology（数据来源与方法）：所有引用来源 URL 与日期（Yahoo Finance、AInvest、MarketBeat、Robinhood），保证报告可回溯、可复核。
9. 数据质量说明与免责声明：数据时效性限制说明 + 标准投资免责声明（仅供参考、过往表现不代表未来、请咨询专业顾问）。

这种"摘要前置、数据可溯源、多空对称、风险分层、免责收尾"的结构，使报告既便于人类快速决策，也便于下游系统解析与引用——对金融场景尤为重要。

六、可复用的方法论沉淀

从 sample_report.md 及其生成流水线中，可以提炼出四条通用于"AI 自动化研究报告"类任务的工程经验：

1. 先质检、后分析，避免"垃圾进垃圾出"：将采集与评审拆成两个 Agent 并用EvaluatorOptimizerLLM强制达到min_rating门槛，是控制下游分析质量的关键；QualityRating枚举（POOR→EXCELLENT）与focus_areas机制让迭代改进有明确方向。
2. 提示词即模板、模板即规范：report_writer的 instruction 就是报告格式规范本身，用占位符（$XXX.XX）约束数字精度，用"严禁添加无据推测"约束幻觉。
3. 强制来源标注：所有采集输出强制附带Source: [URL and date]，使报告成为可审计的证据链。
4. 置信度显式化：每项关键评估都附带 High/Medium/Low 置信度，避免 LLM 输出过度自信的结论。

七、进阶：把它接进更大系统

本示例的架构天然可扩展：research_quality_controller是一个包装在EvaluatorOptimizerLLM中的组件，而EvaluatorOptimizerLLM的构造参数支持传入Agent、AugmentedLLM实例或Orchestrator/Router/ParallelLLM等嵌套工作流（见 evaluator_optimizer.py），这意味着你可以把"多来源研究"替换为更复杂的编排，或把本流水线作为更高层 Agent 的一个工具。报告经 filesystem 服务器落盘后，即可被定时任务调度、纳入知识库检索，或进一步做市场情绪分析。如需将该流水线部署为可对外提供服务的形态，可参考仓库中的 mcp-agent-cloud 相关文档（如 use-deployed-server 与 deploy-mcp-server）。

关联资源速览（便于在仓库中继续深入）：

• 范例报告：sample_report.md
• 示例完整实现：examples/usecases/mcp_financial_analyzer/main.py
• 示例说明与运行指引：examples/usecases/mcp_financial_analyzer/README.md
• 运行配置：mcp_agent.config.yaml、secrets 模板
• EvaluatorOptimizer 工作流源码：evaluator_optimizer.py
• Orchestrator 工作流源码：orchestrator.py

免责声明：本文所有财务数据均来自示例产出的样本报告，仅用于演示 mcp-agent 的技术能力，不构成任何投资建议。

【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent