00如何使用这本手册
你不需要先选定一个框架。只需要一个能调用模型的 API key、一台能运行 Python 的电脑,以及一个愿意被拆解的真实任务。
用一个模型、一个工具和一条停止条件,完成最小可用的闭环。
补齐契约、错误处理与上下文策略,让失败可以被解释。
用固定数据集与轨迹指标,把「感觉不错」换成可比较的数字。
手册按 认知 → 工具 → 记忆 → 编排 → 评估 → 上线 六个阶段组织。每一节都可以独立阅读,但建议至少完整走一遍第一章:后面的所有设计,都建立在同一个循环之上。
如果一段代码不能在一次对话里被讲清楚,它大概率也不该成为你系统的第一版。
00.1123
1
01什么是 Agent
一个常见的误解,是把「会调用 API 的聊天机器人」直接叫做 Agent。真正的区别不在于回复有多长,而在于系统是否拥有在运行时做决定的能力:调用哪个工具、传什么参数、看到结果后是否继续,以及什么时候停下来。
模型负责判断,工具负责把判断变成外部世界的动作,状态让下一步知道上一步发生了什么,而循环提供了「观察—再决策」的机会。少任何一项,系统都会退化成一次性的文本生成。
| 维度 | 聊天机器人 | Agent |
|---|---|---|
| 交互 | 一问一答 | 围绕目标多步推进 |
| 决策 | 由用户指定下一步 | 由模型在运行时选择动作 |
| 失败 | 答错,重新提问 | 需要重试、回滚或升级处理 |
| 观测 | 看单条回复 | 看整条决策轨迹与工具结果 |
如果任务既不需要外部信息,也不需要执行动作,更不需要跨步骤保留状态,那就不要做 Agent。一次结构化的模型调用,通常更便宜、更快,也更容易测试。
02最小闭环
先把工程复杂度放在一边。一个最小 Agent 只需要三样东西:一组消息、一组工具定义,以及一个「模型返回工具调用就执行、否则结束」的循环。下面这段伪代码不是某个 SDK 的用法,而是所有 Agent 框架最终都会收敛到的形状。
# 消息、工具与预算,构成最小可运行状态
messages = [{"role": "user", "content": task}]
steps = 0
while not finished and steps < MAX_STEPS:
reply = model.chat(messages, tools=TOOLS)
messages.append(reply) # 先保存 assistant 的 tool_calls
if not reply.tool_calls:
finished = True
break
for call in reply.tool_calls:
try:
result = run_tool(call.name, call.args)
except ToolError as exc:
result = f"tool failed: {exc}"
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": result,
})
steps += 1
把用户意图与可用工具放进上下文。
生成回答,或给出结构化的工具调用。
校验参数、执行副作用、捕获错误。
把结果写回上下文,直到触发停止条件。
四个必须写下来的约束
- 步数预算
例如 MAX_STEPS = 6。超过预算就停止并返回当前最佳结果,而不是继续消耗 token。
- 停止条件
模型给出最终回答、达到预算、命中人工审批,或连续两次没有产生新信息。
- 工具超时
每次调用设置独立的 timeout,避免一个卡死的下游拖垮整条轨迹。
- 完整轨迹
记录每一步的输入、工具名、参数、结果与耗时。没有轨迹,后面的评估与调试都无从谈起。
轮数只是保险丝。真正的停止条件应该描述业务上的完成状态,例如「已拿到订单状态并给出处理建议」。否则系统只会在预算耗尽时随机停下。
03工具即契约
模型不会读你的源码。它只看到工具的名字、描述和参数 schema。因此,工具定义不是给编译器看的,而是写给一个聪明但没有上下文的同事的操作手册。
{
"name": "search_docs",
"description": "在官方文档中检索。仅在需要外部事实时调用;不要用它查询用户私有数据。",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "2-8 个关键词,保留产品名与版本号"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 8
}
},
"required": ["query"],
"additionalProperties": false
}
}
| 契约部分 | 要写清楚什么 | 常见错误 |
|---|---|---|
| name | 动词 + 对象,全局唯一 | search、do_it 这类模糊命名 |
| description | 何时用、何时不要用、返回什么 | 只写「搜索文档」 |
| schema | 类型、枚举、范围、必填项 | 全部 optional,参数无约束 |
| 结果 | 稳定结构,明确错误字段 | 成功返回 JSON、失败抛裸异常 |
| 副作用 | 是否写数据、是否可重试 | 把写操作包装成可自动重试 |
- 窄而专:一个工具只做一件事,参数不超过 5 个;需要组合时让模型分两步调用。
- 可验证:所有参数在执行前做 schema 校验,拒绝未知字段,而不是「尽力猜测」。
- 有边界:为读操作设置超时与条数上限,为写操作设置权限检查与人工确认。
- 可解释:错误信息要告诉模型下一步能做什么,例如「订单号不存在,请先调用 get_order」。
工具失败,是设计的一部分
在真实系统里,超时、限流和下游 500 是常态。与其追求「不失败」,不如设计一条可预测的恢复路径:区分可重试与不可重试错误,限制重试次数,并让模型看到结构化的失败原因。
def call_with_retry(tool, args, attempts=3):
for i in range(attempts):
try:
return tool.run(args, timeout=8)
except RetryableError:
time.sleep(2 ** i) # 1s, 2s, 4s
raise ToolUnavailable(tool.name)
退款、发邮件、创建工单都可能被执行两次。要么为工具提供幂等键,要么在重试前先查询状态。自动重试只应覆盖明确可重试的读操作与幂等写操作。
04上下文工程
Agent 的「记忆」首先是一个预算问题。上下文窗口不是硬盘,放进去的每一个 token 都在增加成本、延迟与干扰。好的记忆策略不是记住一切,而是让当前这一步需要的信息出现在正确的位置。
| 层级 | 放什么 | 生命周期 | 实现方式 |
|---|---|---|---|
| 工作记忆 | 当前目标、最近几步、工具结果 | 单次任务 | 消息数组 + 截断策略 |
| 会话状态 | 已确认事实、决策、待办 | 多轮对话 | 结构化 checkpoint |
| 长期知识 | 文档、历史案例、用户偏好 | 跨会话 | 检索 + 重排 |
在上下文逼近上限之前,主动写一个 checkpoint,比事后粗暴截断更可靠。它应该像交接班记录:下一位同事只需要读这一页,就能继续工作。
{
"goal": "确认年费会员是否符合退款条件",
"facts": [
"订单 #A1024,购买于 2026-03-02",
"权益尚未使用"
],
"decisions": [
"依据 7 天无理由条款,进入人工审核"
],
"open_questions": ["支付渠道是否影响退回路径?"],
"next_action": "get_payment_channel"
}
- 先测量,再优化
记录每步的输入 token 数。大多数「上下文太长」的问题,其实来自重复的工具结果和冗长的系统提示。
- 让检索结果可丢弃
给每条检索内容标注来源与时间;过期或低相关的内容应被移出上下文,而不是一直累积。
- 压缩保留决策
摘要不是把对话写短,而是保留事实、决定、未解决问题与下一步。删掉寒暄,别删掉理由。
先保证召回,再做重排与去重。把 20 段低相关内容塞进上下文,通常不如 4 段高相关内容加一句来源说明。相关性比数量更能决定答案质量。
05工作流与多 Agent
Agent 不是编排的默认答案。当步骤稳定、输入输出明确时,一条确定性工作流往往更便宜、更可控,也更容易做回归测试。先把问题画成流程图,再决定哪一段真的需要模型自由决策。
规则或小模型判断请求类型,缩小处理范围。
按既定数据源检索,避免模型凭空补全。
在受限上下文内完成回答或动作草稿。
规则检查、引用核对,必要时进入人工审核。
| 场景 | 推荐结构 | 原因 |
|---|---|---|
| 步骤固定、合规要求高 | 确定性工作流 | 可审计、可回放、成本稳定 |
| 路径依赖中间结果 | 单 Agent + 工具 | 保留决策灵活性,状态集中 |
| 子任务可并行且上下文隔离 | 多 Agent / 子图 | 减少相互污染,缩短关键路径 |
| 需要多角色对抗审查 | 生成者 + 评审者 | 用不同提示词制造独立视角 |
什么时候才值得拆成多 Agent
- 任务可以真正并行:子任务之间没有顺序依赖,合并结果的成本低于串行执行。
- 上下文必须隔离:不同子任务的数据不应互相可见,或放在一起会显著降低判断质量。
- 角色需要独立:生成与审查使用不同目标、不同工具权限,避免「自己批自己」。
- 你有能力观测:能按子 Agent 维度记录耗时、token、失败率与交接内容,否则调试会失控。
每增加一个 Agent,就多一份上下文交接、权限边界与失败路径。没有明确的并行收益或隔离需求时,单 Agent 加清晰的工具,通常是更好的第一版。
06评估体系
提示词改动最危险的地方,是它看起来总是「更好了」。评估的作用,是把这种叙事拉回到可比较的事实:同一批输入,同样的判定标准,改动前后到底差在哪里。
| 指标 | 定义 | 为什么重要 |
|---|---|---|
| 任务成功率 | 满足全部验收条件的样本占比 | 最终效果,但需要足够细的判定 |
| 工具正确率 | 调用工具、参数与顺序均正确的比例 | 定位问题在决策还是执行 |
| 平均步数 | 完成任务的模型轮次均值 | 反映效率与循环质量 |
| P95 延迟 | 95% 请求的端到端耗时上限 | 用户体验由尾部决定 |
| 单任务成本 | token + 工具调用 + 基础设施成本 | 决定方案能否规模化 |
{
"id": "refund-policy-014",
"input": "我昨天买的年费会员能退吗?",
"must_call": ["get_order", "get_refund_policy"],
"must_include": ["7 天内", "未使用"],
"must_not_include": ["随时可退"],
"max_steps": 5
}
- 从真实请求开始
先收集 30–50 条线上或灰度请求,覆盖常见路径、边界条件和已知失败。不要用模型自己生成的题目当唯一测试集。
- 把「通过」写具体
必须调用哪些工具、必须包含哪些事实、绝不能出现什么。可自动判定的条件优先,主观质量再交给人工或评审模型。
- 建立基线再改
记录当前版本的通过率、步数、延迟与成本。没有基线,任何对比都只是感觉。
- 把评估放进 CI
每次提示词、模型或工具变更都跑同一套用例。通过率下降超过阈值就阻止发布,而不是上线后再回滚。
固定数据集能防止回归,但无法覆盖真实世界的分布漂移。上线后保留小比例人工抽检与失败样本回收,定期把它们补进评估集。
07可观测性
当 Agent 答错时,你需要的不是「再试一次」,而是能回答三个问题:它看到了什么、它决定了什么、它为什么停下。可观测性不是日志的副产品,而是 Agent 系统的一等功能。
{
"trace_id": "tr_8f2a",
"step": 3,
"action": "tool.search_docs",
"input_digest": "sha256:9c1e…",
"latency_ms": 412,
"tokens": { "in": 1840, "out": 96 },
"status": "ok",
"stop_reason": "answer_ready"
}
至少记录这四类信号
- 决策轨迹:每一步的模型输出、工具名、参数摘要与观察结果,能按 trace_id 串起来。
- 性能与成本:每步延迟、token 用量、工具耗时,以及按任务聚合的 P50 / P95。
- 失败分类:区分模型判断错误、工具错误、参数校验失败、超时与人工中断,而不是统一的 error。
- 版本信息:模型名、提示词版本、工具版本、代码版本。没有版本号,回放无法复现。
用户输入、工具结果与模型输出都可能包含个人信息。对日志做字段级脱敏与访问控制,设置保留期限;不要把完整 prompt 与密钥一起写进普通日志。
08安全边界
上线前的最后一个问题不是「它能不能做」,而是「它做错时,最坏会发生什么」。Agent 拥有工具权限,也就拥有了把错误放大的能力。安全边界必须写在系统里,而不是写在提示词里。
| 风险 | 典型表现 | 控制手段 |
|---|---|---|
| 提示词注入 | 网页或文档中的指令改变 Agent 行为 | 隔离不可信内容,工具结果只作为数据 |
| 工具滥用 | 越权读取、批量删除、重复扣款 | 最小权限、参数白名单、写操作审批 |
| 数据外泄 | 把私有上下文发往外部地址 | 出站域名白名单、敏感字段过滤 |
| 失控循环 | 反复调用昂贵工具,成本飙升 | 步数 / 金额 / 时长三重预算与熔断 |
- 最小权限
每个工具只拿完成当前任务所需的最小权限;读与写分离,生产与测试隔离。
- 不可信内容隔离
把检索到的网页、邮件、文件标记为数据,不让其中的「指令」进入系统提示的权限层级。
- 高风险动作人工确认
退款、删除、对外发送等操作必须经过显式审批,并记录批准人与原始参数。
- 预算与熔断
为单任务设置步数、金额与时长上限。触发上限时安全停止,返回可解释的状态,而不是继续重试。
「请不要删除数据」无法阻止一个拥有删除权限的模型。真正的边界由代码、权限与审批流构成;提示词只能帮助模型做出更好的判断。
1699999
11789
10延伸阅读
以下资料分别覆盖工具调用、编排、可观测性与安全。建议带着具体问题去读,而不是从头到尾收藏。
99术语表
下面这些词会反复出现在设计评审与故障复盘里。先把定义对齐,再讨论方案。
Agent Loop
模型决策、执行工具、观察结果并再次决策的循环。循环必须有明确的停止条件与预算。
Tool Contract
工具对模型暴露的完整接口:名称、用途、参数 schema、返回结构、错误语义与副作用说明。
Context Window
模型单次调用能看到的 token 上限。它同时是容量约束、成本约束与注意力约束。
Checkpoint
在上下文压缩或任务交接时写下的结构化状态,包含目标、事实、决策、未解决问题与下一步。
Trace
一次任务从开始到结束的完整决策轨迹,按步骤记录模型输出、工具调用、观察结果与耗时。
Eval Set
用于回归评估的固定输入集合,附带可判定的通过条件、期望工具调用与性能预算。
Grounding
让回答建立在可核查的外部事实上,通常通过检索、引用与一致性校验实现。
Guardrail
独立于模型的输入输出检查与权限控制,用于拦截越权、敏感数据与高风险动作。
Human-in-the-loop
在高风险或低置信度节点引入人工确认,让自动化在边界处停下来。
这一章对你有帮助吗?你的反馈会帮助我们改进下一版。
收到,谢谢你的反馈。继续往下读,或者回到课程地图按模块学习。