基于 mcp-agent 的智能金融分析 Agent：用 EvaluatorOptimizer + Orchestrator 打造数据可信的上市公司研究报告-平芜编程栈

基于 mcp-agent 的智能金融分析 Agent：用 EvaluatorOptimizer + Orchestrator 打造数据可信的上市公司研究报告

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

本指南围绕开源仓库mcp-agent中的实战示例 examples/usecases/mcp_financial_analyzer，完整讲解如何构建一个"先验证数据、再深度分析"的金融分析 Agent：它通过 Google 搜索 MCP 服务器采集公司财务数据，用 EvaluatorOptimizer 质量反馈循环把数据打磨到合格标准，再交给分析师与报告撰写 Agent 输出机构级 Markdown 报告。读完本文，你将掌握 EvaluatorOptimizerLLM 与 Orchestrator 的组合编排方式、Agent 提示词设计范式，以及完整的本地运行与配置方法。

示例概览：为什么金融分析要先验证数据

MCP Financial Analyzer 是一个端到端的金融分析 Agent 应用：给它一个公司名称，它就能自动完成"搜索数据 → 评估数据质量 → 迭代补全 → 深度分析 → 生成报告"的完整流水线，最终在本地文件系统落盘一份专业的 Markdown 研究报告。

这个示例的核心设计理念是：在进入分析阶段之前，先确保底层数据的质量。金融报告的价值完全取决于基础数据是否准确、完整、时效性强，因此它把"数据验证"提升为一等公民——Research Agent 与 Research Evaluator 组成一个反馈循环，直到数据达到预定的质量评级才放行，避免把幻觉或过时数据带进后续的分析与报告。

系统架构：五个角色的协作分工

该示例将整个工作流拆分为五个协作组件，其数据流如下（源自 README.md 的架构图）：

┌──────────────┐ ┌──────────────────┐ ┌────────────────────┐ │ Orchestrator │─────▶│ Research Quality │─────▶│ Research │◀─┐ │ Workflow │ │ Controller │ │ Agent │ │ └──────────────┘ └──────────────────┘ └────────────────────┘ │ │ │ │ │ │ │ │ ▼ │ │ ┌────────────────────┐ │ │ │ Research Evaluator ├──┘ │ │ Agent │ │ └────────────────────┘ │ ┌─────────────────┐ └────────────▶│ Analyst Agent │ │ └─────────────────┘ │ ┌─────────────────┐ └────────────▶│ Report Writer │ │ Agent │ └─────────────────┘

各角色的职责：

Orchestrator（编排器）：总控整个流程，负责在 Agent 之间调度数据流，并确保每个步骤成功完成；
Research Agent（数据采集 Agent）与 Research Evaluator（数据质量评估 Agent）：二者形成反馈闭环——采集 Agent 负责收集数据，评估 Agent 负责审查其质量；
EvaluatorOptimizer（研究质量控制组件）：管理这个反馈循环，评估产出并指挥 Research Agent 持续改进数据，直到达到 EXCELLENT 质量评级（或示例配置的最低门槛 GOOD）；
Analyst Agent（分析师 Agent）：基于已验证的高质量数据，提炼关键投资洞察；
Report Writer（报告撰写 Agent）：生成专业的 Markdown 报告并写入文件系统。

这种编排方式确保了报告质量：在开始分析之前先聚焦于数据验证，Research Agent 与 Research Evaluator 反复迭代，直至 EvaluatorOptimizer 判定数据满足质量要求。

环境准备与安装步骤

克隆仓库并进入示例目录

git clone https://github.com/lastmile-ai/mcp-agent.git cd mcp-agent/examples/usecases/mcp_financial_analyzer

安装 uv 并同步依赖

如果尚未安装uv，先通过 pip 安装：

pip install uv

同步mcp-agent项目依赖：

uv sync

安装本示例专属的依赖（见 requirements.txt，包含mcp-agent、openai、anthropic三个包）：

uv pip install -r requirements.txt

安装 g-search-mcp 搜索引擎服务

本示例依赖第三方 MCP 服务器 g-search-mcp 提供 Google 搜索能力，通过 npm 全局安装：

npm install -g g-search-mcp

配置文件与密钥设置

复制并配置 secrets 文件

示例使用mcp_agent.secrets.yaml存放 LLM 提供商密钥，需先从模板复制：

cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml

然后在mcp_agent.secrets.yaml中填入你偏好的 LLM（本示例默认使用 OpenAI）的 API Key（模板见 mcp_agent.secrets.yaml.example）：

