【无标题】 - 技术栈

第二阶段综合学习笔记：RAG + Tools + Memory + Failure Handling + Evidence Agent

阶段目标：会做 RAG；会把搜索、数据库、文件、浏览器、代码执行接成工具；会区分短期上下文、会话记忆、长期记忆；会处理工具失败、空结果、重复调用、幻觉引用；会在答案中提供代理轨迹或证据。

0. 本阶段学习资源与定位

本阶段实际学习了四类资源：

LlamaIndex Agents：重点学习 Agent、RAG、QueryEngineTool、Context / Memory、Workflow、事件流、引用式 RAG。
LangChain / LangGraph ：重点学习 create_agent、Tools、Retrieval、Memory、Middleware、StateGraph、interrupt、LangSmith 可观测性。
Gemini Code Execution：重点学习代码执行作为 Agent 工具的定位、响应结构、执行结果留证、文件/图表 I/O、运行限制和失败处理。
MCP：重点学习 Host / Client / Server 架构，Tools / Resources / Prompts 三类能力，协议化工具发现、工具调用、权限、安全和证据记录。

这四套资料分别回答了 Agent 工程中的不同问题：

text 复制代码

LlamaIndex：如何围绕数据构建 RAG / Agent / Workflow。
LangChain / LangGraph：如何构建状态化、可中断、可观测的 Agent Loop。
Gemini Code Execution：如何把 Python 执行能力作为可验证工具接入 Agent。
MCP：如何标准化连接文件、数据库、搜索、浏览器、业务 API 等外部系统。

1. 第二阶段的核心结论

第二阶段最重要的结论是：Agent 不是一个单次 LLM 调用，而是一个受控执行系统。

一个可落地 Agent 至少包含六层：

text 复制代码

1. 模型决策层：判断下一步是回答、检索、调用工具、继续规划还是终止。
2. 信息获取层：RAG、搜索、文件读取、数据库查询、浏览器抓取。
3. 工具执行层：搜索、SQL、文件、浏览器、代码执行、业务 API。
4. 状态记忆层：短期上下文、会话状态、长期记忆、外部知识库。
5. 可靠性控制层：超时、重试、最大步数、空结果、重复调用、人工确认。
6. 证据输出层：引用、工具调用轨迹、执行结果、限制说明。

换句话说，Agent 工程的核心不是"让模型自主思考"，而是：给模型有限的动作空间，给工具清晰的边界，给状态明确的生命周期，给输出可验证的证据。

2. 统一 Agent Loop

综合 LlamaIndex、LangChain / LangGraph、Gemini Code Execution 和 MCP，第二阶段应掌握的标准 Agent Loop 如下：

text 复制代码

User Task
  -> Normalize / classify task
  -> Load short-term context and session state
  -> Decide next action
      -> answer directly
      -> retrieve internal documents
      -> search external web
      -> query database
      -> read file / browser page
      -> execute code
      -> ask human for confirmation
  -> Execute selected tool
  -> Validate tool result
      -> success / empty / error / low confidence / unsupported
  -> Store observation and evidence
  -> Decide continue or final
  -> Verify citations and claims
  -> Return answer + evidence + agent trace

这个循环必须有工程边界：

text 复制代码

max_steps：防止无限循环。
timeout：防止工具长时间阻塞。
retry_policy：控制工具失败后是否重试。
duplicate_call_guard：阻止相同工具和参数重复调用。
evidence_required：要求关键结论必须绑定证据。
human_approval：高风险工具必须人工确认。

Agent 的每一步都应该产生可记录的事件：

text 复制代码

AgentInput
Plan / Decision
ToolCall
ToolResult
EvidenceSelected
CitationVerified
FinalAnswer
Error / Fallback

用户可见的是压缩后的代理轨迹，不是模型隐藏推理过程。

3. RAG：从"向量搜索"升级为证据系统

3.1 RAG 的基本闭环

第二阶段要求会做 RAG，但这里的 RAG 不能只理解成"embedding + vector search"。完整 RAG 闭环应包括：

