你的第一个最小 Agent
你的第一个最小 Agent：用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体，通过架构、轨迹和故障重放完成验收。
学习目标
- 能解释“你的第一个最小 Agent”如何用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体
- 能区分工具注册表、输入 schema、分发器、执行结果、验收器，并指出控制权、数据与副作用边界
- 能固定输入与版本，沿以下证据定位首个分叉：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言
- 能注入“把模型返回的工具名直接映射到任意函数，并允许未经校验的参数触发副作用”，完成阻断、恢复、复位和同输入重放
来源、课程编排与适用边界
“你的第一个最小 Agent”以Anthropic 公开全文《Building effective agents》为总纲，并用Claude Platform《How tool use works》核对本单元机制；涉及 MCP 的控制权边界再由MCP 2025-06-18 官方规范交叉检查。
这不是 Anthropic 出版的“19 章教材”。平台把公开文章、官方工具文档与协议规范重组为 19 个应用单元；下列 152 个节点是站内课程地图，不冒充原文目录。正文、代码、图表、实验和练习均为独立教学重写；产品接口、模型行为或协议版本变化时必须重新验证。
本单元的八个课程坐标
- 你的第一个最小 Agent：这是“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”的第 1 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 先说说这一章干嘛：这是“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”的第 2 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 最小 Agent，就是这四块拼起来：这是“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”的第 3 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 动手看：最小 agent 跑一次长什么样：这是“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”的第 4 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 一段段把它拼出来：这是“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”的第 5 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 第一段：定义一个工具：这是“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”的第 6 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 第二段：给工具写一份 schema：这是“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”的第 7 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
- 第三段：解析 LLM 的工具调用，并执行：这是“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”的第 8 个课程坐标；必须进入机制解释、实验观察或练习证据，不能只停在目录。
术语与运行合同
↡工具注册表：从公开工具名到受控执行函数的显式映射；在“你的第一个最小 Agent”中按以下证据核对：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。、↡输入 schema：限定参数字段、类型、枚举和必填项的合同；在“你的第一个最小 Agent”中按以下证据核对：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。、↡分发器：校验调用后选择并执行白名单工具的运行时代码；在“你的第一个最小 Agent”中按以下证据核对：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。、↡执行结果：包含成功值或结构化错误的工具回执；在“你的第一个最小 Agent”中按以下证据核对：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。、↡验收器：根据环境事实判断任务是否真正完成的确定性逻辑；在“你的第一个最小 Agent”中按以下证据核对：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。。
本页不变量是：最小实现也必须分离模型决策、工具执行、权限检查和成功判定。任何“成功”结论都要保存以下证据：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言，模型生成的计划或自信不能替代环境事实。
关键机制与可推翻实验
先选无副作用切片
首个 Agent 应使用天气、计算或查询等只读工具，先证明协议闭环。
动手验证：把工具替换为返回固定值的测试替身，验证消息序列。
schema 不是授权
字段合法只说明形状正确，资源范围与操作者权限仍要单独判断。
动手验证：提交格式正确但越权的资源标识，确认执行器拒绝。
注册表阻断任意调用
模型产生的名称永远不能直接进入 eval、反射或 shell。
动手验证：注入未注册工具名，断言零副作用并返回 structured error。
验收独立于模型措辞
模型说“已经完成”不能替代数据库、文件或测试断言。
动手验证：让模型错误声称完成，确认验收器仍返回 blocked。
先预测，再操作三类证据
1. 架构与复杂度边界
在“你的第一个最小 Agent”中切换简单基线、受控工作流与自主循环，先预测“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”在哪个阶段需要增加控制权，再比较延迟、成本、可观测性和自主性。
Architecture decision laboratory
你的第一个最小 Agent
用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体
不变量：最小实现也必须分离模型决策、工具执行、权限检查和成功判定
最小可运行实现
const registry = { get_weather: getWeather } satisfies ToolRegistry;
async function dispatch(call: ToolCall, actor: Actor) {
const tool = registry[call.name as keyof typeof registry];
if (!tool) return { ok: false, error: "unknown_tool" };
const args = tool.schema.parse(call.input);
await authorize(actor, call.name, args);
return { ok: true, value: await tool.run(args) };
}这段切片只暴露“用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体”的最小运行合同。交付版本还要补齐超时、密钥隔离、结构化日志、幂等和批量评测；缺少工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言时，代码能运行也不代表本章结论成立。
练习与答案
练习
问题 1：最小证明。 怎样用最少样本证明“最小实现也必须分离模型决策、工具执行、权限检查和成功判定”？
问题 2：课程覆盖。 你的第一个最小 Agent、先说说这一章干嘛、最小 Agent，就是这四块拼起来、动手看：最小 agent 跑一次长什么样、一段段把它拼出来、第一段：定义一个工具、第二段：给工具写一份 schema、第三段：解析 LLM 的工具调用，并执行如何进入可操作验证？
问题 3：恢复闭环。 怎样证明“把模型返回的工具名直接映射到任意函数，并允许未经校验的参数触发副作用”已经修复？
本章回顾
- “你的第一个最小 Agent”的主问题是用一个只读工具、一个显式状态机和一个确定性验收器组装最小可运行智能体。
- 核心不变量是最小实现也必须分离模型决策、工具执行、权限检查和成功判定。
- 首要反例是把模型返回的工具名直接映射到任意函数，并允许未经校验的参数触发副作用。
- 最小证据包包含工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。
名词解释
本章出现的专业名词，用大白话再讲一遍。
- 工具注册表
从公开工具名到受控执行函数的显式映射。在“你的第一个最小 Agent”中必须能按以下证据重新定位：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。
- 输入 schema
限定参数字段、类型、枚举和必填项的合同。在“你的第一个最小 Agent”中必须能按以下证据重新定位：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。
- 分发器
校验调用后选择并执行白名单工具的运行时代码。在“你的第一个最小 Agent”中必须能按以下证据重新定位：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。
- 执行结果
包含成功值或结构化错误的工具回执。在“你的第一个最小 Agent”中必须能按以下证据重新定位：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。
- 验收器
根据环境事实判断任务是否真正完成的确定性逻辑。在“你的第一个最小 Agent”中必须能按以下证据重新定位：工具白名单、输入校验、执行日志、结果消息、退出状态与验收断言。