实验 1-1

假设模型刚用计算器得到一个结果，下一轮却看不到这条工具消息。它还能可靠地继续计算吗？本实验用同一任务的不同上下文版本，帮助你理解模型的行为为什么取决于它实际收到的信息。

建议按以下顺序阅读：理解问题与方法 → 准备环境与输入 → 按照步骤完成实验 → 分析结果与形成判断 → 阅读实现与继续探索 → 排查问题与查阅资料。

理解问题与方法

把一类信息从完整输入中移除，再比较行为，称为消融实验。这里分别考察历史消息、推理内容、工具定义和工具结果。它们承担不同职责：工具定义说明能做什么，工具结果说明刚才发生了什么；两者不能相互替代。

沿一轮调用理解四类上下文

把 Agent 的一轮执行写成“读消息 → 选择动作 → 执行工具 → 读工具结果”。历史消息帮助它知道任务进展，工具定义帮助它选择动作，工具结果提供刚刚取得的事实。实验中的消融开关分别移除这些输入，因此应先读懂完整模式的轨迹，再观察移除信息以后哪里发生变化。推理文本与外部执行结果来源不同；不能把模型自己的解释当作工具已经执行的证据。

概述

对应书中实验 1-1 ★★：上下文的关键作用。Agent 可以读取 PDF、换算货币、计算表达式和执行 Python。你可以分别移除历史消息、推理内容、工具定义或工具结果，观察它怎样完成同一任务。下面的配置说明供你在跑通第一个对照后查阅。

主要特性

• 多提供商支持：阿里云百炼（Qwen 直连）、SiliconFlow（Qwen）、Doubao（字节）、Kimi（月之暗面）、DeepSeek
• 多工具 Agent：PDF 解析、货币换算、计算与 Python 代码执行
• 上下文模式：五种配置，用于消融对照
• 交互与批处理：单任务运行或完整测试套件
• 对话历史：同一会话内跨多轮查询保持上下文
• 详细分析：性能指标、可视化与综合报告

架构

上下文组件

1. Full Context — 完整 Agent，保留全部组件
2. No History — 缺少历史工具调用追踪
3. No Reasoning — 无战略规划/思考过程
4. No Tool Calls — 无法执行外部工具
5. No Tool Results — 看不到工具执行结果

可用工具

• parse_pdf(url) — 下载并抽取 PDF 文本
• convert_currency(amount, from, to) — 货币换算
• calculate(expression) — 简单数学表达式求值
• code_interpreter(code) — 执行 Python，用于复杂计算、汇总与数据处理

消融实验

已验收的 Kimi K3 真实执行（2026-08-25）

run_experiment_1_1.py 会按正文运行五个精确实验组，并保存每轮真实 API 的无凭据 请求与响应，而不只是汇总表：

python run_experiment_1_1.py --provider kimi

--model 可省略，缺省取共享注册表（agentbook/providers）中该提供商的默认模型。 选定一个提供商却写另一个提供商的模型名，正是 #971外部资源 ↗ 中五组全部失败的原因； 现在只传 --provider 就够了：

export DASHSCOPE_API_KEY=your_key_here
python run_experiment_1_1.py --provider dashscope     # 使用 qwen3.7-plus

验收产物见 validation/latest.json（该材料暂未包含在当前内容中）。只有既是标准配置 （五组齐全、带约束的任务、静默隐藏工具结果）又通过验收的运行才会覆盖它；其余运行 只写自己的时间戳目录，不会动被引用的证据。

怎么读一组实验

completed 表示 Agent 循环返回了终止响应，不代表任务做对了。旧字段 success 是 completed 的别名，task_success 才是数值评分标准。三者都区分不出「消融组没给出 答案」的两种情况，因此每组还带一个 outcome：

unsupported_numbers 正是 Completed 那一列永远显示不出来的情况，也是生产中真正 要命的一种：用记忆中的汇率拼出来的答案，排版和用工具结果算出来的答案一模一样。它由 grounding.py 依据实际发出的消息计算，因此被隐藏了观测的实验组 无论框架本地算出了什么，都无处可依。

