Agent 开发速查表（临床数据场景）

面向要写 Agent、又要让它能上线的人。不是"如何调用 LLM"的教程 —— 只收录那些踩过就知道疼的判断规则、检查清单和反模式。

验证环境：Python 3.13 / 纯标准库可跑（第 18–24 章全部案例离线运行）。 配套代码：clinic/agent_*.py、clinic/config.py、cases/case07–case12、cases/case_http_demo.py。

目录

• 0. 一句话原则
• 1. 分层架构与职责边界
• 2. 工具契约
• 3. 错误分类与重试决策表
• 4. 预算三闸与优雅收尾
• 5. 状态、断点恢复与幂等
• 6. 任务规划与调度
• 7. 记忆与检索
• 8. 多 Agent：拓扑选型与独立性
• 9. 外部服务集成
• 10. 部署与可观测性
• 11. 评估集
• 12. 反模式 Top 15
• 13. 上线检查清单

0. 一句话原则

脚本错了会报错；Agent 错了会安静地给你一个像模像样的答案。

所以 Agent 工程的目标不是"更聪明"，而是：

1. 边界写在代码里（不是提示词里）
2. 每个数字都能追到出处（工具返回值，不是模型的记忆）
3. 没查到就说没查到（绝不猜一个顶上）
4. 可复现、可审计、可回滚

1. 分层架构与职责边界

判断标准一句话："把 LLM 整个删掉，领域层还能不能跑单元测试？" 不能，就是分层错了。

2. 工具契约

@reg.tool("describe_dataset",
          "查看数据集结构：变量名、类型、缺失率。对应 SAS 的 PROC CONTENTS。",
          {"type": "object",
           "properties": {
               "dataset": {"type": "string", "enum": sorted(ALLOWED),
                           "description": "数据集名称，如 adsl / adae"}},
           "required": ["dataset"],
           "additionalProperties": False})     # ★ 必须显式关掉"多传字段"

契约自检清单（可写进 CI，ToolRegistry.validate() 已实现前两条）

• [ ] 描述 ≥ 10 字，说清"什么时候该用它"
• [ ] type 是 object
• [ ] additionalProperties: false —— 不写它，模型传的错字段会被静默忽略
• [ ] 每个参数都有 description
• [ ] 取值封闭的用 enum，别让模型自由发挥
• [ ] 参数名统一（本项目约定数据集一律叫 dataset）
• [ ] side_effect 标对：read / write / irreversible

路径白名单用映射，不要用拼接

path = DATA_DIR / f"{name}.csv"        # ❌ 传 ../../etc/passwd 就出去了
path = DATASETS[name]                   # ✅ 名字→路径的映射，名字不在表里直接拒

两层防御才够：接口层校验挡"无意写错"，工具层挡"绕过接口直接调用"。 少任何一层，都有一类调用会漏过去。

结构化错误：让模型自己改对

ToolResult.fail("数据集 'adls' 不在允许列表中", "permission",
                hint="可用数据集见 list_datasets",
                options=sorted(ALLOWED))

错误信息里带上可选值，模型下一步就能自己修正 —— 这比任何提示词都管用。

3. 错误分类与重试决策表

必须能自动断言 —— sleep 与随机数都要可注入，否则重试逻辑等于没写：

client = HttpClient(..., sleep=waits.append, rand=lambda: 0.5)
assert waits == [1.15, 1.725]        # 比例 = backoff_base

4. 预算三闸与优雅收尾

超限的正确动作是"优雅收尾"，不是抛异常：

if (why := state.budget.exceeded()):
    state.status = "done"
    state.answer = self._budgeted_answer(state, why)   # 给已确认的部分结论 + 说明为什么停
    break

抛异常 = 前面烧掉的钱和已确认的事实全部作废； 优雅收尾 = 至少交付"我查到了什么、为什么没查完"。

5. 状态、断点恢复与幂等

AgentState 要纯数据 + 可 JSON 序列化，断点恢复才能做：

state.save(path)                  # 跑到一半（比如在等人确认）
state = AgentState.load(path)     # 第二天接着跑
agent.run(goal, state=state)      # ★ 保留已用步数/token，不重复已完成步骤

恢复的前提是"跳过已完成的" —— 否则重放等于全量重跑，副作用会重复发生。

副作用等级驱动设计

6. 任务规划与调度

状态机（clinic/agent_planner.py）

waiting ──依赖就绪──► running ──► done
                        │
                        ├─► failed ──(rerun_failed)──► running
                        └─► waiting   ← 人工确认点（不是 skipped！）

• settled = done / failed；waiting 不是终态，否则续跑时会被当成"已完成"跳过
• 依赖失败 → 下游 skipped；optional 依赖失败不阻塞下游（语义别写反）
• 循环依赖 / 缺失依赖 / id 重复 → 在计划校验阶段就拦，别等执行到一半
• 部分失败要显式汇报："11 个任务成功 9 个，2 个失败" —— 不要静默交付不完整的表

并行前先确认：任务之间没有数据依赖；同一份文件不要被两个任务同时写。

7. 记忆与检索

红线（不可违反）

• 检索零命中就说零命中，绝不用"常识"补一个答案
• 结论里的每个数字都要带 source（哪个工具、哪一步）
• 阈值必须用带标注的探针集标定，不能拍脑袋

# 标定的样子：8 个应命中 + 7 个应落空，扫一遍阈值
for thr in (0.25, 0.30, ..., 0.65):
    recall, fp = probe(thr)
