QVerisFlow实战：一句“分析英伟达股票“到完整投资分析工作流

QVerisFlow 是一个基于 LangGraph 的多智能体工作流框架，支持对话式工作流构建、可视化画布编辑、智能 Agent 生成与实时执行监控，并深度集成 QVeris 统一数据和工具层。本文带你用一个真实需求——"分析英伟达股票"，走通从一句自然语言到完整投资分析工作流的全过程，全程无需手写复杂编排代码。

一、QVerisFlow 能帮你做什么？

传统多 Agent 系统需要手动定义每个 Agent 的角色、Prompt、工具调用和数据流转，门槛不低。QVerisFlow 的思路是：你只说需求，系统帮你生成工作流。

它的核心能力包括：

• 💬对话式构建：用自然语言描述需求，自动生成 Agent 定义和 DAG 工作流
• 🖥️可视化画布：React + ReactFlow 画布，拖拽编辑节点、查看执行状态
• 🤖智能 Agent 生成：Meta Agent 自动分析任务并生成最优 Agent 定义
• 📊QVeris 工具层：Agent 可动态搜索、执行互联网远程工具（股价、财报、研报等）
• ✅三层验证：规则验证 + LLM 评判 + 组合验证，保证输出质量
• ⚡实时执行监控：WebSocket 推送进度，支持暂停、恢复、干预

项目采用声明式设计：Agent、工具、工作流都是 YAML 配置，配置即代码。详见 README.md。

二、快速上手：安装与启动步骤

1. 安装依赖

# 使用 uv（推荐） uv sync # 或使用 pip pip install -e ".[web,dev]"

2. 配置模型

编辑 config/app_config.yaml，填入你的 LLM API Key：

models: qwen-plus: api_key: "your-api-key" base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" model_name: "qwen-plus" model_selection: default: "qwen-plus"

框架支持同时配置多个模型（Qwen、DeepSeek、GPT、GLM 等），并按任务复杂度自动路由到不同模型。

3. 启动 Web UI

# 终端 1：启动后端服务 uv run python -m src.web # 终端 2：启动前端 cd web-ui && npm install && npm run dev

访问http://localhost:5173，对话式构建界面就打开了。

三、对话式构建：一句话生成投资分析工作流

第 1 步：描述你的需求

在对话框中输入一句自然语言即可，例如：

"帮我创建一个分析英伟达股票的工作流"

或更具体一些：

"我需要一个多维度的投资分析系统，包括数据收集、财务分析、估值和报告生成"

第 2 步：生成工作流规划

系统的DialogueAgent（src/evolution/dialogue_agent.py）会理解你的意图，自动生成工作流规划方案——包括需要哪些 Agent、执行顺序如何、数据如何流转。

第 3 步：确认后自动生成 Agent 定义

确认规划后，Meta Agent 会为每个节点自动生成完整的 Agent 定义（角色设定、输出 Schema、工具引用、模型配置）。你可以在 examples/agents/ 中参考现成的三类 Agent 模板：

第 4 步：画布查看与执行

生成的工作流会展示在画布上，节点间的数据引用一目了然。点击执行后，WebSocket 实时推送每个节点的进度，你可以暂停、恢复甚至中途干预。

最终的完整工作流结构参考 examples/workflows/analysis_workflow.yaml：

开始 → 数据收集 → 财务分析 → 生成报告 → 结束

四、投资分析工作流背后的 4 个关键设计

1. 声明式 YAML 定义工作流

整个投资分析工作流就是一个 YAML 文件。每个节点声明agent_id、上游dependencies、输入字段映射input_mappings，以及节点级的任务说明user_override。例如数据收集节点要求 Agent 依次完成：

1. 用qveris_search_tools搜索可用的数据工具（如 "stock price API"）
2. 用qveris_execute_tool执行工具获取真实数据
3. 整理成结构化 JSON 输出给下游

这种"配置即代码"的方式让工作流可版本管理、可复用、可审查。

2. QVeris 工具层：让 Agent 自己找工具

这是 QVerisFlow 与 QVeris 统一数据层集成的精华所在。金融分析师 Agent 除了本地内置工具（财务数据、股票价格、公告搜索、研报搜索），还挂接了三个 QVeris 远程工具：

• qveris_search_tools：用自然语言搜索平台上的金融分析工具，如 "PE ratio calculation"、"DCF valuation model"
• qveris_execute_tool：执行搜索到的远程工具
• qveris_get_tool_info：获取工具的参数说明和使用示例

Agent 会在执行过程中按需动态搜索工具，而不需要你预先写死所有数据接口。相关集成逻辑见 src/tools/qveris_adapter.py。

3. 三层 Prompt 结构

每个 Agent 的 Prompt 分三层组织（见 docs/overall_design/02_definitions.md）：

• 背景指令：角色设定（"你是一位资深金融分析师"）
• 输出指令：明确的 JSON 输出 Schema，包括估值区间、风险等级枚举（高/中/低）、投资评级枚举（强烈推荐/推荐/中性/谨慎/回避）
• 用户指令：具体任务描述 +@工具名、#上下文名引用语法

以金融分析师为例，其输出 Schema 强制要求包含financial_analysis、valuation_analysis、risk_analysis、investment_opinion四大板块，保证分析结果结构一致、可被下游节点消费。

4. 节点间数据流转与上下文引用

下游节点通过input_mappings精确引用上游输出字段，例如财务分析节点从数据收集节点取output.data映射为input.financial_data；同时通过context_refs: ["#collect_data"]引用上游完整上下文。工作流引擎（src/orchestration/workflow_engine.py）负责 DAG 调度和数据传递。

五、实时监控与迭代优化

执行阶段，Web UI 通过 WebSocket 实时推送节点状态（pending / running / completed / failed），支持暂停与恢复。框架还内置了智能演化闭环（docs/overall_design/07_evolution.md）：

• 执行 → 反馈 → 优化：根据执行反馈自动调优 Prompt
• 版本管理：Agent 和工作流变更可追溯、可回滚
• A/B 测试：灰度对比新旧版本 Agent 效果

想快速体验完整闭环，可以直接运行交互式构建器示例：

uv run python examples/interactive_builder_test.py

该示例（examples/interactive_builder_test.py）演示了边生成边调整：审核规划方案 → 逐步生成 Agent → 组装工作流 → 检查点与回滚。

六、不喜欢的地方？三种替代构建方式

除对话式构建外，QVerisFlow 还支持三种方式定义工作流：

• 命令行交互构建：uv run python examples/interactive_builder_test.py
• 代码定义：通过AgentDefinition/WorkflowDefinition编程式构建
• YAML 配置：直接维护 examples/workflows/ 下的工作流文件，用uv run python examples/run_workflow.py执行

七、总结

从一句"分析英伟达股票"到一份结构完整的投资分析工作流，QVerisFlow 把多智能体编排的复杂度收进了对话、画布和声明式配置里。如果你想深入理解架构设计，推荐按顺序阅读 docs/overall_design/00_overview.md 框架概览和 docs/overall_design/06_orchestration.md 工作流编排文档。