text 复制代码

Load -> Parse -> Chunk -> Enrich Metadata -> Embed -> Store -> Retrieve -> Rerank / Filter -> Synthesize -> Cite -> Evaluate

各阶段的工程职责如下：

阶段	工程职责	常见失败
Load	接入 PDF、网页、Markdown、CSV、数据库、API	文件格式错误、权限不足、编码问题
Parse	抽取正文、表格、标题、页码、结构	表格丢失、标题层级错乱、OCR 错误
Chunk	切分为可检索节点	chunk 太大、太小、语义断裂
Metadata	保留 source、page、section、url、timestamp	后续无法引用或过滤
Embed	生成向量表示	模型不匹配、长文本截断
Store	存入 vector store / doc store	重复索引、版本不一致
Retrieve	根据 query 找候选证据	召回不足、query 不清晰
Rerank / Filter	过滤低相关、重复和冲突证据	误删有效证据
Synthesize	基于证据生成答案	幻觉、过度概括
Cite	绑定 source node	引用不存在、引用不支持结论
Evaluate	检查正确性、忠实性、覆盖率	缺少评估集和 trace

3.2 分块策略

分块不是纯长度问题，而是检索单元设计问题。建议按以下优先级设计：

text 复制代码

优先保留结构：标题、章节、页码、表格、代码块。
再控制长度：chunk size 与 overlap 只是下限方案。
必须保留元数据：source_id、document_title、page、section、timestamp。
表格和代码不要随意切断。
一个 chunk 最好表达一个相对完整的信息单元。

推荐分块方式：

文档类型	推荐策略
Markdown / 技术文档	按标题层级切分，再控制长度
PDF 报告	页码 + 标题 + 段落混合切分
FAQ / 知识库	按问答对切分
代码文件	按函数、类、模块切分
CSV / 表格	不宜直接普通 chunk；优先结构化查询或代码执行
网页	清洗导航、广告、页脚后按正文结构切分

3.3 检索策略

第二阶段要区分普通 RAG 和 Agentic RAG。

普通 RAG：

text 复制代码

用户问题 -> 检索 -> 生成答案

适合稳定知识库问答、低延迟应用、流程明确的任务。

Agentic RAG：

text 复制代码

用户问题 -> Agent 判断是否检索 -> 改写 query -> 检索 -> 判断是否足够 -> 可能继续检索 / 搜索 / 查询数据库 -> 生成答案

适合复杂研究任务、跨来源问题、需要多步验证的问题。

检索层建议支持：

text 复制代码

vector retrieval：语义召回。
keyword / BM25：精确术语、代码、实体名。
hybrid retrieval：语义 + 关键词融合。
metadata filter：按时间、文档类型、权限、来源过滤。
reranker：对 top-k 候选结果重排。
similarity cutoff：过滤低相关节点。
deduplication：去除重复或近似重复 chunk。

3.4 引用式回答

RAG 的最终输出不是"模型看过资料后的回答"，而是"基于证据的回答"。每个关键结论都应当能追溯到 source node。

推荐输出结构：

text 复制代码

结论：
...

证据：
[1] 文档名 / 页码 / 章节 / URL / chunk 摘要
[2] ...

代理轨迹：
- 使用 document_retriever 检索到 12 个节点
- rerank 后保留 5 个节点
- 未调用 web_search，因为内部证据足够

限制：
- 没有覆盖 2026 年之后的外部变化
- 某些数据源未提供原始表格

引用规则：

text 复制代码

1. 引用编号必须对应真实 source node。
2. 关键事实必须有引用。
3. 引用必须实际支持对应结论。
4. 若证据不足，不允许编造答案。
5. 若证据冲突，必须说明冲突，而不是强行给单一结论。

4. 工具系统：工具是 Agent 的外部能力边界

4.1 工具不是普通函数

工具是给模型使用的外部能力接口。它的名称、描述、参数 schema、返回格式都会影响模型是否正确调用。

一个合格工具至少应定义：