可依据性与正确性是两条独立的轴——没有观测却报出 正确总数的模型，同样不是「读到」的。no_unsupported_numbers 同时涵盖「明确拒绝」和 「只说了一句打算怎么做就停下」；区分这两者属于对意图的判断，本框架不做。

实测结果（下方「预期行为」表是设计预期，不是实测）：

后两组在多次运行之间并不稳定；「移除工具执行结果」组反复运行的实际表现见下表。

analysis.manuscript_behavior_claims 保存正文行为结论的布尔值， all_manuscript_behavior_claims_observed 为 false。对于根本没有到达提供商的实验组， 结论记为 null 而不是 true——四条结论里有两条是以「没有发生什么」表述的，一次失败 的请求就能白白满足它们。analysis.claim_qualifications 则记下：「移除工具定义后没有 工具行动」是构造性必然，请求里没有工具定义，模型本就发不出工具调用；唯一可观察的是 它转而做了什么。

两个会改变结论的开关

两者默认都是标准配置；提供另一个取值，是因为它确实会改变结果，而这值得看见。支撑数据 见 validation/probes_20260825T/（该材料暂未包含在当前内容中），汇总在其 index.json。

--task guarded|unguarded 控制提示词里的一句话：「不要自行估计汇率，请使用工具 观测。」 在带约束（标准）的任务下，Kimi K3 的「移除工具定义」组不会声称任何未被给予 的数字；去掉这一句，同一个模型、同一组实验就给出了 $9,587,333.33——与工具汇率表相差 0.16%，汇率是它自己补上的，附带的「基于所假设汇率」说明，只看总数的读者根本不会注意到。

这条约束确实起作用，但它只是概率上的偏移，不是开关：在带约束的任务下，同一个模型 仍有 2/13 组报出了无依据的数字。而且这里无法把提示词和模型分开——这批运行期间除 Moonshot 外的提供商都不可用，没有在固定提示词下比较过两个模型。不同模型的幻觉率差异 很大，那多半才是更主要的因素；提示词约束只能降低概率，不能消除。两者都不能依赖，这正是 可依据性检查存在的意义。

python run_experiment_1_1.py --provider kimi --modes no_tool_calls --task unguarded

--hidden-result empty|marker 控制「移除工具执行结果」组如何隐藏观测。empty （标准）发送一条内容为空的 tool 消息——协议要求这条消息必须存在，所以这已是「结果消失 了」最接近的实现。marker 发送可见的占位符 [Tool result hidden due to context mode]，这等于补上了一个本该被消融掉的信号： 模型能看出「这里有观测，但被藏了」，于是可以停下来说明情况。对这一组反复运行 （Kimi K3、带约束任务、上限 5 轮）：

这一组在两种方式下都不是确定性的，样本量也小，因此上表只是倾向而非定律。倾向本身足够 清楚：静默隐藏下 7 次里有 6 次跑到迭代上限——反复重做换汇，然后用测试值试探工具 （1 EUR→USD、100 USD→EUR）以判断为什么什么都没回来——这正是正文所说的「盲目执行」； 可见占位符下 4 次里只有 1 次如此，而且只有在这种方式下，模型才报告过「我什么都没拿到」。 这正是关键：占位符本身是一个信号，拿走一个信号和拿走观测并不是同一个消融。两种方式也都 出现过用记忆中的汇率作答，所以那一种失败不属于任何一种设计。

python run_experiment_1_1.py --provider kimi --modes no_tool_results --hidden-result marker

系统性地移除上下文组件，以理解其重要性。

测试场景

需要以下能力的复杂财务分析任务：

1. PDF 文档解析
2. 多次货币换算
3. 数学计算
4. 结果汇总

预期行为

各消融如何落地（见 agent.py）：