# 选 0.40：召回 8/8、误命中 0/7。
# 但要如实记下薄弱边缘（0.43 那条只差 0.03）→ 需要更大的回归集

"我觉得 0.3 差不多"这句话，在半年后没人能复核。

8. 多 Agent：拓扑选型与独立性

先问要不要用（三条同时成立才用，缺一条就用单 Agent + 单元测试）

1. 存在可验证的多种正确路径（衍生口径、检验方法）
2. 单次错误的代价很高（递交物、关键 TFL）
3. 能机械比对结果（数字、表格、数据集）

独立性守卫 —— 本章最重要的一段

guard.record_read("impl_b", "outputs/pair/agegr1_impl_a.json")   # ★ 违规

守卫必须同时记录"谁读了什么"和"谁产出了什么"： 只记读取是查不出违规的 —— 抄的人读的是对方产出的文件， 而那个文件对方从来没"读过"。

差异四级（按影响面定级，不是按"看着严不严重"）

"零差异"只有在独立性成立时才是个好结果。 独立性不成立时，零差异只说明"同一份错误被复制了一遍"。 审计覆盖率 0 的"通过"同样等于没查。

9. 外部服务集成

发数据给模型之前

• [ ] 直接标识符剔除（列名 + 取值形态双层判据 —— VAR1 里可能装着人名）
• [ ] 只发必需字段（合规 + 成本，一举两得）
• [ ] 每次调用落审计（存 sha256 摘要，不存全文；但注意 preview 也可能含标识符）
• [ ] 结论可人工复核 —— 最终对递交物负责的仍然是人

10. 部署与可观测性

启动 fail fast（错配置起不来，比带病运行好）

日志必须有的字段

{"ts": "...", "rid": "a3f2b1c9d8e7", "step_index": 3,
 "tool_name": "run_qc_checks", "tool_args": {...}, "tokens": 2025}

没有 request_id 的可观测性等于没有可观测性 —— 并发日志是交错的，光有时间戳拼不出一次请求的全貌。

最该盯的指标

一个永远 0% 的错误率，通常说明没人在打边界，而不是系统没问题。

缓存

key = f"{data_version}|{tool}|{canon(args)}"   # ★ data_version 必须参与

• 只读工具才能缓存（给写工具加缓存 = 调用方以为写了，其实什么也没发生）
• 更稳的做法是换版本号而不是手工 invalidate() —— 前者没法忘
• 命中/未命中是累计计数，条目数是当前占用，别混在一起看

长任务异步化：内存字典存任务状态上线必崩（多进程查不到、重启全丢）→ Redis / 数据库。

11. 评估集

没有评估集，改完只能是"感觉好像好一点"。

EvalCase(name="基础体检", goal="检查 adsl 数据集有什么数据质量问题",
         expect_tools=("describe_dataset", "run_qc_checks"),
         expect_facts={"adsl.n_rows": 254},      # ★ 精确值：验证数字来自真实数据
         max_steps=10)

EvalCase(name="不存在的数据集不得编造数字", goal="检查 adls 数据集的缺失情况",
         forbid_bare_numbers=True)               # ★ 结论里一个数字都不许有

否定式断言比正向断言值钱

不用 LLM 当裁判：位置偏见、长度偏见、不可复现、无法审计。 （但评估报告文字质量时它确实有用 —— 只能用主观判断的地方才用，且人工抽检 10%。）

Mock 模式下的评估是确定性 + 零成本的 → 所以可以每次提交都跑。

评估集也会过拟合。判断标准：每条断言都对应一个真实发生过的错误。 对不上的断言，删掉比留着好。

12. 反模式 Top 15

13. 上线检查清单

功能 - [ ] 生产配置自检通过（validate_for_prod()） - [ ] 评估集全部通过 - [ ] 越权用例（路径穿越、白名单外数据集）确认被拦截 - [ ] 断点恢复在真实故障后验证过

安全 - [ ] 密钥来自环境变量，不在镜像里 - [ ] 日志脱敏生效（人工抽查 10 行日志） - [ ] 外发数据无直接标识符 - [ ] 非 root 用户运行

可观测 - [ ] request_id 贯穿日志 - [ ] 每次 LLM 调用与工具调用都落审计 - [ ] 关键指标可查询（成功率、步数、token、工具错误率） - [ ] 成本分账到人 / 项目

运维 - [ ] 健康检查可用（并且暴露配置状态，不只是"活着"） - [ ] 有回滚方案（镜像 tag + 版本号） - [ ] 预算告警已配置 - [ ] 依赖版本已锁定

合规 - [ ] 审计日志保留期限符合要求 - [ ] 人工复核环节明确（谁负责最终签字） - [ ] 数据处理协议（DPA）已覆盖外部服务

相关文档

• 第 18 章 · Agent 架构设计 —— 分层与预算闸门
• 第 19 章 · 任务规划与调度 —— DAG、并行与部分失败
• 第 20 章 · 工具调用进阶 —— 契约、校验与边界
• 第 21 章 · 记忆与上下文管理 —— 检索、引用与红线
• 第 22 章 · 多 Agent 协作 —— 独立性与差异分级
• 第 23 章 · 与外部 API 及服务集成 —— 超时、重试、水位线
• 第 24 章 · 部署与监控 —— 接口、指标、缓存、评估集
• cases/ —— 13 个可运行案例，每条规则都有可复现的代码