AskFlow

A LangGraph-based adaptive deep research agent with research budget control, evidence verification, targeted re-research, tool failure recovery, and dynamic model routing.

AskFlow 是一个基于 LangGraph + Open Deep Research 二次开发的深度研究 Agent。

项目保留了 Open Deep Research 的 Supervisor-Researcher 研究框架，并围绕真实 Agent 系统中的几个核心问题进行了进一步扩展：

• Agent 如何控制搜索与 Tool Calling 成本？
• 搜索到的信息是否真的足以回答用户问题？
• 证据不足时，应该重新研究什么，而不是机械重复搜索？
• Tool 超时、限流或服务异常时如何自动恢复？
• 不同 Agent 阶段是否应该使用不同模型？
• 如何将 LangGraph 的执行过程实时呈现到前端？

AskFlow 将这些问题拆解为 Research Budget Controller、Evidence Verifier、Adaptive Targeted Research、Tool Recovery、Search Fallback、Dynamic Model Router 等模块，并通过 React 前端提供完整的流式研究体验。

---

Architecture

flowchart TD
    A[User Query] --> B[Clarify With User]
    B --> C[Research Brief]
    C --> D[Research Supervisor]
    D --> E1[Researcher]
    D --> E2[Researcher]
    D --> E3[Researcher]
    E1 --> F[Evidence Verifier]
    E2 --> F
    E3 --> F
    F --> G{Evidence Sufficient?}
    G -- Yes --> J[Final Report]
    G -- No --> H[Plan Targeted Research]
    H --> I[Targeted Research]
    I --> F
    J --> K[Streaming Response]

Loading

AskFlow 的核心研究闭环：

Plan
  ↓
Research
  ↓
Verify
  ↓
Find Evidence Gaps
  ↓
Targeted Re-Research
  ↓
Verify Again
  ↓
Synthesize

---

Core Agent Improvements

1. Research Budget Controller

原始 ReAct Agent 中，“工具调用轮次”并不等价于真实 Tool Invocation 数量。一次 LLM 推理可以同时生成多个 Tool Call，因此 AskFlow 将 ReAct iteration 与 Tool invocation 拆成两套独立资源模型。

Budget	Description
max_react_iterations	单个 Researcher 最大 ReAct 推理轮数
max_tool_calls_per_iteration	单轮最多允许执行的预算型 Tool 数
max_total_tool_calls	单个 Researcher 最大逻辑 Tool 调用总量
max_concurrent_tool_calls	单个 Researcher 最大 Tool 并发量

Tool Call 在执行前会经过 Budget Admission：

LLM generated tool calls
          ↓
Identify budgeted tools
          ↓
Per-iteration budget
          ↓
Remaining total budget
          ↓
Admit / Reject
          ↓
Semaphore concurrency control
          ↓
Execute

think_tool、ResearchComplete 等控制类工具不会占用研究预算；基础设施 Retry 属于同一次逻辑 Tool Invocation，因此不会重复消耗预算。

当 Tool Budget 或 ReAct Budget 耗尽后，Researcher 会正常进入 compress_research，而不是异常退出。

---

2. Evidence Verification

“搜索完成”并不等于“证据已经足够”。

AskFlow 在 Research 与 Final Report 之间加入独立 Evidence Verifier：

Research
   ↓
Evidence Verifier
   ↓
Final Report / Targeted Research

Verifier 从多个维度评估当前研究资料：

• Coverage：是否覆盖用户要求的关键维度
• Credibility：当前证据来源是否足够可靠
• Conflict：多个来源之间是否存在关键冲突
• Missing Evidence：哪些结论仍缺少直接证据

核心结构：

VerificationResult
├── coverage_score
├── credibility_score
├── credibility_issues
├── conflicts
├── missing_evidence
├── evidence_gaps
├── evidence_sufficient
└── summary

Evidence Gap 进一步包含：

gap_type
topic
reason
importance
expected_information_gain

因此 Agent 不只是知道“当前研究还不够好”，而是知道具体缺什么证据，以及这个缺口是否值得继续搜索。

---

3. Adaptive Targeted Re-Research

AskFlow 不使用单纯的 Research N rounds → Stop 作为主要终止逻辑。

系统同时使用：

Hard Stop

• max verification iterations
• max ReAct iterations
• max Tool budget

Soft Stop

• evidence_sufficient
• expected_information_gain
• actionable_evidence_gaps

如果 Verifier 发现证据不足：

Evidence Verifier
        ↓
Evidence Gap
        ↓
Targeted Research Planner
        ↓
Targeted Research