text 复制代码

tool_name：清晰、具体、动词化。
description：说明什么时候使用，什么时候不该使用。
input_schema：参数类型、必填字段、约束、枚举。
output_schema：结构化返回，避免只返回自然语言。
error_schema：失败时返回可解释错误。
side_effect_level：none / low / medium / high。
timeout：最大执行时间。
retry_policy：是否允许重试。
permission_policy：是否需要人工确认。
citation_capability：结果是否可作为证据。

坏工具示例：

text 复制代码

search(q: str) -> str
描述：search things

好工具示例：

text 复制代码

search_web(query: str, freshness_days: int, allowed_domains?: list[str]) -> SearchResults
描述：用于查询开放网络上的最新事实、新闻、文档和外部参考来源。不用于查询内部文档。
返回：[{title, url, snippet, published_at, source_type, confidence}]
失败：{error_code, message, retryable}

4.2 工具分类

第二阶段需要接入的工具可以分成六类：

工具类型	典型用途	是否有副作用	证据能力
搜索工具	查开放网络、最新信息	无	URL、snippet、时间
数据库工具	查结构化数据	读操作无；写操作高风险	SQL、结果表、行数
文件工具	读取 PDF、Markdown、CSV、代码	读操作无；写/删高风险	文件名、页码、片段
浏览器工具	打开页面、抽取正文、点击	点击/提交可能高风险	URL、页面片段
代码执行工具	计算、统计、CSV 分析、图表	沙箱内低风险	代码、stdout、图表、结果
业务 API 工具	邮件、日历、工单、订单	常有副作用	API 响应、操作记录

4.3 工具调用决策

Agent 不应默认调用工具，而应根据问题类型选择动作：

text 复制代码

如果问题可由当前上下文回答：直接回答。
如果问题需要内部资料：调用 document_retriever。
如果问题需要最新外部信息：调用 web_search。
如果问题需要结构化统计：优先 database_query 或 code_execution。
如果问题需要网页细节：browser_fetch / browser_extract。
如果问题涉及高风险写操作：先 human_approval。
如果工具结果不足：改写 query 或换工具，但不能无限重试。

4.4 工具结果必须结构化

工具返回不应只是字符串。建议统一返回：

json 复制代码

{
  "status": "success | empty | error | denied",
  "data": {},
  "evidence": [],
  "metadata": {
    "tool_name": "...",
    "args": {},
    "duration_ms": 0,
    "source": "...",
    "timestamp": "..."
  },
  "error": {
    "code": "...",
    "message": "...",
    "retryable": true
  }
}

这样 Agent 才能判断是否继续、重试、降级或拒答。

5. MCP：工具协议化的工程意义

MCP 的核心价值是把外部系统接入标准化。它不是 Agent 框架，也不是 RAG 框架，而是 Agent 与工具/资源/提示模板之间的协议层。

MCP 的架构是：

text 复制代码

Host：用户交互的 AI 应用。
Client：Host 内部创建的连接管理器。
Server：暴露工具、资源、提示模板的外部能力提供者。

典型结构：

text 复制代码

Agent Host
  -> MCP Client: filesystem server
  -> MCP Client: database server
  -> MCP Client: search server
  -> MCP Client: browser server
  -> MCP Client: code execution server

MCP Server 可以暴露三类 primitive：

Primitive	控制方	工程含义
Tools	model-controlled	模型可主动调用的动作，如搜索、查询、执行代码
Resources	application-controlled	应用提供给模型的上下文，如文件、schema、文档
Prompts	user-controlled	用户可选择的任务模板或工作流模板

这对第二阶段非常重要：

text 复制代码

搜索、数据库查询、浏览器抽取、代码执行：适合做成 Tool。
数据库 schema、项目 README、文件目录、API 文档：适合做成 Resource。
引用式回答模板、代码审查模板、故障排查模板：适合做成 Prompt。

MCP 的工具发现流程是：

text 复制代码