• no_tool_calls — 请求中省略 tools 参数，模型没有可调用的工具定义。
• no_tool_results — 每个工具结果的内容被置空：API 要求这条消息存在，但它不再携带任何观测。--hidden-result marker 则换成可见的 [Tool result hidden due to context mode] 占位符——那是另一个实验，因为它等于告诉模型「这里有观测被藏起来了」。
• no_reasoning — 写回轨迹前，从每条 assistant 消息中剥离 reasoning_content。
• no_history — _prepare_messages_for_api() 仅向模型发送系统提示词和当前任务，不保留任何ReAct步骤。因此模型会遗忘此前所有操作步骤，易重复调用工具。完整模式始终发送完整轨迹。

运行测试

# Run the full ablation study (single case, all five modes)
python main.py --mode ablation

# Run across multiple cases for a stronger comparison
python main.py --mode ablation --cases 3

# This will generate:
# - ablation_study_results.png (visualization, if matplotlib is installed)
# - ablation_study_report.md (detailed report)
# - ablation_results.json (raw data; override path with --output)

控制台会打印两张表：逐次运行的 ablation study results，以及 comparison matrix（上下文模式 × 用例），便于一眼对比各组件的作用。

自动化回归测试

python -m pytest .

pytest . 同时收集 tests/ 目录与顶层回归测试（test_grounding.py、 test_experiment_1_1.py、test_main_result_semantics.py），这些测试钉住 实验的核心结论。需要真实 API Key 的手动提供商/API 冒烟脚本放在 tests/manual/。

可以从实验中得出什么

工具结果和历史消息可能帮助模型减少猜测和重复操作，但影响取决于任务与模型。 简单任务即使缺少某类信息也可能做对；某次运行更快，也不足以证明一种配置总是更高效。 尤其是“去掉推理内容会退化”并非本仓库每次实测都能复现。要讨论稳定差异，应在多个任务上重复运行， 并查阅 实验记录 中的实际证据。

准备环境与输入

下面会用到模型服务。先按配置说明选择一个提供商，准备对应的模型名称、服务地址和 API Key，再运行小规模例子。一次完整运行的费用取决于模型、输入长度和调用次数。

支持的 LLM 提供商

Doubao（字节跳动）— 默认

• 模型：doubao-seed-1-6-thinking-250715（可自定义）
• API：火山引擎上的 OpenAI 兼容接口
• 适合：深度推理、较快响应，中英文任务均可

SiliconFlow

• 模型：Qwen/Qwen3.5-397B-A17B（可自定义）
• API：OpenAI 兼容
• 适合：复杂推理与细致分析

阿里云百炼（Qwen 直连）

• 模型：qwen3.7-plus（可通过 --model 自定义）
• API：直连 DashScope 的 OpenAI 兼容接口，无需 SiliconFlow 账号
• 提供商名称：规范名称为 dashscope，也可使用别名 qwen 或 bailian
• 区域说明：API Key 与区域绑定。中国内地 Key 默认直连内地端点；国际站 Key 必须设置 DASHSCOPE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1

Kimi（月之暗面）

• 模型：kimi-k3（K3 推理模型；temperature 强制为 1，max_tokens 足够容纳思考输出）
• API：Moonshot 平台 OpenAI 兼容接口
• 适合：深度推理、多轮对话，中英文任务均可
• 特性：上下文缓存以优化成本

DeepSeek

• 模型：deepseek-v4-flash（默认；更强档可用 --model deepseek-v4-pro）
• API：DeepSeek Platform外部资源 ↗ 的 OpenAI 兼容接口
• 适合：性价比高的工具调用；开启 thinking，便于 no_reasoning 消融剥离 reasoning_content
• 说明：旧别名 deepseek-chat / deepseek-reasoner 已弃用（2026-07-24），请优先使用 V4 id

前置条件

• Python 3.10+
• 任一支持提供商的 API Key：
  • 阿里云百炼：百炼控制台外部资源 ↗
  • SiliconFlow：SiliconFlow外部资源 ↗
  • Doubao（字节）：火山引擎外部资源 ↗
  • Kimi（月之暗面）：Moonshot Platform外部资源 ↗
  • DeepSeek：DeepSeek Platform外部资源 ↗