openai: api_key: "YOUR_OPENAI_API_KEY"

如果偏好 Anthropic，也可以取消模板中对应部分的注释来切换提供商。

理解 MCP 服务器配置

示例的运行依赖三个 MCP 服务器，全部声明在 mcp_agent.config.yaml 中：

execution_engine: asyncio mcp: servers: # Fetch server for basic web retrieval fetch: command: "uvx" args: ["mcp-server-fetch"] # Google Search MCP server g-search: command: "npx" args: ["-y", "g-search-mcp"] # Filesystem server for writing reports filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem"] openai: default_model: gpt-4o

三者职责如下：

MCP 服务器	启动方式	作用
`fetch`	`uvx mcp-server-fetch`	基础网页检索，用于抓取搜索结果页面内容
`g-search`	`npx -y g-search-mcp`	Google 搜索，采集股价、财报、新闻等实时数据
`filesystem`	`npx -y @modelcontextprotocol/server-filesystem`	文件系统读写，用于把最终报告落盘

同时配置文件指定了execution_engine: asyncio与 OpenAI 的默认模型gpt-4o。

运行示例

在示例目录下，用公司名称作为命令行参数运行：

uv run main.py "Apple"

换一家公司同样简单：

uv run main.py "Microsoft"

运行入口 main.py 会在启动时读取命令行参数：COMPANY_NAME = "Apple" if len(sys.argv) <= 1 else sys.argv[1]，即不传参时默认分析 Apple。报告会输出到company_reports/目录，文件名形如apple_report_20250915_143000.md（公司名小写 + 时间戳）。仓库中的 sample_report.md 提供了一份针对 Duolingo 的完整样例报告，可作为输出效果的直接参考。

深入源码：核心组件如何协同工作

运行时前置检查

在main.py的main()中，应用启动后会做两项关键检查：

若配置中存在filesystem服务器，则通过context.config.mcp.servers["filesystem"].args.extend([os.getcwd()])把当前工作目录注入其参数，确保报告能写入本地文件系统；否则告警"报告保存可能失败"；
若配置中缺少g-search服务器，则直接return False中止流程，并提示安装命令npm install -g g-search-mcp。

这体现了"失败快速、提示明确"的工程实践：在耗费任何 Token 之前先确认外部依赖可用。

Agent 定义：提示词即数据契约

示例通过mcp_agent.agents.agent中的Agent类创建四个专用 Agent，每个 Agent 的instruction都扮演着"数据契约"的角色，直接决定产出质量：

data_collector（Research Agent）：挂载server_names=["g-search", "fetch"]，被要求按固定结构采集四类数据——当前市场数据（股价、涨跌幅、成交量、52 周区间）、最新财报（EPS 实际 vs 预期、营收实际 vs 预期、同比增速）、近 7 天新闻（3-5 条含日期/来源/影响评级）、关键财务指标（P/E、市值），并强制要求精确数字、附带来源 URL 与时间戳；
data_evaluator（Research Evaluator）：不挂任何 MCP 服务器，专职从完整性、准确性、时效性三个维度打分，输出COMPLETENESS / ACCURACY / CURRENCY / OVERALL RATING结构化评估，并在评分低于 GOOD 时给出"需要补齐的数据点"与"精确搜索词"；
financial_analyst：不挂服务器，基于已验证数据输出股价表现分析、财报分析、新闻影响评估、多空论点（Bull/Bear Case）、估值视角与风险评估；
report_writer：挂载server_names=["filesystem"]，按严格的大纲模板（执行摘要、市场表现、财务表现、近期动态、投资分析、风险因素、投资结论、数据来源与免责声明）生成 1200-1800 词的机构级报告，并保存到output_path。

EvaluatorOptimizerLLM：质量反馈循环的实现

示例的关键创新在于把data_collector与data_evaluator组合进EvaluatorOptimizerLLM（来自 src/mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py）：

research_quality_controller = EvaluatorOptimizerLLM( optimizer=research_agent, evaluator=research_evaluator, llm_factory=OpenAIAugmentedLLM, min_rating=QualityRating.GOOD, )

结合源码可以深入理解其内部机制：