新的 Researcher 不会重新研究完整问题，而是只针对缺口补充证据。

针对不同类型的 Evidence Gap：

coverage
→ 搜索缺失维度

credibility
→ 优先寻找官方 / 一手来源

conflict
→ 专门调查冲突来源及版本、时间、范围差异

Targeted Research 得到的新 Evidence 会与已有 Notes / Raw Notes 合并，并执行基础去重。

---

4. Tool Failure Recovery

AskFlow 增加独立 Tool Recovery Layer：

Tool Call
   ↓
Exception
   ↓
Error Classifier
   ↓
Retry Policy
   ↓
Retry / Fail Fast
   ↓
Search Fallback

不同 Provider / HTTP Client 的异常会统一归一化为 timeout、connection、rate_limit、server_error、bad_request、authentication、authorization、not_found、validation 等类别。

典型策略：

Error	Strategy
Timeout	Retry
Connection Error	Retry
HTTP 408	Retry
HTTP 429	Retry
HTTP 5xx	Retry
HTTP 400	Fail Fast
HTTP 401	Fail Fast
HTTP 403	Fail Fast
HTTP 404	Fail Fast
HTTP 422	Fail Fast

Retry 同时检查 Transient Error、Tool Idempotency 和 Retry Budget，并使用 Exponential Backoff + Random Jitter。

对于 Search Tool，系统提供 Search Fallback 策略基础设施：

Primary Search
      ↓
Transient Failure
      ↓
Retries Exhausted
      ↓
Fallback Search Provider

AskFlow 还区分 Infrastructure Retry 和 Agent Semantic Retry：网络异常由 Recovery Layer 处理；搜索结果为空或关键词效果差，则交回 Researcher 调整下一轮搜索策略。

---

5. Dynamic Model Router

不同 Agent 阶段对模型能力需求不同：

Clarification
→ Speed / Cost

Researcher
→ Tool Calling + Reasoning

Evidence Verifier
→ Structured Output + Reasoning

Compression
→ Long-context Synthesis

Final Report
→ Writing + Long Context

AskFlow 使用 Task-aware Model Router。

Router 首先执行硬约束筛选：

Tool Calling support?
Structured Output support?
Context Window enough?

随后根据 Task Type、Task Complexity、Estimated Context Size、Model Cost、Task Affinity 进行评分：

Agent Task
    ↓
Task Requirements
    ↓
Complexity Estimation
    ↓
Compatible Model Filter
    ↓
Cost / Capability Scoring
    ↓
Model Decision

任务复杂度使用 Rule-based Heuristics 判断，因此不会为了 Model Routing 再额外调用一次 LLM。

---

Streaming Frontend

AskFlow 提供 React + TypeScript Web Client，通过 @langchain/langgraph-sdk 直接连接 LangGraph Agent Server。

LangGraph 原始事件：

updates
messages-tuple

经过 Adapter Layer：

LangGraph Events
      ↓
deepResearch.ts
      ↓
progress
content
done

再交给 UI。

支持：

• Deep Research 阶段进度展示
• 最终报告 Token Streaming
• Markdown / Code Highlight
• Stop Generation
• Retry / Regenerate
• 多会话本地状态
• Streaming 自动滚动
• 用户主动上滑后暂停自动跟随
• 长消息虚拟列表

Frontend Stack：

React
TypeScript
Vite
Zustand
React Virtuoso
React Markdown
LangGraph SDK

---

Observability

AskFlow 在 Agent Runtime 中保留结构化日志：

[RESEARCH_BUDGET]
[TOOL_RECOVERY]
[SEARCH_FALLBACK]
[EVIDENCE_VERIFIER]
[ADAPTIVE_RESEARCH]
[MODEL_ROUTER]
[FINAL_REPORT_ERROR]

可用于观察 Research Iterations、Logical Tool Calls、Retry、Fallback、Evidence Gaps、Verification Rounds、Model Routing、Latency 和 Token Usage。

项目可以结合 LangSmith Trace 对完整 LangGraph Run 进行进一步分析。

---

Evaluation

AskFlow 使用一组统一的 Deep Research Tasks 对系统进行受控评测。

完整 Eval Dataset 包含 30 条 Research Tasks，覆盖：

• Production API Audit
• Framework Comparison
• Evidence-heavy Research
• Conflict Resolution
• Time-sensitive Research
• Budget Efficiency

考虑到完整 A/B/C 重复实验的 API 成本，最终正式对比采用一个 6-task stratified controlled benchmark：从上述六类任务中各选取 1 条。

api-01
cmp-01
evidence-05
conflict-01
current-01
efficiency-03