按照步骤完成实验

先为所选提供商配置 API Key。下面以百炼为例，只运行一道计算题。读完终端中的工具调用，再把命令里的 full 改成 no_tool_results 重跑。保持任务和模型相同，才能把差异与上下文变化联系起来。

先做一个小规模观察

以下命令从本实验目录执行。先完成前面的环境准备，再观察这条路径的输入和输出。

python main.py --mode single --provider dashscope --context-mode full --task "请调用计算器计算 (125 + 375) * 8，并给出结果。" --output full.json

示例任务

系统预置 5 个样例任务：

1. 简单货币换算 — 基础多币种计算
2. 多币种预算分析 — 跨办公室费用分析
3. PDF 财务分析 — 解析并分析财务文档
4. 投资增长计算 — 复利与货币换算
5. 综合财务报告 — 串联全部工具的完整流程

用于展示 Agent 能力与上下文消融的影响。

快速开始

1. 安装

# 推荐在仓库根目录使用统一的第 1 章环境
uv sync --locked --extra ch1

# 切换目录前先激活环境：
# macOS/Linux：
source .venv/bin/activate
# Windows PowerShell：.\.venv\Scripts\Activate.ps1
# Windows cmd：.venv\Scripts\activate.bat

# 未安装 uv 时可用 pip 兜底：
# python -m pip install -e ".[ch1]"

# 进入本实验目录，后续命令都在这里运行
cd chapter1/context

# 迁移期间仍支持单项目兼容路径：
# python -m pip install -r requirements.txt

# 复制并配置环境变量
cp env.example .env
# 编辑 .env 并填入一个提供商的 API Key（例如 DASHSCOPE_API_KEY 或 ARK_API_KEY）

2. 配置提供商

# For Doubao (ByteDance) - Default
export ARK_API_KEY=your_key_here
python main.py  # Uses Doubao by default

# For SiliconFlow (Qwen)
export SILICONFLOW_API_KEY=your_key_here
python main.py --provider siliconflow

# 通过阿里云百炼直连 Qwen
export DASHSCOPE_API_KEY=your_key_here
python main.py --provider dashscope
# --provider qwen 与 --provider bailian 是等价别名。
# 如果使用国际站 Key，还需设置：
export DASHSCOPE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1

# For Kimi (Moonshot)
export MOONSHOT_API_KEY=your_key_here
python main.py --provider kimi

# For DeepSeek
export DEEPSEEK_API_KEY=your_key_here
python main.py --provider deepseek
# Optional stronger model:
python main.py --provider deepseek --model deepseek-v4-pro

# Or specify a custom model
python main.py --model doubao-seed-1-6-thinking-250715

# Universal OpenRouter fallback: if the provider key above is missing/invalid
# but OPENROUTER_API_KEY is set, requests are routed through OpenRouter and the
# model id is mapped automatically (bare gpt-*/o1-* -> openai/*, claude-* ->
# anthropic/*, deepseek-* -> deepseek/*, other native ids -> OPENROUTER_MODEL
# or openai/gpt-5.6-luna).
export OPENROUTER_API_KEY=your-openrouter-api-key
python main.py                       # falls back to OpenRouter when ARK_API_KEY is unset
python main.py --provider openrouter # or use OpenRouter directly

3. 测试 Qwen / Kimi / DeepSeek 集成

# 通过阿里云百炼 Qwen 直接运行消融实验
export DASHSCOPE_API_KEY=your_key_here
python main.py --provider dashscope --mode ablation

# Quick test of Kimi K3 model
export MOONSHOT_API_KEY=your_key_here
python tests/manual/check_kimi.py

# Use Kimi in main script
python main.py --provider kimi --mode interactive

# Run ablation study with Kimi
python main.py --provider kimi --mode ablation