质量评级枚举：QualityRating是一个int枚举，POOR=0 / FAIR=1 / GOOD=2 / EXCELLENT=3，可参与数值比较；
结构化评估结果：评估器通过generate_structured调用返回EvaluationResult（Pydantic 模型），包含rating、feedback、needs_improvement、focus_areas四个字段；
迭代主循环（generate方法）：先让 optimizer 生成初版响应 → 评估器评估 → 若评级低于min_rating且仍需改进，则把EvaluationResult的 feedback 与 focus_areas 拼进 refinement prompt 让 optimizer 重写 → 循环直至达标或达到max_refinements（默认 3 次）上限。整个过程中会保留历史最佳响应（best_response），即使循环被迫终止也能返回迄今为止质量最高的一版；
可配置阈值：min_rating=QualityRating.GOOD表示"数据达到 GOOD 即可放行"，而 README 中提到的 EXCELLENT 是评估器的最高评级标准——提示词里明确"只有无需任何改进才评 EXCELLENT"。

从代码注释可见，EvaluatorOptimizerLLM 既可以作为独立工作流使用，也可以像本例这样"包装"在 Orchestrator 中作为其可用 Agent 之一，为上层编排提供内建的评估与改进能力——这正是本例"数据先行"策略的基石。

Orchestrator：动态任务编排

最外层由Orchestrator（来自 src/mcp_agent/workflows/orchestrator/orchestrator.py）统一调度：

orchestrator = Orchestrator( llm_factory=OpenAIAugmentedLLM, available_agents=[ research_quality_controller, analyst_agent, report_writer, ], plan_type="full", )

plan_type="full"表示"先生成完整计划、再逐项执行"的规划模式（源码中另一选项为"iterative"，即逐步规划、循环执行）。available_agents列表同时容纳了普通 Agent（financial_analyst、report_writer）与工作流组件（research_quality_controller），说明 Orchestrator 能把 EvaluatorOptimizer 当作一个"可调用的子 Agent"看待。

随后，一条三段式的任务指令被交给编排器执行：

task = f"""Create a high-quality stock analysis report for {COMPANY_NAME} by following these steps: 1. Use the EvaluatorOptimizerLLM component (named 'research_quality_controller') to gather high-quality financial data about {COMPANY_NAME}. This component will automatically evaluate and improve the research until it reaches GOOD quality. 2. Use the financial_analyst to analyze this research data and identify key insights. 3. Use the report_writer to create a comprehensive stock report and save it to: "{output_path}" """

执行时通过orchestrator.generate_str(message=task, request_params=RequestParams(model="gpt-4o"))驱动整个流水线，并在结束后校验output_path是否真实存在，以确认报告成功生成（对应代码中的成功/失败日志与布尔返回值）。全程通过app.logger记录Initializing stock analysis workflow、Starting the stock analysis workflow、Report successfully generated等关键节点，便于观测排障。

预期产出：一份机构级研究报告

运行结束后，company_reports/目录下会生成一份完整的 Markdown 报告。以仓库附带的 sample_report.md（Duolingo 案例）为参照，报告包含：执行摘要（当前价格、市值、投资论点与置信度）、市场表现（交易指标与技术分析）、财务表现（季度 EPS/营收实际 vs 预期及同比）、近 7 天新闻与分析师动态、多空双方论证、估值评估、风险因素、投资结论，以及带 URL 与时间戳的数据来源、数据质量说明和免责声明。这份样例直接验证了整条流水线的实际产出效果。

小结与可复用要点

MCP Financial Analyzer 示例提供了一套可迁移的组合范式，值得提炼的设计要点包括：

数据质量前置：用EvaluatorOptimizerLLM(min_rating=QualityRating.GOOD)把"采集-评估-迭代"封装为受控循环，在分析前兜底数据可信度；
Agent 提示词契约化：采集、评估、分析、撰写四类 Agent 各自用结构化提示词定义输入输出格式，上下游数据流清晰可验；
工作流组合嵌套：Orchestrator(plan_type="full")可以把 EvaluatorOptimizer 工作流当作子 Agent 编排，实现"验证 → 分析 → 产出"的端到端自动化；
依赖预检：启动时校验 MCP 服务器是否就绪，失败即中止并给出修复提示，避免无谓消耗；
产出可落盘：通过filesystemMCP 服务器把结构化报告写入本地目录，形成可审计的交付物。

若想深入理解底层机制，可继续阅读 evaluator_optimizer.py（质量循环核心实现）、orchestrator.py（编排器与计划模式）以及对应的测试用例 tests/workflows/evaluator_optimizer 与 tests/workflows/orchestrator，并结合本示例的配置与运行入口 main.py 进行二次开发。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考