该 benchmark 用于分析系统架构与 Dynamic Model Router 的影响，不用于声明统计显著性。

Experimental Groups

Group	Configuration	Purpose
A	ODR-derived Baseline + Static qwen3.5-plus	Baseline
B	AskFlow + Router OFF + Static qwen3.5-plus	Architecture Ablation
C	AskFlow + Dynamic Model Router	Router Ablation

因此：

A → B
控制模型不变
→ 观察 AskFlow 架构本身的影响

B → C
控制 AskFlow 架构不变
→ 观察 Dynamic Model Router 的影响

Baseline 来源于 AskFlow 早期、尚未加入 Budget Controller / Evidence Verifier / Adaptive Research 等增强能力的 ODR-derived 版本。正式实验仅额外加入 Eval Observability 与必要的 Qwen provider compatibility patch，不改变其核心研究逻辑。

AskFlow 正式 B/C 实验冻结在同一生产逻辑 revision：

c109a2fd48c82389048c371b69ad6f0f34a4d439

Evaluation Protocol

三组实验共享：

same task set
same search provider
same runtime configuration
same static model for A/B
same Judge protocol

质量评估使用独立 LLM-as-Judge：

Judge Model: qwen3.5-plus
Temperature: 0
Structured Output: function_calling
Research Success Coverage Threshold: 0.80
Pairwise Order: blind + deterministic randomized order

Research Success 定义为：

execution_success
AND aspect_coverage >= 80%
AND no critical factual error

Pairwise Judge 不知道哪份报告来自 AskFlow 或 Baseline，仅根据报告本身判断：

• Required-aspect coverage
• Evidence quality
• Official / primary-source compliance
• Conflict handling
• Temporal awareness
• Unsupported certainty
• Final answer usefulness

---

Controlled Benchmark Results

Metric	A · Baseline Static	B · AskFlow Static	C · AskFlow Router
Execution Success	100%	100%	100%
Research Success	100%	100%	100%
Mean Aspect Coverage	100.00%	96.67%	98.15%
Mean E2E Latency	308.67 s	385.23 s	468.20 s
Median E2E Latency	315.89 s	366.60 s	347.25 s
Mean Logical Tool Calls	6.50	4.33	5.33
Mean External Search Requests	20.00	15.17	21.00
Mean LLM Calls	105.83	78.50	104.67
Mean API Cost / Task	¥2.0482	¥1.5488	¥1.8656
Total Benchmark API Cost	¥12.2894	¥9.2925	¥11.1934

API Cost 统计基于固定 pricing snapshot 与实际 token / search usage。Judge 成本与 Agent Runtime 成本分开计算。

---

Architecture Ablation — A vs B

A 与 B 使用相同的 qwen3.5-plus 静态模型，因此该对比主要反映 AskFlow 架构本身带来的变化。

从 A 到 B：

Mean API Cost          -24.4%
Logical Tool Calls     -33.3%
External Searches      -24.2%
LLM Calls              -25.8%

Mean E2E Latency       +24.8%

AskFlow Static 在这组 benchmark 中保持了：

Research Success = 6 / 6

同时明显减少了研究调用量与 API 成本。

代价是 Mean Aspect Coverage 从：

100.00%
→
96.67%

且 Blind Pairwise Judge 结果为：

Comparison	A Wins	B Wins	Ties
Baseline vs AskFlow Static	4	2	0

这表明 Budget Controller 与更严格的研究终止策略确实能够压缩资源使用，但部分任务中的 Evidence Depth / Source Quality 也可能随之下降。

因此 AskFlow Static 的结果更准确地体现为一种：

Resource Efficiency
        ↑
Research Depth / Latency Trade-off

而不是所有指标的单向提升。

---

Dynamic Router Ablation — B vs C

B 与 C 使用完全相同的 AskFlow Agent 架构，区别仅在于是否启用 Dynamic Model Router。

Router 会根据不同阶段动态选择模型，例如：

Research Brief
→ qwen3.5-flash

Simple Research / Webpage Summarization
→ qwen3.5-flash

Supervisor
→ qwen3.5-plus

Evidence Verification
→ qwen3.5-plus

Complex Research
→ qwen3.5-plus

Final Report
→ qwen3.5-plus

从 B 到 C：

Mean Aspect Coverage   96.67% → 98.15%

Mean API Cost          +20.5%
Mean E2E Latency       +21.5%
Logical Tool Calls     +23.1%
External Searches      +38.5%
LLM Calls              +33.3%

Blind Pairwise：

Comparison	B Wins	C Wins	Ties
Static vs Dynamic Router	4	2	0