# Quick test of DeepSeek V4
export DEEPSEEK_API_KEY=your_key_here
python tests/manual/check_deepseek.py
# or: python tests/manual/check_deepseek_quick.py

# Use DeepSeek in main script / ablation study
python main.py --provider deepseek --mode interactive
python main.py --provider deepseek --mode ablation

4. 交互模式（推荐）

# Default (Doubao)
python main.py --mode interactive

# With SiliconFlow provider
python main.py --mode interactive --provider siliconflow

# In interactive mode, you can:
# - Type 'samples' to see pre-defined tasks
# - Type 'sample 2' to test PDF parsing
# - Type 'providers' to list available providers
# - Type 'provider kimi' to switch providers
# - Type 'status' to see current configuration
# - Type 'help' for all commands

5. 运行样例任务

# Run without arguments to select from samples
python main.py --mode single

# With specific provider
python main.py --mode single --provider doubao

# Or provide your own task
python main.py --mode single \
  --task "Convert $1000 USD to EUR, GBP, and JPY. Calculate the average." \
  --context-mode full \
  --provider siliconflow

6. 运行消融实验

# With default provider (single case, all five context modes)
python main.py --mode ablation

# With Doubao provider
python main.py --mode ablation --provider doubao

# Multi-case comparison across modes (stronger evidence for the book's point)
python main.py --mode ablation --cases 3

# Compare only two modes and save raw results to a custom path
python main.py --mode ablation --ablation-modes full no_history --output my_ablation.json

main.py 是唯一 CLI 入口。运行 python main.py --help 查看完整（中文）参数说明。

关键参数：

分析结果与形成判断

算式的结果是 4000。先看模型有没有调用计算器，再看结果是否进入下一轮消息。即使两个答案都正确，也不能推断工具结果没有价值：简单算术可能被模型直接算对。如果没有发生工具调用，应换一个确实需要外部结果的任务。

结果解读

性能指标

• Terminal Response Rate：Agent 是否返回了终止响应
• Task Success：在存在任务专用评分标准时，任务是否正确完成
• Execution Time：完成任务总耗时
• Iterations：Agent 与模型交互次数
• Tool Calls：外部工具调用次数
• Reasoning Steps：战略规划迭代次数

怎样判断实验结果

先区分“程序给出了最终响应”和“任务做对了”。例如，模型可能没有查询汇率，便用记忆中的数字算出答案； 程序虽然结束了，但这些数字未必有依据。阅读结果时，结合任务要求检查数字来源和工具记录。

比较不同上下文模式时，保持任务、模型和运行条件一致。重点看：哪些工具被调用、结果是否被模型看到、 有没有重复操作、答案是否符合任务要求。运行时间和调用次数帮助解释成本，不能单独代表答案质量。

检查自己的解释

如果答案正确，但模型引用的是自己猜出的数据，你会把这次运行判为成功吗？还需要检查哪些证据？

阅读实现与继续探索

项目说明

Multi-provider context-aware agent with systematic ablation of context components (history, reasoning, tool calls, tool results). 配套《深入理解 AI Agent》第 1 章 实验 1-1 ★★：上下文的关键作用。

← Chapter 1 index / 返回第 1 章目录 · 📖 Read the chapter / 读本章正文（该材料暂未包含在当前内容中）（EN（该材料暂未包含在当前内容中））

进阶用法

交互模式命令

说明： 提示符会以括号显示当前提供商，如 [KIMI]> 或 [DOUBAO]>

对话历史

交互会话中 Agent 会维护对话历史：

• 持久上下文：会话内记住先前查询与回复
• 多轮对话：可引用更早提到的信息
• 工具调用记忆：先前工具执行结果可被引用
• 按需重置：使用 reset 清空历史重新开始

示例对话流程：

[DOUBAO]> Remember that our budget is $10,000. Calculate 15% of it.
# Agent calculates and remembers the budget

[DOUBAO]> Now convert that 15% amount to EUR
# Agent uses the previously calculated amount without re-asking