Client initialize
  -> tools/list
  -> Server 返回工具名、描述、inputSchema
  -> Host 将工具注册给 LLM
  -> LLM 选择工具
  -> tools/call
  -> Server 执行并返回结果
  -> Host 把结果纳入 Agent 状态和证据包

工程要求：

text 复制代码

工具必须可发现。
工具必须有 schema。
工具必须有错误返回。
工具调用必须可审计。
高风险工具必须有人类确认。
工具结果必须能进入 evidence pack。

6. 代码执行工具：什么时候让 Agent 写代码

Gemini Code Execution 提供了一个重要样本：代码执行可以作为模型内置工具，让模型生成并运行 Python，再根据执行结果迭代生成最终答案。

从 Agent 工程角度，代码执行工具适合：

text 复制代码

数学计算。
统计分析。
CSV / 表格处理。
文本批处理。
数据清洗。
图表生成。
结果验证。
小规模模拟。

不适合：

text 复制代码

访问外部网络。
修改真实文件系统。
执行长时间任务。
调用业务 API。
处理敏感数据。
执行不可信用户代码。
安装任意依赖。

代码执行和 Function Calling 的区别：

能力	Code Execution	Function Calling / Tool Calling
执行主体	模型生成代码，在沙箱执行	应用侧调用外部函数/API
适合任务	计算、分析、图表、验证	搜索、数据库、业务系统、文件、浏览器
结果证据	代码、stdout、图表、计算结果	API 返回、文档片段、数据库结果
风险	幻觉代码、超时、错误计算	权限、副作用、外部系统失败
工程重点	沙箱、限制、结果验证	schema、权限、错误处理、审计

代码执行结果应进入证据包：

text 复制代码

executable_code：模型生成的代码。
execution_result：stdout / stderr / 变量输出。
artifacts：图表、文件、表格。
limitations：运行时间、库限制、输入数据范围。

失败处理：

text 复制代码

代码报错：允许有限次数修正。
超时：停止执行，改用更小数据或说明失败。
库缺失：换用内置库或拒绝。
结果异常：用独立方法校验或要求人工检查。
数据过大：抽样、分批或转数据库处理。

7. 记忆与上下文：必须分层，不可混用

第二阶段必须清晰区分四类信息：

text 复制代码

短期上下文：一次 Agent run 内的输入、工具结果、临时证据。
会话记忆：一个 thread / conversation 内的历史消息、阶段目标、当前任务进度。
长期记忆：跨会话稳定存在的用户偏好、项目约束、长期事实。
外部知识库：文档、数据库、网页、文件系统、向量库。

7.1 短期上下文

短期上下文只服务当前任务：

text 复制代码

当前用户问题。
当前计划。
已调用工具。
当前证据节点。
工具错误。
最终答案草稿。

生命周期：一次运行或一个短任务。

不应该写入长期记忆。

7.2 会话记忆

会话记忆服务当前 conversation：

text 复制代码

用户在本会话中确认的目标。
已经完成的学习阶段。
当前任务的偏好。
中间产物路径。
已选方案。

生命周期：一个 thread。

适合通过 checkpointer / context / session state 保存。

7.3 长期记忆

长期记忆只保存稳定、高价值、可复用的信息：

text 复制代码

用户长期偏好。
项目固定约束。
稳定身份信息。
长期使用的格式要求。

长期记忆写入必须谨慎：

text 复制代码

不要写入未经验证的搜索结果。
不要写入临时工具结果。
不要写入一次性偏好。
不要写入敏感信息。
必须允许审计和删除。

7.4 外部知识库

外部知识库不是 memory。它包括：

text 复制代码

向量库。
文档库。
数据库。
文件系统。
网页缓存。
搜索索引。

这些内容应该通过 RAG 或工具检索，不应该混进长期用户记忆。

8. 失败处理：可靠 Agent 的关键

第二阶段必须掌握的失败模式如下：