这说明当前 Router V1 的收益具有明显的 task-dependent 特征。

例如 efficiency-03：

B:
cost    = ¥1.1608
latency = 322.5 s

C:
cost    = ¥0.8382
latency = 186.8 s

即 Router 在该任务上实现了：

Cost    ≈ -27.8%
Latency ≈ -42.1%

同时：

B coverage = 1.0
C coverage = 1.0
Blind Pairwise Winner = C

说明对合适的轻量阶段使用较低成本模型，可以同时降低成本与延迟而不损失最终质量。

但是在 Evidence-heavy 任务中，上游较弱模型也可能改变后续研究轨迹。

例如 evidence-05：

Initial Research
      ↓
Evidence Verifier
      ↓
Evidence Insufficient
      ↓
Targeted Re-Research
      ↓
Verify Again
      ↓
Final Report

最终导致额外 Search / LLM / Compression / Verification 开销。

因此当前 Router 更接近：

Local Invocation Cost Optimization

而未来更理想的目标是：

Expected End-to-End Agent Cost Optimization

即不仅考虑“当前模型调用是否更便宜”，还需要考虑弱模型导致：

• Additional Search
• Retry
• Evidence Gap
• Targeted Research
• Re-verification

的 downstream amplification risk。

---

Evidence Gap Repair

Dynamic Router 组中：

Targeted Research Triggered Tasks
= 1 / 6
= 16.67%

其中 evidence-05 的 Evidence Verifier 在第一轮研究后发现一个 actionable evidence gap。

系统执行：

Evidence Gap
    ↓
Targeted Research Planner
    ↓
Targeted Research
    ↓
Second Evidence Verification

Judge 对该真实补研路径的评估结果：

Triggered Actionable Gaps = 1
Repaired Gaps             = 1

也就是说，在本次 controlled benchmark 中：

1 个任务触发了 Targeted Re-Research，其 1 个 actionable evidence gap 经 Judge 判定被成功修复。

由于样本仅为 1 个 triggered gap，因此不将该结果泛化为整体系统的稳定 100% Repair Rate。

---

Stage-level Runtime Breakdown

AskFlow Eval 同时记录 Node-level Runtime。

这里区分：

End-to-End Latency
=
用户实际等待的 wall-clock time

Aggregate Node Work
=
所有 Node invocation 的累计运行时间

由于 Supervisor / Researcher / Tool Execution 存在并发和父子节点嵌套，Aggregate Node Work 可以显著大于 E2E Latency。

以下表格只使用最外层阶段，因此可以近似还原真实 wall-clock critical path：

Top-level Stage	A · Baseline	B · Static	C · Router
Research Brief	7.97 s	9.12 s	3.33 s
Research Supervisor	220.71 s	279.88 s	356.88 s
Evidence Verification	N/A	11.00 s	14.68 s
Targeted Research	N/A	N/A	17.55 s
Final Report	79.98 s	85.23 s	75.72 s
Top-level Stage Sum	308.67 s	385.22 s	468.18 s
Measured E2E Latency	308.67 s	385.23 s	468.20 s

一个重要现象是：

A → B

Researcher cumulative work
107.97 s → 94.46 s

Compression cumulative work
163.18 s → 133.84 s

AskFlow 实际减少了部分 Researcher 工作量。

但同时：

Research Supervisor wall-clock
220.71 s → 279.88 s

说明在并发 Agent 系统中：

Fewer LLM / Tool Calls
≠
Lower Wall-clock Latency

资源调用量降低后，Supervisor orchestration、较慢的单次 Tool execution、并发 critical path 等因素仍可能使整体 E2E latency 上升。

内部 Research 子图的累计节点工作如下：

Nested Research Node	A · Baseline	B · Static	C · Router
Supervisor	29.40 s	31.52 s	30.24 s
Supervisor Tools	191.31 s	248.35 s	326.64 s
Researcher	107.97 s	94.46 s	99.02 s
Researcher Tools	133.23 s	143.60 s	73.94 s
Compression	163.18 s	133.84 s	308.88 s

这些 Nested Runtime 是 cumulative node work，存在并发和父子嵌套，不能与 Top-level Runtime 相加。

---

Main Findings

本次正式受控 Eval 得到的主要工程结论：

1. Research Budget / Adaptive Stop
   能显著减少 Tool、Search 和 LLM 调用量。

2. Lower Resource Usage
   不一定直接转换成更低的 Wall-clock Latency。

3. Evidence Verification
   本身的额外延迟相对有限；
   更大的延迟来自整体 research orchestration critical path。

4. Dynamic Model Routing
   的收益高度依赖任务类型。