[DOUBAO]> What was our original budget?
# Agent recalls the $10,000 mentioned earlier

自定义任务

from agent import ContextAwareAgent, ContextMode

agent = ContextAwareAgent(api_key, ContextMode.FULL)
result = agent.execute_task("""
    Download the PDF from https://example.com/report.pdf,
    extract all monetary values, convert them to EUR,
    and calculate the total.
""")

生成测试 PDF

python create_sample_pdf.py
# Creates fixtures/pdfs/ with sample financial reports

配置

编辑 config.py 或设置环境变量：

export MODEL_TEMPERATURE=0.5
export MAX_ITERATIONS=15
export LOG_LEVEL=DEBUG

项目结构

context/
├── README.md             # 本文件
├── main.py               # 单一 CLI 入口（single / ablation / interactive）
├── agent.py              # Core agent implementation + context modes
├── config.py             # Configuration management
├── create_sample_pdf.py  # PDF generation utility
├── fixtures/
│   └── pdfs/             # 本地 demo/tests 使用的样例 PDF
├── tests/
│   ├── test_agent.py
│   ├── test_code_interpreter.py
│   ├── test_malformed_tool_json.py
│   └── manual/           # 需真实 Key 的提供商/API 冒烟脚本
├── requirements.txt      # Dependencies
└── env.example           # Environment template

说明：消融实验逻辑在 main.py 的 AblationTestSuite 中，通过 python main.py --mode ablation 运行，没有单独的 ablation_tests.py。

研究用途

• AI 安全研究：理解失败模式
• 系统设计：识别关键组件
• 优化：寻找最小可用配置
• 教学：讲解 Agent 架构原理

先跑一个对照

这个实验研究：给同一个模型、同一个任务，少提供一类上下文信息，执行过程会发生什么变化？ “消融”就是一次只移除一个组件，再与完整版本比较。先观察一个任务，之后再运行批量实验。

你需要 Python 3.10+，以及一个可用的模型 API Key。下面以百炼为例；其他提供商的配置见中文说明。 在仓库根目录安装依赖并激活环境，再进入实验目录：

uv sync --locked --extra ch1
source .venv/bin/activate
cd chapter1/context
export DASHSCOPE_API_KEY='your-api-key-here'

python main.py --mode single --provider dashscope --context-mode full \
  --task "请调用计算器计算 (125 + 375) * 8，并给出结果。" --output full.json
python main.py --mode single --provider dashscope --context-mode no_tool_results \
  --task "请调用计算器计算 (125 + 375) * 8，并给出结果。" --output no-tool-results.json

Windows 的环境激活方式和其他安装方法见下文“快速开始”。这两条命令会调用模型 API。

计算结果应为 4000。但答案相同不代表两次执行相同：先检查是否调用了计算器，再看工具结果是否 进入了下一轮上下文。即使没有看到工具结果，模型也可能自己算对这道简单题。 如果没有发生工具调用，这次任务就不能说明移除工具结果的影响；应换一个确实需要工具的任务再比较。 full.json 和 no-tool-results.json 保存了各次运行结果，可结合终端日志核对。

读代码时，先看 main.py 的参数分发，再看 agent.py 如何组装消息和处理工具结果。 提供商适配和绘图代码可以稍后阅读。

排查问题与查阅资料

局限

• 货币汇率为固定值（生产环境应使用实时 API）
• 复杂版式 PDF 解析可能失败
• 模型 token 上限可能影响超大文档

Notes / 说明

• Educational project for context ablation; for production, add proper error handling, rate limiting, and security. 本项目为教学向消融实验；生产使用请补齐错误处理、限流与安全措施。
• OpenRouter is a universal fallback when the direct provider key is missing. 未配置直连提供商 Key 时，可走 OPENROUTER_API_KEY 通用兜底。
• License: MIT. Contributions welcome (extra tools, scenarios, ablation strategies, performance). 许可证：MIT。欢迎贡献（更多工具、场景、消融策略、性能优化）。