失败类型	检测方式	处理策略
工具超时	timeout	重试一次；仍失败则降级
工具参数错误	schema validation failed	重写参数；最多一次
工具权限失败	permission denied	请求授权或说明无法执行
搜索空结果	result_count = 0	改写 query；仍为空则拒答
RAG 低相关	similarity < threshold	扩大 top-k、换检索器、说明不足
检索重复	duplicate chunks	去重，保留最高质量来源
引用缺失	citation list empty	不输出证据型答案，重新生成或拒答
引用不支持结论	claim-source mismatch	删除结论或标注不确定
工具重复调用	same tool + same args	阻断循环，换策略
最大步数耗尽	step >= max_steps	停止并说明未可靠完成
状态污染	临时事实写入长期记忆	阻止写入，改存 evidence cache
高风险操作	side_effect_level high	人工确认

8.1 最小可靠 Agent Loop 伪代码

python 复制代码

MAX_STEPS = 8
seen_calls = set()
evidence_pack = []

for step in range(MAX_STEPS):
    action = planner(state)

    if action.type == "final_answer":
        result = verify_answer(action.answer, evidence_pack)
        if result.ok:
            return format_answer(action.answer, evidence_pack, trace)
        state.add_error("citation_verification_failed")
        continue

    if action.type == "tool_call":
        call_key = (action.tool_name, normalize(action.args))
        if call_key in seen_calls:
            state.add_error("duplicate_tool_call")
            continue
        seen_calls.add(call_key)

        tool = tool_registry[action.tool_name]
        if tool.side_effect_level == "high":
            approved = ask_human_approval(action)
            if not approved:
                state.add_error("human_denied")
                continue

        result = execute_tool(tool, action.args)

        if result.status == "error":
            handle_error(result)
            continue

        if result.status == "empty":
            state.add_observation("empty_result")
            continue

        evidence_pack.extend(result.evidence)
        state.add_observation(result.data)

return fallback_response(state, evidence_pack, trace)

8.2 Fallback （回退、应急措施）原则

失败后不应该直接胡编答案。应按顺序降级：

text 复制代码

1. 修正参数后重试。
2. 改写 query 后重试。
3. 换工具或换检索策略。
4. 缩小问题范围。
5. 输出已有证据和限制。
6. 明确拒答。

9. 证据化回答：答案必须可追溯

第二阶段的最终输出不应只有自然语言答案，而应包含三类可验证信息：

text 复制代码

1. 结论：回答用户问题。
2. 证据：文档片段、URL、数据库结果、代码执行结果、文件来源。
3. 代理轨迹：调用了哪些工具，得到什么结果，做了什么过滤。

推荐结构：

text 复制代码

结论
...

依据
[1] source_type=document, title=..., page=..., chunk=...
[2] source_type=web, url=..., published_at=..., snippet=...
[3] source_type=database, sql=..., row_count=...
[4] source_type=code, code_hash=..., stdout=...

代理轨迹
- classify_task: 需要内部文档 + 代码执行
- document_retriever: top_k=10, kept=4
- code_execution: 成功，输出 2 张表
- citation_check: 通过

限制
- 未查询外部网页
- 数据截止到 source metadata 中的时间

9.1 Evidence Pack 设计

建议统一 evidence pack：

json 复制代码

{
  "evidence_id": "E1",
  "type": "document | web | database | code | file | tool_result",
  "source": {
    "title": "...",
    "url": "...",
    "file_path": "...",
    "page": 0,
    "section": "..."
  },
  "content": "支持结论的最小片段",
  "metadata": {
    "retrieved_by": "document_retriever",
    "score": 0.83,
    "timestamp": "...",
    "tool_args": {}
  },
  "supports_claims": ["C1", "C2"]
}

9.2 Claim Check

最终答案应拆成 claims（明确可验证的陈述）：

text 复制代码

C1: xxx。
C2: xxx。
C3: xxx。

每个 claim 至少满足之一：

text 复制代码

有 evidence 支持。
是纯逻辑推论，并明确说明。
是用户已提供信息。
是常识性、不需工具的背景信息。

否则应删除或标注不确定。

10. LlamaIndex、LangChain、Gemini、MCP 的互补关系