5. 对简单任务使用低成本模型
   可以同时降低成本和延迟。

6. 对 Evidence-heavy 任务过早使用较弱模型
   可能触发更多 Search / Targeted Research，
   从而抵消单次模型调用节省。

7. Targeted Re-Research
   在真实 Eval 中成功触发并修复了一个 Evidence Gap。

这也给 Dynamic Router 的下一版优化提供了明确方向：

Rule-based Router V1
        ↓
Downstream Risk Estimation
        ↓
Feedback-aware / Outcome-aware Router

未来 Router 不只估算当前 inference cost，还应估算：

Expected Total Cost
=
Current Model Cost
+
P(Follow-up Research) × Follow-up Cost

---

Limitations

当前结果需要结合以下限制理解：

• 正式 A/B/C Controlled Benchmark 仅包含 6 个任务，每类任务 1 个。
• 结果用于工程 Ablation 和系统行为分析，不声明统计显著性。
• Research Quality 使用单一 qwen3.5-plus LLM-as-Judge，未来可以增加多 Judge / Human Review。
• Web Search 与外部 API latency 本身存在运行时波动。
• Router V1 仍为 Rule-based Heuristics，并未通过历史 outcome 自动学习 routing policy。
• Evidence Gap Repair 在本次 benchmark 中仅有 1 个实际触发样本。
• 受到 Search Provider quota 或 Cost Telemetry 缺失污染的实验记录不会用于正式结果；对应任务在相同冻结代码与配置下进行一次 recovery run，原始记录保留用于审计。

因此这些结果主要用于回答：

系统改动如何改变
Research Cost
Tool Usage
Evidence Coverage
Agent Trajectory
Runtime Critical Path

而不是声称 AskFlow 在所有 Deep Research 任务上普遍优于 Baseline。

Testing

Backend：

cd backend
uv run python -m pytest tests -q

Frontend：

cd frontend
npm run build
npm run lint

核心测试覆盖 Research Budget、Evidence Verifier、Adaptive Research、Tool Error Classification、Tool Retry、Search Fallback、Model Router 与 Model Runtime Configuration。

---

Project Structure

AskFlow
│
├── backend
│   ├── src/open_deep_research
│   │   ├── deep_researcher.py
│   │   ├── state.py
│   │   ├── configuration.py
│   │   ├── prompts.py
│   │   ├── utils.py
│   │   ├── tool_recovery.py
│   │   ├── search_fallback.py
│   │   ├── model_router.py
│   │   └── model_utils.py
│   ├── tests
│   ├── langgraph.json
│   └── pyproject.toml
│
├── frontend
│   ├── src
│   │   ├── api
│   │   ├── components
│   │   ├── hooks
│   │   ├── store
│   │   └── type
│   └── package.json
│
└── README.md

---

Quick Start

Backend

cd backend
uv sync

复制环境变量：

cp .env.example .env

示例：

TAVILY_API_KEY=

BAILIAN_API_KEY=
BAILIAN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

LANGSMITH_API_KEY=
LANGSMITH_TRACING=false

启动 LangGraph：

uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.11 langgraph dev --allow-blocking

Agent API：

http://127.0.0.1:2024

Frontend

cd frontend
npm install
npm run dev

frontend/.env：

VITE_LANGGRAPH_API_URL=http://localhost:2024

---

Demo

部署或录制 Demo 后，可以在这里加入：

<p align="center">
  <img src="./docs/demo.gif" width="900" alt="AskFlow Demo" />
</p>

---

Based on Open Deep Research

AskFlow backend is based on LangChain Open Deep Research:

https://github.com/langchain-ai/open_deep_research

AskFlow 在原始 Supervisor-Researcher 架构上增加：

Research Budget Controller
Evidence Verification
Adaptive Targeted Re-Research
Tool Failure Recovery
Search Fallback
Dynamic Model Router
React Streaming Client

原始 Open Deep Research 项目采用 MIT License，见 backend/LICENSE。

---

Design Principle

More Agents
≠
Better Agent System

AskFlow 更关注：

Resource Governance
Evidence Quality
Adaptive Decision Making
Failure Recovery
Model Selection
Observability

只有当不同 Agent 真正拥有不同 Tool、权限、State 和执行策略时，才值得进一步拆分。

---

Roadmap

• Controlled AskFlow Eval with static-model architecture ablation and dynamic-router ablation
• Publish evaluation results
• LangSmith observability cleanup
• Demo GIF / screenshots
• Public demo deployment
• Optional RAG / private knowledge research

---

Author

CabbageCannon

GitHub: https://github.com/CabbageCannon