体系	最适合解决的问题	在第二阶段中的定位
LlamaIndex	RAG、数据索引、QueryEngine、引用式问答	信息获取与证据系统
LangChain	Agent harness、tools、middleware、retrieval	Agent 快速构建与工具调用
LangGraph	状态机、持久化、interrupt、人类审批	可控 Agent Loop
Gemini Code Execution	Python 计算、文件分析、图表、验证	代码执行工具样本
MCP	标准化连接外部工具、资源、提示模板	工具协议层

一个成熟 Agent 不必只选一种框架。更重要的是理解抽象层：

text 复制代码

RAG 框架解决"知识如何检索"。
Agent 框架解决"下一步做什么"。
Workflow / Graph 解决"执行顺序和状态如何控制"。
Code Execution 解决"如何执行计算和分析"。
MCP 解决"工具和上下文如何标准化接入"。
Observability 解决"行为如何追踪和评估"。

11. 最终目标：Research Agent 设计蓝图

第二阶段最终应能设计一个 Research Agent。它的目标不是闲聊，而是完成可验证研究任务。

11.1 能力范围

text 复制代码

1. 读取用户问题。
2. 判断需要哪些信息源。
3. 检索内部文档。
4. 必要时搜索外部网页。
5. 必要时查询数据库。
6. 必要时读取文件或网页。
7. 必要时执行代码进行计算或分析。
8. 收集证据并验证引用。
9. 输出答案、证据和代理轨迹。
10. 在证据不足时拒答或说明限制。

11.2 工具集合

text 复制代码

document_retriever(query, filters) -> evidence nodes
web_search(query, freshness_days, domains?) -> web evidence
database_query(question_or_sql, readonly=True) -> table evidence
file_reader(path, query?) -> file chunks
browser_fetch(url) -> page content
browser_extract(url, query) -> targeted page evidence
code_executor(code, input_files?) -> stdout / charts / tables
citation_checker(answer, evidence_pack) -> verification result
human_approval(action_summary, risk_level) -> approved / denied

11.3 状态结构

json 复制代码

{
  "user_task": "...",
  "task_type": "research | qa | analysis | action",
  "plan": [],
  "step_count": 0,
  "tool_calls": [],
  "observations": [],
  "evidence_pack": [],
  "errors": [],
  "memory": {
    "short_term": {},
    "session": {},
    "long_term_candidates": []
  },
  "final_answer": null
}

11.4 Agent Trace 示例

text 复制代码

代理轨迹：
1. 识别问题需要内部资料和外部最新信息。
2. 调用 document_retriever，检索到 15 个节点。
3. rerank 后保留 6 个节点。
4. 调用 web_search 查询最新资料，保留 3 个网页来源。
5. 发现一个统计问题，调用 code_executor 计算均值和趋势。
6. 对最终答案做 citation_check，删除 1 条证据不足的结论。
7. 输出答案、证据和限制。

11.5 最小实现路线

推荐按四步实现：

text 复制代码

Step 1：2-step RAG
Document -> Chunk -> Embed -> Retrieve -> Answer with citations

Step 2：Agentic RAG
把 retriever 包成 tool，让 Agent 判断何时检索。

Step 3：Multi-tool Research Agent
加入 web_search、file_reader、database_query、code_executor。

Step 4：Reliable Agent
加入 max_steps、retry、duplicate guard、human approval、citation checker、agent trace。

12. 第二阶段工程检查清单

12.1 RAG Checklist

text 复制代码

[ ] 文档是否保留 source/page/section/url 元数据？
[ ] chunk 是否语义完整？
[ ] 是否支持 metadata filter？
[ ] 是否支持 hybrid retrieval 或 rerank？
[ ] 是否有 similarity cutoff？
[ ] 是否能处理空检索？
[ ] 答案是否绑定 source nodes？
[ ] 是否能验证引用支持结论？

12.2 Tools Checklist

text 复制代码

[ ] 工具名是否清晰？
[ ] 描述是否说明使用边界？
[ ] 参数 schema 是否严格？
[ ] 返回是否结构化？
[ ] 错误是否结构化？
[ ] 是否定义 timeout？
[ ] 是否定义 retry？
[ ] 是否标注 side_effect_level？
[ ] 高风险工具是否人工确认？
[ ] 工具结果是否能进入 evidence pack？

12.3 Memory Checklist

text 复制代码

[ ] 当前信息属于短期上下文、会话状态、长期记忆还是外部知识？
[ ] 是否避免把搜索结果写入长期记忆？
[ ] 是否有 thread/session 隔离？
[ ] 是否允许长期记忆审计和删除？
[ ] 是否避免 memory 污染 prompt？

12.4 Failure Checklist

text 复制代码

[ ] 是否设置 max_steps？
[ ] 是否检测重复工具调用？
[ ] 是否处理工具超时？
[ ] 是否处理空结果？
[ ] 是否处理低相关检索？
[ ] 是否处理 schema validation error？
[ ] 是否有 fallback 策略？
[ ] 是否在证据不足时拒答？

12.5 Evidence Checklist

text 复制代码

[ ] 每个关键结论是否有证据？
[ ] 引用是否真实存在？
[ ] 引用是否支持对应 claim？
[ ] 是否区分文档、网页、数据库、代码执行证据？
[ ] 是否输出工具调用轨迹？
[ ] 是否说明限制和不确定性？

13. 本阶段最终认知

第二阶段的最终成果不应是"会用某个框架"，而是具备一套 Agent 工程判断能力：

text 复制代码

看到一个任务，能判断是否需要 RAG。
看到一个外部能力，能判断应该做成 Tool、Resource 还是 Prompt。
看到一段信息，能判断属于上下文、会话记忆、长期记忆还是外部知识库。
看到工具失败，能决定重试、换工具、降级还是拒答。
看到一个答案，能检查它有没有证据支撑。

真正可落地的 Agent，不是"能调用很多工具"的 Agent，而是：

text 复制代码

能控制工具边界；
能管理状态生命周期；
能处理失败；
能在证据不足时停止；
能把结论和证据一起交付。

这就是第二阶段的核心目标。

14. 后续建议：进入第三阶段前的实操任务

建议在进入第三阶段前完成一个最小项目：

text 复制代码

项目：Evidence-based Research Agent

输入：一个研究问题 + 一组本地文档 + 可选网页搜索。
能力：
1. 文档 ingestion 与 chunk。
2. 向量检索 + rerank。
3. retriever 作为工具。
4. web_search 作为工具。
5. code_executor 作为工具。
6. 短期状态保存。
7. max_steps + duplicate guard。
8. citation checker。
9. 输出 answer + evidence + trace。

验收标准：

text 复制代码

[ ] 能回答有证据支持的问题。
[ ] 能拒绝无证据问题。
[ ] 能展示调用过的工具。
[ ] 能展示引用来源。
[ ] 能处理空检索。
[ ] 能处理工具失败。
[ ] 不重复调用同一工具进入循环。
[ ] 不把临时证据写入长期记忆。

完成这个项目，才说明第二阶段真正转化成了工程能力。

15. 参考资料

LlamaIndex Agents: https://docs.llamaindex.ai/en/stable/use_cases/agents/
LangChain Agents: https://docs.langchain.com/oss/python/langchain/agents
LangChain Retrieval: https://docs.langchain.com/oss/python/langchain/retrieval
LangChain Tools: https://docs.langchain.com/oss/python/langchain/tools
LangChain Short-term Memory: https://docs.langchain.com/oss/python/langchain/short-term-memory
LangChain Middleware: https://docs.langchain.com/oss/python/langchain/middleware/built-in
Gemini Code Execution: https://ai.google.dev/gemini-api/docs/code-execution
Model Context Protocol Architecture: https://modelcontextprotocol.io/docs/learn/architecture
MCP Server Concepts: https://modelcontextprotocol.io/docs/learn/server-concepts