From f1dfa389b1f687fc80e37d22921c3714acf639ae Mon Sep 17 00:00:00 2001 From: jiekewu Date: Sun, 28 Jun 2026 15:40:07 +0300 Subject: [PATCH] Add agent development methodology docs --- AGENTS.md | 2 +- README.en.md | 4 +- README.md | 4 +- thinking/AGENTS.md | 2 + thinking/agent-development-repo-structure.md | 1782 +++++++++++++++++ ...roduction-agent-development-methodology.md | 921 +++++++++ 6 files changed, 2710 insertions(+), 5 deletions(-) create mode 100644 thinking/agent-development-repo-structure.md create mode 100644 thinking/production-agent-development-methodology.md diff --git a/AGENTS.md b/AGENTS.md index df7e6dc..3221d0c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ ## 学习路线（进度） - [x] Phase 1：理解核心概念（concepts/，8 篇） -- [x] Phase 2：形成自己的观点（thinking/，9 篇，持续中） +- [x] Phase 2：形成自己的观点（thinking/，11 篇，持续中） - [x] Phase 3：选一个小项目实践（practice/，1 个 Ralph Demo） - [x] Phase 4：记录反馈迭代（feedback/，1 篇，持续中） - [x] Phase 5：输出可展示的作品（works/，22 篇翻译 + 1 篇原创 + 2 篇外部中文收录） diff --git a/README.en.md b/README.en.md index e355ba8..dc4cdf6 100644 --- a/README.en.md +++ b/README.en.md @@ -109,7 +109,7 @@ harness-engineering/ │ ├── 06-harness-... # Harness definition (Fowler control-theory extension) │ └── 07-spec-as-product.md # Spec as product (Symphony extension) │ -├── thinking/ # Phase 2: Independent analysis (9 articles) +├── thinking/ # Phase 2: Independent analysis (11 articles) ├── practice/ # Phase 3: Hands-on experiments (1 Ralph Demo) ├── feedback/ # Phase 4: Lessons learned (1 article) ├── works/ # Phase 5: Shareable outputs (22 translations + 1 original + 2 external Chinese captures) @@ -123,7 +123,7 @@ Each subdirectory has its own `AGENTS.md` explaining its purpose and conventions ## 🚀 Learning Path - [x] **Phase 1: Understand core concepts** — 8 concept notes covering OpenAI's six concepts + Fowler's control-theory extension + Symphony's spec-as-product -- [x] **Phase 2: Form your own opinions** — 9 independent analyses (ongoing) +- [x] **Phase 2: Form your own opinions** — 11 independent analyses (ongoing) - [x] **Phase 3: Pick a small project to practice** — Ralph Demo completed (321s, $0.31) - [x] **Phase 4: Record feedback & iterations** — 1 article (ongoing) - [x] **Phase 5: Produce shareable work** — 22 professional translations + 1 original synthesis + 2 external Chinese captures diff --git a/README.md b/README.md index eac4886..30d4294 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,7 @@ harness-engineering/ │ ├── 06-harness-... # Harness 精确定义（Fowler 控制论扩展） │ └── 07-spec-as-product.md # 约束即产品（Symphony 延伸） │ -├── thinking/ # Phase 2：独立思考与质疑（9 篇） +├── thinking/ # Phase 2：独立思考与质疑（11 篇） ├── practice/ # Phase 3：小项目实验（1 个 Ralph Demo） ├── feedback/ # Phase 4：踩坑与迭代心得（1 篇） ├── works/ # Phase 5：可展示的作品（22 篇翻译 + 1 篇原创 + 2 篇外部中文收录） @@ -122,7 +122,7 @@ harness-engineering/ ## 🚀 学习路线 - [x] **Phase 1：理解核心概念** — 8 篇概念笔记，覆盖 OpenAI 六大概念 + Fowler 控制论扩展 + Symphony 约束即产品 -- [x] **Phase 2：形成自己的观点** — 9 篇独立思考（持续中） +- [x] **Phase 2：形成自己的观点** — 11 篇独立思考（持续中） - [x] **Phase 3：选一个小项目实践** — Ralph Demo 完成（321 秒，$0.31） - [x] **Phase 4：记录反馈迭代** — 1 篇（持续中） - [x] **Phase 5：输出可展示的作品** — 22 篇专业翻译 + 1 篇原创综合分析 + 2 篇外部中文收录 diff --git a/thinking/AGENTS.md b/thinking/AGENTS.md index 7c78f0d..4808d9e 100644 --- a/thinking/AGENTS.md +++ b/thinking/AGENTS.md @@ -22,6 +22,8 @@ | [software-project-complexity-in-the-ai-era.md](software-project-complexity-in-the-ai-era.md) | AI 时代的软件项目复杂度 | 6 维（上下文压力 / 可提示性 / 探索收敛 / 状态纠缠 / 暗知识 / 验证成本）+ 胶囊化分母 + 重构/复刻终局指标 | | [subagent-is-child-runtime.md](subagent-is-child-runtime.md) | Subagent 是 child runtime | 与 Claude Code 架构逆向互证：subagent = tool-call-triggered child session + context projection + evidence-return contract | | [why-this-project-exists.md](why-this-project-exists.md) | 为什么有这个项目 | 项目宗旨：把 Harness Engineering 从"概念集合"变成"可复刻的产品构建方法论"——借用《诡秘之主》"学徒途径"隐喻 | +| [agent-development-repo-structure.md](agent-development-repo-structure.md) | Agent 开发项目仓库结构 | Agent repo 应组织为 lab system、deliverables、project memory，并用 capability evidence chain 和 drift control 支撑可控开发 | +| [production-agent-development-methodology.md](production-agent-development-methodology.md) | 生产级 Agent 开发方法论 | 2025-2026 官方资料显示，Agent 开发正在从 prompt+tools 转向 controlled runtime、context engineering、trace-native eval loop 和 production control plane | ## 写作方向参考 diff --git a/thinking/agent-development-repo-structure.md b/thinking/agent-development-repo-structure.md new file mode 100644 index 0000000..22f4776 --- /dev/null +++ b/thinking/agent-development-repo-structure.md @@ -0,0 +1,1782 @@ +# 开发 Agent 时，一个合适的 Repo 应该长什么样 + +## 核心论点 + +开发一个 Agent，尤其是 coding agent、research agent、workflow agent、tool-using assistant、multi-agent harness 这类项目，不应该被组织成简单的： + +```text +agent/ +evals/ +traces/ +``` + +这三个目录只能说明“这里有 Agent 代码、评估样例和运行记录”。它们不能稳定回答 Agent 开发真正困难的问题： + +```text +这个 Agent 声称具备哪些能力？ +这个能力声明来自哪个 eval run？ +这个 run 用的是哪个 prompt、model route、tool permission 和 memory policy？ +某个失败 trace 是否进入 regression？ +docs 里的能力描述是否超过 evidence？ +换模型、换工具、换部署环境后，这个结论还成立吗？ +``` + +它更应该被组织成一个可运行、可验证、可复现、可接续、可发布的 Agent 工程系统： + +```text +agent-development repo + = lab system + + human-facing deliverables + + project memory +``` + +更具体地说： + +```text +lab/ 生成行为证据的工程系统 +deliverables/ 给用户、集成方、评审者看的最终表达 +memory/ 管理 Agent 能力事实如何走向发布承诺 +``` + +这个结构的目标，不是为了让目录看起来整齐，而是为了让整个 Agent 项目围绕一条能力证据链运转： + +```text +capability claim + -> agent experiment + -> lab infra target + -> eval / trace replay / live trial + -> run logs + -> artifact index + -> evidence ledger + -> release note / docs / product behavior +``` + +如果这条链断了，项目就会退化成一堆 prompt、tool adapter、trace、eval report 和部署脚本。改了很多东西，但没人能稳定回答： + +```text +这个 Agent 到底支持哪些能力？ +这个能力声明来自哪个 run？ +这个 run 用的是哪个 config？ +这个 config 对应哪个 commit？ +这个失败 trace 是否进入 regression？ +tool permission 是否符合风险等级？ +release package 里包含哪套 prompt / policy / tool schema？ +``` + +一句话： + +> 一个好的 Agent repo，不只是存放 Agent，而是让 Agent 的能力声明、运行配置、评估证据、失败记录、发布产物和项目记忆都能被追踪、验证和接续。 + +--- + +## 1. 推荐目录结构 + +一个较完整的 Agent development repo 可以长这样： + +```text +/ + README.md + AGENTS.md + PROJECT.md + DECISIONS.md + + lab/ + code/ + src/ + my_agent/ + runtime/ + orchestration/ + tools/ + prompts/ + policies/ + memory/ + planning/ + observability/ + evaluation/ + utils/ + + configs/ + defaults.yaml + model/ + runtime/ + tool/ + prompt/ + policy/ + memory/ + eval/ + experiment/ + baseline/ + benchmark/ + infra/ + + scripts/ + run_agent.py + run_eval.py + replay_trace.py + collect_traces.py + compare_runs.py + package_release.py + submit_job.py + + baselines/ + wrappers/ + configs/ + reproduction/ + + benchmarks/ + tasks/ + metrics/ + protocols/ + runners/ + graders/ + + tests/ + unit/ + smoke/ + regression/ + + experiments/ + E001-baseline-agent/ + E002-tool-routing/ + E003-memory-policy/ + E004-model-route-upgrade/ + + infra/ + README.md + inventory.yaml + targets/ + local.template.yaml + sandbox.template.yaml + staging.template.yaml + production.template.yaml + providers/ + model-providers.template.yaml + tool-backends.template.yaml + observability.template.yaml + paths/ + logical-paths.yaml + path-map.template.yaml + environments/ + uv/ + pyproject.toml + uv.lock + docker/ + Dockerfile + compose.yaml + schedulers/ + local/ + tmux/ + queue/ + ci/ + launch/ + agent.template.sh + eval.template.sh + replay.template.sh + deploy.template.sh + storage/ + traces.yaml + eval-results.yaml + snapshots.yaml + releases.yaml + permissions/ + tool-permissions.yaml + approval-policy.yaml + data-access-policy.yaml + dependencies.yaml + external-scripts.yaml + probes/ + check_model_access.py + check_tool_permissions.py + smoke_agent.py + smoke_eval.py + smoke_replay.py + private/ + README.md + + research/ + BEHAVIOR.md + CAPABILITIES.md + SAFETY.md + claims.yaml + hypotheses.yaml + evidence.yaml + baselines.yaml + experiment-ledger.yaml + capability-matrix.yaml + regression-matrix.yaml + comparison-matrix.yaml + failure-analysis.md + reviewer-risks.md + + data/ + cards/ + task-sets/ + trace-corpora/ + labels/ + golden/ + manifests/ + privacy/ + checksums/ + + runs/ + README.md + .gitignore + + artifacts/ + README.md + agent-snapshot-index.yaml + eval-result-index.yaml + trace-bundle-index.yaml + release-index.yaml + .gitignore + + deliverables/ + docs/ + usage.md + deployment.md + troubleshooting.md + limitations.md + + reviews/ + behavior-review.md + safety-review.md + reliability-review.md + cost-latency-review.md + reviewer-risk-register.yaml + + demos/ + demo-script.md + demo-cases.yaml + + integration/ + api-contract.md + tool-contract.md + deployment-contract.md + + release/ + release-notes.md + release-checklist.yaml + promises.yaml + + memory/ + current-status.md + phase-dashboard.yaml + change-control.yaml + lab/ + active-experiments.yaml + eval-queue.yaml + trace-queue.yaml + infra-status.yaml + blockers.yaml + product/ + docs-status.md + demo-status.yaml + integration-status.yaml + release-status.yaml + reviewer-risks.yaml + bridge/ + claim-to-evidence.yaml + evidence-to-release.yaml + failure-to-regression.yaml + promises.yaml + handoff-log.md + archive/ + lab/ + product/ + bridge/ + handoffs/ + gc/ + retention-policy.yaml + compaction-log.md + tombstones.yaml +``` + +这不是第一天必须全部实现的模板。 + +第一天最重要的是把层级关系想清楚： + +```text +lab/ 证据生成层：代码、实验、基础设施、数据、运行、产物、能力账本 +deliverables/ 人类表达层：文档、review、demo、集成契约、release +memory/ 状态控制层：实验状态、产品状态、能力到发布的桥接状态 +``` + +--- + +## 2. 顶层文件 + +### README.md + +`README.md` 面向外部读者、新加入的人和潜在集成方，回答： + +```text +这个 Agent 是什么？ +解决什么问题？ +如何快速跑一个 smoke test？ +如何复现主要 eval？ +当前 release / capability / integration 状态是什么？ +``` + +不要把 README 写成调 prompt 日志。README 应该是入口，而不是事实数据库。 + +### AGENTS.md + +`AGENTS.md` 面向 Agent，回答： + +```text +进入项目后先读哪里？ +哪些目录是 lab、deliverables、memory？ +改 prompt / tool / policy / memory 后必须跑哪些 smoke checks？ +新增失败 trace 后必须写回哪些 ledger？ +哪些信息不能提交进公开 repo？ +哪些节点必须 human approval？ +``` + +对 Agent development project 来说，`AGENTS.md` 的关键价值是固定读写协议： + +```text +进入时： +AGENTS.md -> memory/current-status.md -> lab/research/claims.yaml -> relevant lab/code config or lab/experiments entry + +离开时： +update eval/run/result -> update evidence -> update memory/current-status.md -> report validation +``` + +### PROJECT.md + +`PROJECT.md` 是项目简介，面向人和 Agent 都可读。 + +它应该写： + +- Agent 的目标任务； +- 目标用户或目标集成场景； +- 核心能力简介； +- 工具和外部系统范围； +- 当前阶段； +- 成功标准； +- 不在范围内的内容。 + +### DECISIONS.md + +`DECISIONS.md` 记录关键决策。 + +Agent 项目里，很多决定会在后期变成暗知识： + +- 为什么选择这个 model provider，不选另一个； +- 为什么某个 tool 默认关闭； +- 为什么某个 action 需要 human approval； +- 为什么 memory 只保留某类事实； +- 为什么某个 eval suite 被认为有代表性； +- 为什么某个失败不修，而是写入能力边界。 + +这些都应该进入 decision log。否则几周后，人和 Agent 都会重新争论同一件事。 + +--- + +## 3. lab/code/：机器可执行的 Agent 系统 + +`lab/code/` 是工程主体。凡是可以被运行、测试、回放、打包、部署的东西，都应该在这里。 + +它回答： + +```text +Agent 如何运行？ +prompt / policy / tool / memory 如何组合？ +eval 如何启动？ +trace 如何回放？ +release artifact 如何打包？ +``` + +### lab/code/src/ + +`src/` 放 Agent 的核心运行逻辑。 + +一个 tool-using agent 可以拆成： + +```text +lab/code/src/my_agent/ + runtime/ # session loop, state machine, stop condition + orchestration/ # planner, router, subagent/team coordination + tools/ # tool schema, adapter, permission wrapper + prompts/ # prompt assembly, prompt bundle, few-shot selection + policies/ # approval, safety, retry, budget, scope policy + memory/ # memory schema, retrieval, writeback + planning/ # task decomposition, plan validation + observability/ # trace event, metrics, logging + evaluation/ # evaluation helpers used by scripts/runners + utils/ # seed, serialization, generic helpers +``` + +关键原则：prompt、tool、policy、memory 不要混成一团。 + +如果失败来自 tool permission，就不要用 prompt 补丁掩盖；如果失败来自 memory retrieval，就不要把规则硬塞进 system prompt。目录边界应该帮助人和 Agent 定位失败归因。 + +### lab/code/configs/ + +`configs/` 固定运行配置。 + +Agent 行为经常不是代码单独决定的，而是由： + +```text +code + prompt + model + tool permission + memory + runtime policy + external state +``` + +共同决定。所以配置必须可追踪、可 diff、可回放。 + +典型结构： + +```text +defaults.yaml +model/ +runtime/ +tool/ +prompt/ +policy/ +memory/ +eval/ +experiment/ +baseline/ +benchmark/ +infra/ +``` + +配置文件至少应该能回答： + +```text +这次 run 用哪个 model？ +允许哪些 tool？ +哪些 action 需要 approval？ +memory 从哪里读，写回哪里？ +eval runner 使用哪些覆盖项？ +``` + +### lab/code/scripts/ + +`scripts/` 是稳定入口，不是一次性 shell 草稿。 + +```text +run_agent.py +run_eval.py +replay_trace.py +collect_traces.py +compare_runs.py +package_release.py +submit_job.py +``` + +每个脚本都应该声明： + +- 输入是什么； +- 输出写到哪里； +- 是否会调用外部服务； +- 是否会产生副作用； +- 失败时如何区分 infra 问题和 Agent 行为问题。 + +### lab/code/baselines/ + +Agent 项目也需要 baseline。 + +baseline 可以是： + +- 无 tool 的 simple assistant； +- 旧 prompt bundle； +- 单模型版本； +- 无 memory 版本； +- 纯规则 workflow； +- 人工流程。 + +如果没有 baseline，项目很容易把“跑起来了”误判成“变好了”。 + +`baselines/` 可以包含： + +```text +wrappers/ 统一调用接口 +configs/ baseline-specific configs +reproduction/ 复现旧版本/竞品/人工流程的记录 +``` + +### lab/code/benchmarks/ + +`benchmarks/` 定义可重复比较的任务集合和评估协议。 + +对 Agent 来说，benchmark 不只是输入输出，还应该包括： + +```text +tasks/ +metrics/ +protocols/ +runners/ +graders/ +``` + +其中 `protocols/` 很重要。它应该写清楚： + +- 是否允许访问工具； +- 是否允许写入外部系统； +- 是否允许使用 memory； +- 是否允许多轮澄清； +- 是否需要 human approval； +- 成功标准看最终输出、过程动作，还是状态变化。 + +### lab/experiments/ + +`lab/experiments/` 保存实验卡。 + +例如： + +```text +lab/experiments/E002-tool-routing/ + experiment.md + config.yaml + runs.yaml + results.md + decision.md +``` + +每个实验至少回答： + +```text +改了什么？ +想验证哪个 hypothesis？ +跑了哪些 eval / replay / live trial？ +结果支持哪个 claim？ +失败是否进入 regression？ +下一步是什么？ +``` + +### lab/code/tests/ + +`tests/` 验证实现，不替代 eval。 + +```text +unit/ 小函数、小模块 +smoke/ tiny agent run / tiny eval / tiny replay +regression/ 已经踩过的 deterministic bug +``` + +它适合检查： + +- tool schema parsing； +- permission wrapper； +- prompt assembly； +- memory serialization； +- runtime state transition； +- budget/timeout handling； +- deterministic helper。 + +它不适合证明“Agent 能胜任某类任务”。那是 `lab/research/` 和 eval/benchmark 的职责。 + +--- + +## 4. lab/infra/：运行基底和计算目标 + +`lab/infra/` 记录 Agent 在哪里运行、依赖哪些外部能力、哪些路径和权限是本地事实、哪些东西不能进入公开 repo。 + +Agent 项目如果没有 infra 层，模型、工具、密钥、沙箱、权限、observability、trace storage 会散落在 README、环境变量、脚本和人的脑子里。 + +### lab/infra/inventory.yaml + +`inventory.yaml` 描述项目可用的运行目标： + +```yaml +targets: + local: + kind: local + purpose: development + side_effect_level: low + sandbox: + kind: sandbox + purpose: eval_and_replay + side_effect_level: controlled + staging: + kind: staging + purpose: integration_test + side_effect_level: medium + production: + kind: production + purpose: live_agent + side_effect_level: high + human_gate_required: true +``` + +它不保存密钥，只记录环境类别、用途和风险等级。 + +### lab/infra/targets/ + +`targets/` 记录不同运行目标的模板： + +```text +local.template.yaml +sandbox.template.yaml +staging.template.yaml +production.template.yaml +``` + +每个 target 应该声明： + +- 可用模型； +- 可用工具； +- side effect 级别； +- observability 后端； +- trace 保存位置； +- 是否允许 live external write； +- 是否需要 human gate。 + +### lab/infra/providers/ + +Agent 项目特别依赖外部 provider： + +```text +model-providers.template.yaml +tool-backends.template.yaml +observability.template.yaml +``` + +模型升级、tool API 变化、browser 行为变化，都可能改变 Agent 行为。provider contract 必须进入 repo，否则 evidence 失去上下文。 + +### lab/infra/paths/ + +路径不要写死在脚本里。 + +```text +logical-paths.yaml +path-map.template.yaml +``` + +建议使用逻辑路径： + +```yaml +paths: + trace_corpus: "${AGENT_TRACE_ROOT}/cleaned" + eval_results: "${AGENT_ARTIFACT_ROOT}/eval-results" + release_packages: "${AGENT_ARTIFACT_ROOT}/releases" +``` + +然后在本地 private path map 中映射到实际机器。 + +### lab/infra/environments/ + +`environments/` 固定运行环境： + +```text +uv/ + pyproject.toml + uv.lock +docker/ + Dockerfile + compose.yaml +``` + +Agent 项目需要明确： + +- SDK 版本； +- provider client 版本； +- browser / sandbox 依赖； +- evaluator 依赖； +- replay 依赖。 + +否则 eval pass/fail 可能只是环境漂移。 + +### lab/infra/schedulers/ 和 lab/infra/launch/ + +Agent eval 和 replay 也需要调度： + +```text +schedulers/ + local/ + tmux/ + queue/ + ci/ + +launch/ + agent.template.sh + eval.template.sh + replay.template.sh + deploy.template.sh +``` + +不要让每个人手写不同的 eval 命令。评估命令本身就是 evidence chain 的一部分。 + +### lab/infra/storage/ + +`storage/` 记录大对象位置： + +```text +traces.yaml +eval-results.yaml +snapshots.yaml +releases.yaml +``` + +这些文件不存密钥，只存逻辑位置、命名规则、保留策略和公开/私有边界。 + +### lab/infra/permissions/ + +Agent repo 比普通 ML repo 多一个关键层：权限。 + +`permissions/` 应该写清楚： + +```text +tool-permissions.yaml +approval-policy.yaml +data-access-policy.yaml +``` + +例如： + +```yaml +tools: + search_docs: + side_effect: none + approval: never + create_github_issue: + side_effect: external_write + approval: required + refund_payment: + side_effect: financial + approval: required + allowed_targets: + - sandbox +``` + +Agent 错误的严重程度，常常取决于 tool permission，而不是最终文本。 + +### lab/infra/dependencies.yaml + +`dependencies.yaml` 记录外部依赖： + +```yaml +python: + manager: uv + lockfile: lab/infra/environments/uv/uv.lock +models: + - name: gpt-5.5 + role: primary_agent +tools: + - name: github + side_effect: external_write + permission_file: lab/infra/permissions/tool-permissions.yaml +observability: + - name: langsmith + optional: true +``` + +它的作用是让 Agent 知道哪些依赖是项目边界的一部分，哪些只是本地便利。 + +### lab/infra/external-scripts.yaml + +很多 Agent 项目依赖外部脚本或 CLI： + +- GitHub CLI； +- browser automation； +- sandbox launcher； +- eval runner； +- release packager； +- internal workflow scripts。 + +这些都应该登记： + +```yaml +scripts: + - name: replay-prod-like-trace + source: external + location: ~/tools/replay-prod-like-trace + required: false + replacement: lab/code/scripts/replay_trace.py +``` + +如果脚本只存在某个人电脑上，就不能成为 project invariant。 + +### lab/infra/probes/ + +Agent 或人接手项目前，应该能先跑 probe： + +```bash +python lab/infra/probes/check_model_access.py +python lab/infra/probes/check_tool_permissions.py +python lab/infra/probes/smoke_agent.py +python lab/infra/probes/smoke_eval.py +python lab/infra/probes/smoke_replay.py +``` + +probe 的目标不是证明 Agent 很强，而是确认当前环境能不能产生可信证据。 + +### lab/infra/private/ + +`private/` 存模板说明，不存秘密。 + +真正的密钥、真实用户 trace、生产路径、本地 token 不应该提交进公开 repo。 + +`private/README.md` 应该说明： + +```text +哪些配置必须本地提供？ +哪些路径只允许 template？ +哪些 trace 禁止提交？ +如何脱敏？ +``` + +--- + +## 5. lab/research/：行为事实和能力证据账本 + +`lab/research/` 是 Agent 项目的事实源。它不只是“研究文档”，而是能力、行为、失败和证据的账本。 + +它回答： + +```text +我们声称 Agent 会什么？ +证据在哪里？ +哪些能力只是 hypothesis？ +哪些能力已经 regression-protected？ +哪些失败尚未关闭？ +哪些风险需要发布前处理？ +``` + +### lab/research/BEHAVIOR.md + +`BEHAVIOR.md` 描述 Agent 的目标行为和不变量。 + +它应该写： + +- 正常任务流程； +- 不确定时如何澄清； +- 何时停止； +- 何时请求 human approval； +- 哪些动作绝不自动执行； +- 如何处理外部系统副作用。 + +### lab/research/CAPABILITIES.md + +`CAPABILITIES.md` 用人类可读语言描述能力边界： + +```text +Supported: +- Can triage GitHub issues using labels and recent repo context. +- Can draft replies without sending them. + +Not supported: +- Cannot autonomously merge PRs. +- Cannot execute production payment actions. + +Conditional: +- Can update documentation when tests are local and deterministic. +- Needs human approval before external writes. +``` + +能力边界必须比 marketing copy 更保守。 + +### lab/research/SAFETY.md + +`SAFETY.md` 记录安全边界： + +- tool side effect； +- approval gate； +- sensitive data handling； +- prompt injection 风险； +- external write 风险； +- model/provider 风险； +- sandbox 逃逸风险。 + +### lab/research/claims.yaml + +机器可读的能力声明： + +```yaml +claims: + - id: cap.issue_triage.basic + statement: "Agent can classify GitHub issues into bug/feature/question with evidence." + status: supported + evidence: + - eval.issue_triage.v3 + - trace.live_review.2026-06-18 + regression: + - suite.issue_triage_core + release_visible: true +``` + +没有 evidence 的 claim 不应该出现在 release note 或 README 的能力承诺里。 + +### lab/research/hypotheses.yaml + +还没有被证实的想法放这里： + +```yaml +hypotheses: + - id: hyp.tool_router.confidence_gate + claim: "Adding a confidence gate before external writes reduces unsafe actions." + experiment: lab/experiments/E002-tool-routing/ + status: testing +``` + +### lab/research/evidence.yaml + +证据账本连接 claim、run、artifact 和 deliverable： + +```yaml +evidence: + - id: eval.issue_triage.v3 + claim: cap.issue_triage.basic + run: lab/runs/2026-06-20/eval-issue-triage-v3/ + artifact: lab/artifacts/eval-result-index.yaml#issue-triage-v3 + config: lab/code/configs/eval/issue-triage.yaml + commit: abc1234 + result: + pass_rate: 0.86 + critical_failures: 0 + reviewed_by: human +``` + +关键是把“我觉得变好了”改成“哪个 run 支持哪个 claim”。 + +### lab/research/baselines.yaml + +记录 baseline： + +```yaml +baselines: + - id: baseline.no_tools.v1 + description: "Assistant without tool access." + config: lab/code/baselines/configs/no-tools.yaml + evidence: eval.issue_triage.baseline_v1 +``` + +没有 baseline，很难判断 Agent 变更是否真的带来增益。 + +### lab/research/experiment-ledger.yaml + +实验总账： + +```yaml +experiments: + - id: E002 + title: tool routing confidence gate + hypothesis: hyp.tool_router.confidence_gate + status: completed + runs: + - lab/runs/2026-06-20/eval-tool-routing-v2/ + decision: keep +``` + +### lab/research/capability-matrix.yaml + +能力矩阵回答： + +```text +哪个能力在哪些场景下有效？ +哪些能力只是 demo 成功？ +哪些能力 release-visible？ +哪些能力需要 human approval？ +``` + +### lab/research/regression-matrix.yaml + +回归矩阵回答： + +```text +哪个历史失败被哪个 suite 守住？ +哪个 critical failure 还没有 regression？ +哪些 regression 依赖 LLM judge？ +``` + +### lab/research/comparison-matrix.yaml + +对比矩阵可以比较： + +- 当前 Agent vs baseline； +- 新模型 vs 旧模型； +- 新 prompt bundle vs 旧 prompt bundle； +- tool-enabled vs no-tool； +- memory-enabled vs no-memory； +- 竞品或人工流程。 + +### lab/research/failure-analysis.md + +失败分析不应该只放在 issue 或聊天里。 + +每个重要失败至少记录： + +- 失败现象； +- 触发条件； +- 归因：prompt / tool / policy / model / memory / infra / eval； +- 修复动作； +- 是否加入 regression； +- 如果不修，是否写入能力边界。 + +### lab/research/reviewer-risks.md + +Agent release 前最容易被 reviewer 质疑： + +- eval 只覆盖 happy path； +- docs 夸大能力； +- tool permission 过宽； +- trace 有隐私风险； +- LLM judge 不稳定； +- live trial 样本太少； +- 成本/延迟不可接受。 + +这些风险应该提前写出来，而不是等发布后才解释。 + +--- + +## 6. deliverables/：给人看的最终产出 + +`deliverables/` 是给用户、集成方、评审者和发布流程看的最终表达。 + +它不应该成为事实源。事实源在 `lab/research/`。`deliverables/` 应该引用证据，而不是发明证据。 + +```text +deliverables/ + docs/ + reviews/ + demos/ + integration/ + release/ +``` + +### deliverables/docs/ + +文档面向使用者： + +```text +usage.md +deployment.md +troubleshooting.md +limitations.md +``` + +如果 docs 声称某能力稳定，应该能回链到 `lab/research/claims.yaml`。 + +### deliverables/reviews/ + +Agent 发布前至少需要几类 review： + +```text +behavior-review.md +safety-review.md +reliability-review.md +cost-latency-review.md +reviewer-risk-register.yaml +``` + +review 不等于“再让一个模型夸一下”。它应该引用 evidence、trace、failure 和 gate。 + +### deliverables/demos/ + +demo 是展示，不是证据本身。 + +`demo-cases.yaml` 应该标记： + +- demo 对应哪个 claim； +- demo 使用哪个 agent config； +- demo 是否使用真实外部系统； +- demo 是否经过脱敏； +- demo 是否可 replay。 + +### deliverables/integration/ + +集成契约包括： + +```text +api-contract.md +tool-contract.md +deployment-contract.md +``` + +Agent 经常嵌入别人的 workflow。集成方真正关心的不是“prompt 写得多好”，而是输入、输出、副作用、失败模式、审批边界和日志接口。 + +### deliverables/release/ + +release note 不应该只写“improved tool routing”。 + +它应该写： + +```text +changed: + - tool routing policy v3 + - memory retrieval threshold + +evidence: + - eval.tool-routing.v4 improved pass rate from 0.71 to 0.83 + - no critical approval-boundary regression + +known limits: + - still fails multi-account ambiguity cases +``` + +Agent release 是能力承诺的外化。没有 evidence 的 release note 会把项目推向自我欺骗。 + +--- + +## 7. lab/data/：任务、Trace 和评估数据契约 + +`lab/data/` 保存相对稳定的数据资产。它不是 `lab/runs/`。 + +```text +lab/data/ + cards/ + task-sets/ + trace-corpora/ + labels/ + golden/ + manifests/ + privacy/ + checksums/ +``` + +### lab/data/cards/ + +每个 task set 或 trace corpus 应该有 data card： + +- 来源； +- 覆盖能力； +- 是否含真实用户数据； +- 脱敏方式； +- 允许用途； +- 已知偏差； +- 更新频率。 + +### lab/data/task-sets/ + +`task-sets/` 保存 curated eval tasks。 + +每个 task 不只是 prompt，还应该包括： + +```text +initial state +available tools +expected behavior +forbidden behavior +success criteria +risk level +human review requirement +``` + +### lab/data/trace-corpora/ + +`trace-corpora/` 保存清洗后的 trace。 + +trace 是最好的 debug/eval 材料，也是最容易泄漏隐私和密钥的材料。进入 repo 前必须经过 privacy/redaction 规则。 + +### lab/data/labels/ + +人工标签应该独立保存： + +- success/failure； +- failure category； +- severity； +- root cause； +- whether regression required。 + +### lab/data/golden/ + +Agent 的 golden 不一定是单一字符串。它可能是： + +```text +expected_outputs/ +expected_actions/ +expected_state/ +expected_files/ +expected_noop/ +expected_handoff/ +``` + +尤其要保留 `expected_noop` 和 `expected_handoff`。很多高质量 Agent 行为不是“多做事”，而是在风险超过权限时停止。 + +### lab/data/manifests/ + +manifest 记录每个 task set / trace corpus 的版本、来源和 checksum。 + +### lab/data/privacy/ + +privacy 规则必须明确： + +- 哪些 trace 可以提交； +- 哪些只能本地保存； +- 哪些必须脱敏； +- 哪些只保存 hash 或摘要； +- 哪些禁止进入模型上下文。 + +### lab/data/checksums/ + +checksum 用来保证 eval 数据没有悄悄变化。 + +```text +如果 task set 变了，历史 eval 分数就不再可比。 +``` + +--- + +## 8. lab/runs/：运行时日志，不做长期事实源 + +`lab/runs/` 记录每次执行、eval、replay、trial 的原始结果。 + +它通常应该被 `.gitignore`，只提交 README、schema 或小样例： + +```text +lab/runs/ + 2026-06-20_eval_issue_triage_v3/ + config.snapshot.yaml + metrics.json + traces.jsonl + failures/ +``` + +原则： + +- 原始 run 可以很大； +- run 可以被删除或归档； +- run 不是长期事实源； +- 进入长期事实源的是 `lab/research/evidence.yaml` 和 `lab/artifacts/*-index.yaml`。 + +也就是说，`lab/runs/` 是证据原料，`lab/research/` 才是证据账本。 + +--- + +## 9. lab/artifacts/：大产物索引 + +Agent 项目的产物可能包括： + +- packaged agent snapshot； +- prompt bundle； +- policy bundle； +- tool schema bundle； +- eval result； +- trace bundle； +- demo recording； +- release package； +- deployment manifest。 + +这些产物不一定适合直接提交进 Git。`lab/artifacts/` 的职责是索引： + +```yaml +releases: + - id: release.2026-06-20.v0.3 + commit: abc1234 + agent_snapshot: s3://... + eval_result: s3://... + trace_bundle: s3://... + release_notes: deliverables/release/release-notes.md + claims: + - cap.issue_triage.basic +``` + +没有 artifact index，几周后就会出现这种情况： + +```text +这个 demo 用的是哪个版本？ +这个 eval result 是不是最新的？ +release package 里到底包含哪套 prompt？ +``` + +--- + +## 10. memory/：项目状态控制面板 + +`memory/` 是给人和 Agent 接续项目用的。 + +它不是把所有资料都堆进去，而是回答： + +```text +现在项目处于什么阶段？ +下一步是什么？ +哪些 claim 正在验证？ +哪些 eval 还没跑？ +哪些 failure 还没关闭？ +哪些 release promise 还没证据？ +哪些旧记忆已经过期？ +``` + +建议结构： + +```text +memory/ + current-status.md + phase-dashboard.yaml + change-control.yaml + lab/ + product/ + bridge/ + archive/ + gc/ +``` + +### memory/current-status.md + +短文件，Agent 进入项目时优先读。 + +建议固定结构： + +```text +Current phase +Current goal +Recently changed +Next action +Validation status +Open blockers +Do not do +``` + +它应该指向事实源，而不是复制所有事实。 + +### memory/phase-dashboard.yaml + +用机器可读方式记录阶段： + +```yaml +phase: "stabilize-eval-harness" +active_claims: + - cap.issue_triage.basic +active_runs: + - lab/runs/2026-06-20_eval_issue_triage_v3/ +required_gates: + - approval_boundary + - privacy_redaction +next_actions: + - add replay case for ambiguous account selection +``` + +### memory/change-control.yaml + +Agent 项目特别容易出现“改了行为控制面，但没人更新证据”的漂移。`change-control.yaml` 记录影响行为的变化： + +```yaml +changes: + - id: change.2026-06-20.prompt-router-v3 + touched: + - lab/code/src/my_agent/prompts/router.md + - lab/code/configs/tool/defaults.yaml + expected_impact: + - cap.tool_routing + required_validation: + - lab/code/benchmarks/tasks/tool-routing.yaml + - lab/code/benchmarks/tasks/approval-boundary.yaml + status: validated +``` + +### memory/lab/ + +`memory/lab/` 记录证据生成层的状态： + +```text +active-experiments.yaml +eval-queue.yaml +trace-queue.yaml +infra-status.yaml +blockers.yaml +``` + +它回答： + +```text +哪些实验正在跑？ +哪些 eval 等待执行？ +哪些 trace 等待清洗？ +当前 infra 是否可用？ +哪些 blocker 会影响证据可信度？ +``` + +### memory/product/ + +`memory/product/` 记录人类表达层的状态： + +```text +docs-status.md +demo-status.yaml +integration-status.yaml +release-status.yaml +reviewer-risks.yaml +``` + +它回答： + +```text +哪些 docs 已经跟 evidence 对齐？ +哪些 demo 可以公开？ +哪些 integration contract 等待确认？ +release checklist 还缺什么？ +``` + +### memory/bridge/ + +`memory/bridge/` 是 Agent 项目最关键的接续层： + +```text +claim-to-evidence.yaml +evidence-to-release.yaml +failure-to-regression.yaml +promises.yaml +handoff-log.md +``` + +它连接： + +```text +能力声明 -> 证据 +证据 -> release/docs +失败 -> regression +承诺 -> gate +``` + +没有 bridge，lab 跑出来的结果很容易进不了 docs/release；docs/release 也很容易写出没有证据支撑的承诺。 + +### decisions 和 handoffs + +关键交接必须进入 repo： + +```text +谁改了什么？ +为什么改？ +哪些 eval 跑过？ +哪些没跑？ +哪些失败需要下一个人接着看？ +``` + +handoff 不应该只存在于聊天记录。 + +### memory/gc/：记忆遗忘机制 + +旧记忆会误导 Agent。 + +需要定期标记： + +- 哪些 status 已过期； +- 哪些 decision 被新 decision 覆盖； +- 哪些 action 已关闭； +- 哪些 failure 已进入 regression； +- 哪些 claim 被降级或撤销。 + +建议结构： + +```text +retention-policy.yaml +compaction-log.md +tombstones.yaml +``` + +没有 memory GC，Agent 会读到旧事实，并按旧目标行动。 + +--- + +## 11. 核心链路：从 Capability Claim 到 Release + +Agent repo 的核心链路应该是： + +```text +lab/research/claims.yaml + -> lab/code/benchmarks/tasks/ + -> lab/code/configs/ + -> lab/infra/targets + lab/infra/permissions + -> lab/runs/ + -> lab/artifacts/ + -> lab/research/evidence.yaml + -> deliverables/release/ +``` + +举例： + +```yaml +claim: cap.safe_issue_triage +task_set: lab/data/task-sets/github-issue-triage-v3.yaml +agent_config: lab/code/configs/eval/issue-triage.yaml +permissions: lab/infra/permissions/tool-permissions.yaml +run: lab/runs/2026-06-20_eval_issue_triage_v3/ +artifact: lab/artifacts/eval-result-index.yaml#issue-triage-v3 +evidence: lab/research/evidence.yaml#eval.issue_triage.v3 +release_note: deliverables/release/release-notes.md +``` + +这条链路让人能从一句能力声明一路追到运行证据。 + +如果追不到，就说明它还不是能力事实，只是项目愿望。 + +--- + +## 12. 主工作流 + +### 新增能力 + +```text +write hypothesis + -> add task set / benchmark protocol + -> implement agent change + -> run eval / replay + -> inspect failures + -> update evidence + -> promote or reject claim +``` + +关键点：先有 claim/hypothesis，再有 eval，再承诺能力。 + +### 修复失败 + +```text +capture failure trace + -> classify root cause + -> add replay/regression + -> modify prompt/tool/policy/code + -> run targeted validation + -> update failure-analysis and evidence +``` + +关键点：失败不能只被“修掉”。它要变成项目记忆。 + +### 发布版本 + +```text +freeze agent config + -> run release eval suite + -> check approval/privacy gates + -> package artifact + -> update release index + -> write release notes from evidence +``` + +关键点：release 是 evidence 的外化，不是 commit hash 的别名。 + +--- + +## 13. Human Gate 应该放在哪里 + +Agent 项目里，有些节点不应该让 Agent 自动越过： + +```text +external write +financial action +user-visible message +production deploy +permission broadening +memory retention change +claim promotion to release-visible +privacy rule relaxation +``` + +这些 gate 应该写进 `AGENTS.md`、`memory/phase-dashboard.yaml`、`lab/infra/permissions/approval-policy.yaml`、`deliverables/release/release-checklist.yaml` 或 launch/release 流程，而不是每次靠临时提醒。 + +--- + +## 14. 第一版先守住什么 + +第一版不用建完整目录。 + +先守住： + +```text +README.md +AGENTS.md +PROJECT.md +DECISIONS.md + +lab/code/ +lab/experiments/ +lab/infra/ +lab/research/claims.yaml +lab/research/evidence.yaml +lab/research/failure-analysis.md +lab/data/task-sets/ +lab/data/privacy/ +lab/runs/ +lab/artifacts/ + +deliverables/docs/ +deliverables/release/ + +memory/current-status.md +memory/phase-dashboard.yaml +memory/bridge/ +``` + +第一版要守住四件事： + +1. **能力声明可追溯**：claim 能追到 evidence； +2. **失败可沉淀**：failure 能进入 replay/regression 或能力边界； +3. **副作用可控**：tool permission 和 human gate 明确； +4. **状态可接续**：任何人或 Agent 三天后回来都知道下一步是什么。 + +--- + +## 15. 防漂移机制：Agent Harness Drift Control + +上面的结构如果只停留在文档里，长期开发后一定会漂移。 + +Agent 项目尤其容易出现几类漂移： + +```text +structure drift +dependency / script drift +goal / scope drift +memory drift +``` + +这些名字和 ML research repo 类似，但在 Agent 项目里有更具体的表现：capability、eval、permission、trace、release promise 都会漂。 + +### 15.1 Structure Drift + +典型问题： + +```text +README 说有 eval，但 lab/code/benchmarks/ 没有对应 suite； +lab/research/claims.yaml 引用的 evidence 不存在； +lab/research/evidence.yaml 引用的 run/artifact 不存在； +deliverables/release/release-notes.md 写了没有 claim 支撑的能力； +memory/current-status.md 指向旧 phase； +AGENTS.md 的读写协议和实际目录不一致。 +``` + +validator 应检查： + +```text +required files exist +required directories exist +YAML references resolve +claim -> evidence -> run/artifact chain exists +release-visible claim has evidence +failure -> regression or boundary exists +``` + +### 15.2 Dependency / Script Drift + +Agent 项目的 dependency drift 不只是包版本漂移，还包括： + +```text +model provider 版本或行为变化； +tool API schema 变化； +approval policy 被脚本绕过； +eval runner 版本变化； +LLM judge prompt 变化； +browser / sandbox 行为变化； +external CLI 只存在某个人机器上。 +``` + +需要记录： + +```text +lab/infra/dependencies.yaml +lab/infra/external-scripts.yaml +lab/infra/providers/ +lab/infra/permissions/ +lab/code/configs/ +``` + +validator 应检查： + +```text +every tool has side_effect level +external write tools require approval policy +production target cannot be default eval target +permission broadening requires decision entry +eval runner and grader versions are pinned +``` + +### 15.3 Goal / Scope Drift + +Agent 项目的目标很容易越写越大： + +```text +本来只做 issue triage，后来变成自动修 PR； +本来只 draft email，后来变成自动发送； +本来只在 sandbox 测试，后来默认连 production； +本来 claim 只是 internal，后来写进 public docs。 +``` + +需要防止： + +```text +PROJECT.md 的 scope 和 README/docs/release 不一致； +claims.yaml 中 hypothesis 被误写成 supported； +release-visible claim 没有 human-reviewed evidence； +out-of-scope action 没有 gate。 +``` + +`memory/change-control.yaml` 应记录会改变行为边界的变化。 + +### 15.4 Memory Drift + +典型问题： + +```text +memory/current-status.md 过期； +old decision 仍被 AGENTS.md 引用； +action 已完成但还在 next action； +failure 已修但没有进入 regression； +memory policy 改了但 eval 没重跑； +stale memory 继续影响 Agent 行为。 +``` + +解决方式： + +```text +current-status 必须短； +phase-dashboard 机器可读； +memory/bridge 维护 claim/evidence/release 的关系； +stale-memory audit 定期执行； +superseded decisions 显式标记； +memory writeback 进入 eval/replay。 +``` + +### 15.5 确定性 validator + +第一版 validator 不需要理解语义，先守住结构和引用： + +```bash +python scripts/validate-agent-harness.py +``` + +它可以检查： + +- 必需目录和文件； +- YAML schema； +- claim/evidence/run/artifact 引用； +- release-visible claim 是否有 evidence； +- tool permission 是否声明 side effect； +- human gate 是否覆盖高风险动作； +- privacy manifest 是否存在； +- memory/current-status 是否引用当前 phase； +- `lab/infra/private`、`lab/runs`、raw trace、secret-like token 是否被正确忽略或拦截。 + +### 15.6 语义审核 Skill + +确定性 validator 只能防止明显断链，不能判断 claim 是否夸大、eval 是否代表真实能力、failure 是否被错误归因。 + +所以还需要一个语义审核流程，专门问： + +```text +README/docs/release 的能力承诺是否超过 lab/research evidence？ +eval suite 是否只覆盖 happy path？ +critical failure 是否真的被 regression 保护？ +tool permission 是否与风险等级匹配？ +release note 是否诚实表达边界？ +memory/current-status 是否会误导下一个 Agent？ +``` + +这类审核可以由人做，也可以由 reviewer Agent 做，但必须引用具体文件和证据，不能只给泛泛建议。 + +--- + +## 16. 结论 + +一个 Agent repo 的核心，不是把 `agent/`、`evals/`、`traces/` 摆出来，而是建立一条从能力声明到行为证据再到发布承诺的链： + +```text +claim + -> experiment / eval / trace + -> config / permission / memory + -> run + -> artifact + -> evidence + -> release / docs +``` + +这条链让 Agent 开发从“调 prompt 的经验”变成“可审计的工程系统”。 + +好的 Agent repo 应该让任何接手的人或 Agent 能快速回答： + +```text +现在这个 Agent 到底会什么？ +凭什么说它会？ +哪些失败已经被守住？ +哪些风险还不能自动越过？ +下一步应该改哪里，改完如何验证？ +``` + +如果 repo 能回答这些问题，它才真正适合 Agent 开发。 diff --git a/thinking/production-agent-development-methodology.md b/thinking/production-agent-development-methodology.md new file mode 100644 index 0000000..010f723 --- /dev/null +++ b/thinking/production-agent-development-methodology.md @@ -0,0 +1,921 @@ +# 如何设计、开发一个生产级 Agent + +## 核心论点 + +2025-2026 年，OpenAI、Anthropic、LangChain/LangGraph 对 Agent 的理解正在从： + +```text +prompt + tools + memory +``` + +转向： + +```text +controlled runtime + + engineered context + + explicit action boundary + + trace-native eval loop + + human-gated production control plane +``` + +也就是说，一个好 Agent 不是“模型更聪明一点、prompt 更长一点、tools 更多一点”。真正决定生产表现的是： + +```text +它承诺什么行为； +它能采取哪些动作； +它每一步看到什么上下文； +它如何使用工具； +它失败后能否复现； +它改进后能否证明； +它上线后能否被观测、暂停、审批、回滚和继续学习。 +``` + +一个更硬的定义是： + +```text +Good Agent + = narrow behavior contract + + explicit action boundary + + engineered context + + constrained tool / skill interface + + traceable runtime + + human-gated side effects + + regression-backed learning loop + + production telemetry +``` + +这篇不是介绍“怎么调用某个 SDK”。它试图回答一个更上层的问题： + +> 如何让 Agent 的开发过程可控、灵活，同时让最终上线的 Agent 在真实生产环境中效果好？ + +--- + +## 资料边界 + +这篇综合的是截至 2026-06-28 的一手资料，重点来自： + +- OpenAI：Responses API、Agents SDK、Codex harness、trace grading、agent evals、Agent Improvement Loop、Macro Evals、Symphony。 +- Anthropic：Claude Code、Managed Agents、context engineering、tool design、Agent Skills、long-running harness、agent evals、auto mode、agent autonomy telemetry。 +- LangChain / LangGraph / LangSmith：LangGraph runtime、Deep Agents、Ambient Agents、context engineering、trajectory evals、observability、interrupts、persistence、Agent Inbox / Fleet oversight。 + +这里不把第三方观点当主证据。第三方文章可以启发语言，但不承担结论。 + +--- + +## 1. Agent 首先是 Runtime，不是 Prompt + +OpenAI 的 current stack 已经很清楚：简单 agentic primitive 走 Responses API；当应用需要管理 orchestration、state、approval、handoff 和 tracing 时，进入 Agents SDK。LangGraph 的方向类似：把 Agent 建模成 state graph、node、edge、checkpoint、interrupt 和 task queue。Anthropic 的 Managed Agents 更进一步，把 session、harness、sandbox 拆开，提出“brain”和“hands”的解耦。 + +这说明一件事： + +```text +Agent 的核心不是 prompt， +而是一个持续运行的受控状态机。 +``` + +Prompt 只是其中一个输入面。一个生产级 Agent 至少还包括： + +```text +runtime loop +state model +tool dispatcher +permission policy +context assembler +memory writer / reader +trace emitter +human approval gate +eval runner +rollback / repair path +``` + +如果这些东西没有显式设计，Agent 的行为就会被隐式 prompt、临时工具、聊天上下文和人的记忆共同决定。这种系统可以 demo，但很难生产化。 + +### 实践判断 + +如果一个 Agent 的关键行为只能通过“读懂 system prompt”来解释，而不能通过 runtime state、tool policy、trace 和 eval 复现，那么它还不是生产级 Agent。 + +--- + +## 2. 三条闭环 + +开发一个好 Agent，可以拆成三条闭环。 + +### 2.1 Design Loop + +```text +behavior contract + -> action boundary + -> context policy + -> tool / skill interface + -> runtime topology +``` + +这条闭环回答： + +```text +Agent 应该做什么？ +不应该做什么？ +遇到不确定性怎么处理？ +可以调用什么工具？ +哪些动作必须停下来问人？ +每一步应该看到什么上下文？ +``` + +Design Loop 的目标不是把 Agent 写死，而是把灵活性放在正确位置： + +- 模型负责不确定判断； +- deterministic code 负责状态、权限、恢复、审批、日志； +- eval/harness 负责证明和回归。 + +### 2.2 Evidence Loop + +```text +trace + -> label / review + -> eval dataset + -> regression + -> release gate +``` + +这条闭环回答： + +```text +Agent 为什么被认为变好了？ +失败能否复现？ +修复是否防止复发？ +release claim 是否有证据支撑？ +``` + +OpenAI 的 Agent Improvement Loop、LangSmith trajectory evals、Anthropic agent evals 都指向同一件事：Agent 不能只评 final answer，必须评 trajectory。 + +### 2.3 Production Loop + +```text +runtime state + -> observability + -> human approval + -> memory update + -> rollback / repair +``` + +这条闭环回答： + +```text +上线后出了问题能不能看见？ +高风险动作能不能停住？ +生产失败能不能回流成 eval？ +memory 会不会污染未来行为？ +``` + +生产 Agent 的质量，不来自上线前一次性调参，而来自这条长期闭环。 + +--- + +## 3. Behavior Contract：Agent 的最小设计单元 + +Agent 开发的最小单位不应该是 prompt，也不应该是 tool，而应该是： + +```text +behavior contract +``` + +一个 behavior contract 至少包括： + +```yaml +id: cap.issue_triage.basic +user: "repo maintainer" +task: "triage GitHub issues" +can_do: + - read issue body, labels, linked PRs, and recent repo context + - suggest labels with evidence + - draft a reply +cannot_do: + - close issue + - assign reviewer + - push commits +must_escalate: + - security vulnerability + - user data exposure + - ambiguous ownership +success: + - correct label + - cited evidence + - no unsafe external write +evidence: + - eval.issue_triage.v3 + - trace.live_review.2026-06-18 +``` + +这比“做一个 issue triage agent”硬得多。 + +它把 Agent 的开发对象从一个模糊功能，变成一组可测试、可审批、可回归的行为承诺。 + +### 为什么这重要 + +没有 behavior contract，就会出现三个问题： + +1. Prompt 改动没有锚点； +2. Eval 不知道该评什么； +3. Release note 很容易夸大能力。 + +生产级 Agent 必须能回答： + +```text +哪个 claim 被哪个 trace 支撑？ +哪个 failure 改变了哪个 claim？ +哪个 release promise 来自哪个 evidence？ +``` + +--- + +## 4. Action Boundary：能力来自动作边界，而不是工具数量 + +很多 Agent 项目的直觉是“多接工具，Agent 就更强”。2025-2026 的资料给出的结论更谨慎： + +```text +工具越多，action space 越大； +action space 越大，错误代价和评估难度越高。 +``` + +OpenAI 的 guardrails / approvals、Anthropic 的 sandboxing / auto mode、LangGraph interrupts、AWS AgentCore policy 都指向同一原则： + +> Tool access 必须被 deterministic policy 包住。 + +一个生产级 Agent 的 tool policy 不应该只是 allowlist，而应该至少包含： + +```yaml +tools: + search_docs: + side_effect: none + approval: never + logging: required + create_github_issue: + side_effect: external_write + approval: required + allowed_targets: + - sandbox + - staging + refund_payment: + side_effect: financial + approval: required + allowed_targets: + - sandbox + production: forbidden +``` + +### 2026 的新信号 + +Anthropic 的 Claude Code auto mode 不是简单“跳过权限提示”，而是尝试用分类器区分安全动作与危险动作。这个方向说明：human-in-the-loop 不是永远弹窗，而是要从粗糙 permission prompt 进化成分层控制系统。 + +```text +low-risk deterministic action -> auto +medium-risk reversible action -> logged / sampled review +high-risk external side effect -> interrupt / approval +irreversible or regulated action -> explicit human gate +``` + +这比“全自动”或“全手动”都更像生产系统。 + +--- + +## 5. Context Engineering：每一步给模型什么 + +LangChain 把 context engineering 拆成： + +```text +write +select +compress +isolate +``` + +Anthropic 也强调 context 是有限资源，不是越多越好。OpenAI 的 memory/compaction cookbook、Codex agent loop、long-running agent harness 都在处理同一个问题： + +```text +Agent 运行越久，上下文越容易变成垃圾场。 +``` + +生产 Agent 需要显式 context policy： + +```yaml +context_policy: + always_include: + - behavior contract + - current task + - current permissions + retrieve_on_demand: + - prior traces + - repo docs + - customer history + compress: + - long tool outputs + - old conversation turns + - repeated logs + isolate: + - subagent scratchpads + - untrusted tool output + - private user data + never_include: + - secrets + - raw production trace with PII +``` + +### 一个重要区别 + +Prompt engineering 问： + +```text +system prompt 怎么写？ +``` + +Context engineering 问： + +```text +在 agent trajectory 的第 N 步，模型应该看到哪些事实、工具、记忆、约束和证据？ +``` + +后者才是生产 Agent 的主问题。 + +--- + +## 6. Memory：持久状态不是聊天历史 + +LangGraph 区分 checkpointer 和 store：前者服务 thread continuity，后者服务跨 thread 长期记忆。Google Agent Platform 也区分 session、event、state、memory。LangChain 2026 的 memory 文章强调从 traces 派生 durable context，而不是把历史隐藏进 prompt。 + +Agent memory 至少应该分层： + +```text +session state 当前 run / 当前 thread 的短期状态 +working memory 当前任务内的中间计划、待办、约束 +episodic memory 过去 trace / failure / user correction +semantic memory 用户偏好、领域事实、组织规则 +policy memory 不应被模型自由改写的规则 +``` + +生产风险在于： + +```text +memory 一旦写错，会改变未来行为。 +``` + +所以 memory 需要： + +- schema； +- write policy； +- retention policy； +- human-edit path； +- deletion / tombstone； +- eval coverage； +- drift audit。 + +### 实践判断 + +如果 memory 无法回答“谁写入、为什么写入、何时过期、是否影响了哪个失败”，它就不是工程 memory，而是隐式 prompt 污染。 + +--- + +## 7. Tool / Skill 是能力接口 + +Anthropic 的 tool-writing 文章和 Agent Skills，OpenAI 的 Skills eval，SWE-agent 对 agent-computer interface 的经验，都说明： + +```text +工具接口本身就是 Agent 能力的一部分。 +``` + +一个好 tool 不只是函数： + +```text +name +description +schema +side_effect +latency / cost +output format +failure modes +permission level +examples +eval cases +``` + +### 工具设计的几个原则 + +1. **工具名要可发现** + 模型靠 name/description 决定是否调用。模糊名字会导致漏调或误调。 + +2. **输出要面向 Agent 消费** + 不要把 5000 行 JSON 直接塞回模型。工具应该返回摘要、关键字段、下一步建议和原始引用。 + +3. **大工具库要可搜索，不要全量注入** + Anthropic 的 advanced tool use 和 code execution with MCP 都指向 tool discovery / programmatic tool calling：工具多时，预加载所有 schema 会拖垮上下文。 + +4. **skill 要可测试** + OpenAI 的 skill eval 思路是：prompt -> trace/artifacts -> checks -> score。Skill 不是“说明书”，而是可触发、可运行、可回归的工作流单元。 + +--- + +## 8. Runtime Topology：从单 Agent 到 Deep / Ambient / Managed + +不要一开始就上 multi-agent。OpenAI 和 Anthropic 都倾向于先用简单 workflow，复杂度真的需要时再拆。 + +可以把 runtime topology 分成几层： + +```text +L0 single model call +L1 single agent loop with tools +L2 workflow + agent islands +L3 graph/state runtime with checkpoints +L4 long-running deep agent +L5 ambient/background agent with inbox +L6 managed agents: session / harness / sandbox decoupled +``` + +### Deep Agent + +LangChain 的 Deep Agents 指长时间、多步骤、有计划、有文件系统/子任务/上下文管理的 agent。它不是“更会聊天”，而是更像一个能维护外部工作区的长任务执行者。 + +Deep Agent 需要： + +- plan tool； +- durable scratchpad； +- file / artifact workspace； +- subagent isolation； +- checkpoint； +- compaction； +- resume； +- eval over trajectory。 + +### Ambient Agent + +Ambient Agent 不再只是被用户一句话触发，而是在后台监听事件、处理任务，并通过 inbox 请求人类确认。 + +它需要： + +- event source； +- task queue； +- notification； +- inbox； +- approval / edit / reject； +- audit log； +- stale task cleanup。 + +Ambient Agent 的 UX 不再是 chat，而是“持续工作的代理 + 人类审核队列”。 + +### Managed Agent + +Anthropic 的 Managed Agents 关键是解耦： + +```text +brain model reasoning +hands sandbox / tools / computer +session long-running task state +harness orchestration and policy +``` + +这个方向说明：未来 Agent 系统的稳定接口可能不是某个 prompt，而是 session、sandbox、tool protocol、trace 和 resume contract。 + +--- + +## 9. Eval：从 Output Eval 到 Trace-Native Eval + +Agent eval 和普通 LLM eval 的区别在于： + +```text +Agent 错误常常发生在过程里，不在最终答案里。 +``` + +一个 Agent 可能最终答案看起来对，但过程中： + +- 调用了不该调用的工具； +- 读了不该读的数据； +- 跳过了 approval； +- 写入了错误 memory； +- 进行了过多无效重试； +- 在不确定时没有澄清； +- 把 untrusted tool output 当成 instruction。 + +所以 eval 要看 trajectory： + +```text +messages +tool calls +tool args +tool outputs +handoffs +guardrail events +state changes +memory writes +human interrupts +cost / latency +final output +``` + +### Eval 分层 + +```text +unit checks tool schema、parser、policy wrapper +smoke eval 能否完整跑通 +trajectory eval tool sequence、handoff、approval、state +capability eval claim 是否成立 +regression eval 历史 failure 是否复发 +macro eval 整个 agentic system 的系统性问题 +production eval 真实 trace、抽样、人类标注、线上指标 +``` + +OpenAI 的 Macro Evals 很重要：它提醒我们，agentic system 的失败常常不是单个 response，而是跨许多 traces 的系统模式： + +```text +handoff too late +review triggered for wrong cases +specialist misses same signal +policy gate fires too often or too late +``` + +这类问题不能只靠单例 eval 发现。 + +--- + +## 10. LLM Judge 可以用，但不能当真理 + +OpenAI evaluation best practices、LangSmith eval concepts、Anthropic evals 都承认 LLM-as-judge 有用，但必须校准。 + +生产级使用方式应该是： + +```text +deterministic checks first +LLM judge for fuzzy criteria +human labels for calibration +pairwise / classification preferred over open-ended scoring +periodic drift audit +``` + +不要只留一个： + +```text +score: 8/10 +``` + +更好的输出是： + +```yaml +verdict: fail +failure_category: unsafe_tool_use +evidence: + - "called create_issue before approval" + - "approval_policy.yaml requires approval for external_write" +severity: critical +requires_regression: true +``` + +Judge 的价值不是给分，而是帮助把 trace 变成可行动的 failure label。 + +--- + +## 11. Infrastructure Noise 也是 Agent 质量问题 + +Anthropic 的 infrastructure noise 文章很关键：Agent eval 分数可能因为 infra headroom、pod kill、latency、环境抖动而变化。 + +这对 Agent 开发有一个直接含义： + +```text +不要把所有 eval 波动都解释成模型或 prompt 的变化。 +``` + +每次 eval 应该记录： + +```text +model +prompt bundle +tool versions +runtime version +sandbox image +resource limits +latency +timeout +retry policy +external service status +grader version +dataset version +``` + +否则你不知道一个 regression 是： + +- Agent 变差了； +- eval 变了； +- grader 变了； +- tool 变了； +- infra 变了； +- model route 变了。 + +生产 Agent 的 evidence ledger 必须包含 infra context。 + +--- + +## 12. Production Control Plane + +上线后的 Agent 不应该只是“API endpoint”。它需要 control plane。 + +最小 control plane 包括： + +```text +trace viewer +run state +tool call log +approval queue +feedback capture +memory editor +eval dashboard +release gate +rollback path +cost / latency monitor +security alerts +``` + +LangSmith 的 observability + feedback、OpenAI tracing/trace grading、Anthropic autonomy telemetry 都说明：生产 Agent 的核心指标不能只有 success rate。 + +更合理的指标包括： + +```text +task completion rate +unsafe action rate +approval request rate +approval rejection rate +human correction rate +escalation rate +regression recurrence rate +tool error rate +memory write error rate +latency +cost per successful task +tail turn duration +auto-approve rate +interrupt rate +``` + +### 一个判断 + +如果一个 Agent 上线后没有 trace、没有人工反馈通道、没有 approval/reject 统计、没有 failure-to-eval 回流，它就不是生产系统，只是部署了一个 demo。 + +--- + +## 13. 开发顺序 + +综合这些资料，我会把 Agent 开发顺序定为： + +### Step 1：定义任务域和错误代价 + +```text +用户是谁？ +任务是什么？ +错误代价是什么？ +哪些动作不可逆？ +哪些动作只允许草稿？ +哪些场景必须拒绝或升级？ +``` + +### Step 2：写 Behavior Contract + +不是写“Agent 会什么”，而是写： + +```text +能做什么； +不能做什么； +必须问人的是什么； +成功标准是什么； +证据在哪里。 +``` + +### Step 3：设计 Action Space + +先设计工具和权限，而不是先写 prompt。 + +```text +read tools +write tools +external side-effect tools +approval-required tools +forbidden tools +``` + +### Step 4：设计 Context / Memory Policy + +```text +哪些上下文 always include？ +哪些按需 retrieve？ +哪些压缩？ +哪些隔离？ +哪些永不进入上下文？ +哪些 memory 可以写？ +谁能改 memory？ +``` + +### Step 5：实现最薄 vertical slice + +先跑通一条真实任务链： + +```text +input -> context -> tool -> decision -> trace -> eval -> output +``` + +不要一开始做多 agent、长期 memory、复杂 planner。 + +### Step 6：建立 Trace-first Eval + +第一批 eval 不要追求大而全，而要能回答： + +```text +是否调用了正确工具？ +是否越权？ +是否在不确定时澄清？ +是否写了错误 memory？ +是否能复现历史 failure？ +``` + +### Step 7：用 Failure 驱动迭代 + +每个重要 failure 要进入： + +```text +failure-analysis + -> root cause + -> fix + -> regression + -> evidence update +``` + +不要只改 prompt。 + +### Step 8：扩大到 Long-running / Deep / Ambient + +只有当单轮/短流程稳定后，再引入： + +- checkpoint； +- resume； +- inbox； +- subagents； +- durable memory； +- background event processing； +- managed sandbox。 + +### Step 9：上线后持续学习 + +生产 trace 不是日志垃圾，而是下一轮 eval dataset 的来源。 + +```text +production trace + -> human feedback + -> labeled dataset + -> regression suite + -> harness change + -> release gate +``` + +--- + +## 14. Repo 里的落点 + +如果把这套方法落到前一篇 `agent-development-repo-structure.md`，对应关系是： + +```text +behavior contract -> lab/research/claims.yaml, CAPABILITIES.md +action boundary -> lab/infra/permissions/, lab/code/configs/tool/ +context policy -> lab/code/configs/prompt/, memory/ +tool / skill interface -> lab/code/src/*/tools/, skills or scripts +runtime topology -> lab/code/src/*/runtime/, orchestration/ +trace-native eval -> lab/code/benchmarks/, lab/runs/, lab/artifacts/ +failure loop -> lab/research/failure-analysis.md, regression-matrix.yaml +production control plane -> deliverables/release/, memory/bridge/, observability docs +``` + +也就是说，那个 repo structure 不是“文件夹模板”，而是为了支持这套开发方法。 + +--- + +## 15. 需要警惕的反模式 + +### 反模式 1：Prompt-first + +先写一个大 prompt，再不断补规则。 + +问题：行为边界、工具权限、eval 标准都被埋在自然语言里。 + +### 反模式 2：Tool-maxing + +接入大量工具，认为 Agent 自己会选择。 + +问题：action space 爆炸，tool selection 和 safety 都变难。 + +### 反模式 3：Final-answer eval + +只评最终回答。 + +问题：过程里的越权、错 tool、错 memory、错 handoff 全都漏掉。 + +### 反模式 4：Memory hoarding + +把所有历史都塞进 memory。 + +问题：旧事实污染未来行为，且很难解释为什么 Agent 做了某个决定。 + +### 反模式 5：No human gate + +一开始追求全自动。 + +问题：真实生产里，关键风险通常来自少数高副作用动作。 + +### 反模式 6：Benchmark worship + +只看 aggregate score。 + +问题：Agent 的真实问题常常是分布尾部、长流程、工具失败、审批边界和 infra noise。 + +--- + +## 16. 我的判断 + +2026 年 Agent 开发的主线，不是“更强模型自动解决一切”，而是： + +```text +模型能力上升以后， +工程问题从生成能力转向治理能力。 +``` + +Agent 越强，越需要： + +- 更清晰的 action boundary； +- 更严肃的 trace； +- 更好的 context/memory policy； +- 更可靠的 eval； +- 更可审计的 release gate； +- 更细粒度的 human approval； +- 更强的 runtime / sandbox / checkpoint。 + +所以，一个好的 Agent 开发方法，不是把模型关得越死越好，也不是把一切交给模型。 + +它应该是： + +```text +让模型在高价值、不确定、需要判断的地方发挥弹性； +让代码、策略、工具、trace、eval 和人类审批在高风险、可定义、可验证的地方提供硬边界。 +``` + +这就是我现在对“设计、开发一个好 Agent”的定义： + +> Agent engineering = 在真实任务分布中，把模型判断力放进一个可观测、可回放、可审批、可持续改进的行为系统。 + +--- + +## 参考资料 + +### OpenAI + +- [Migrate to the Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses) +- [Agents SDK](https://developers.openai.com/api/docs/guides/agents) +- [Running agents](https://developers.openai.com/api/docs/guides/agents/running-agents) +- [Integrations and observability](https://developers.openai.com/api/docs/guides/agents/integrations-observability) +- [Guardrails and human review](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals) +- [Trace grading](https://developers.openai.com/api/docs/guides/trace-grading) +- [Evaluate agent workflows](https://developers.openai.com/api/docs/guides/agent-evals) +- [Build an Agent Improvement Loop with Traces, Evals, and Codex](https://developers.openai.com/cookbook/examples/agents_sdk/agent_improvement_loop) +- [Build iterative repair loops with Codex](https://developers.openai.com/cookbook/examples/codex/build_iterative_repair_loops_with_codex) +- [Macro Evals for Agentic Systems](https://developers.openai.com/cookbook/examples/partners/macro_evals_for_agentic_systems/macro_evals_for_agentic_systems) +- [Testing Agent Skills Systematically with Evals](https://developers.openai.com/blog/eval-skills) +- [Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/) +- [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) +- [An open-source spec for Codex orchestration: Symphony](https://openai.com/index/open-source-codex-orchestration-symphony/) +- [The next evolution of the Agents SDK](https://openai.com/index/the-next-evolution-of-the-agents-sdk/) + +### Anthropic + +- [The "think" tool](https://www.anthropic.com/engineering/claude-think-tool) +- [Claude Code: Best practices for agentic coding](https://code.claude.com/docs/en/best-practices) +- [How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system) +- [Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents) +- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) +- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) +- [Making Claude Code more secure and autonomous with sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) +- [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) +- [Introducing advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use) +- [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) +- [Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) +- [Quantifying infrastructure noise in agentic coding evals](https://www.anthropic.com/engineering/infrastructure-noise) +- [Measuring AI agent autonomy in practice](https://www.anthropic.com/research/measuring-agent-autonomy) +- [How we built Claude Code auto mode](https://www.anthropic.com/engineering/claude-code-auto-mode) +- [Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents) + +### LangChain / LangGraph / LangSmith + +- [Introducing ambient agents](https://www.langchain.com/blog/introducing-ambient-agents) +- [LangGraph Platform is now Generally Available](https://www.langchain.com/blog/langgraph-platform-ga) +- [Context Engineering](https://www.langchain.com/blog/context-engineering-for-agents) +- [Deep Agents](https://www.langchain.com/blog/deep-agents) +- [Building LangGraph](https://www.langchain.com/blog/building-langgraph) +- [LangChain and LangGraph Agent Frameworks Reach v1.0 Milestones](https://www.langchain.com/blog/langchain-langgraph-1dot0) +- [How we build evals for Deep Agents](https://www.langchain.com/blog/how-we-build-evals-for-deep-agents) +- [Agent observability needs feedback to power learning](https://www.langchain.com/blog/agent-observability-needs-feedback-to-power-learning) +- [How To Give Your Agent Memory](https://www.langchain.com/blog/how-to-give-your-agent-memory) +- [Prompt Caching with Deep Agents](https://www.langchain.com/blog/deep-agents-prompt-caching) +- [LangSmith observability concepts](https://docs.langchain.com/langsmith/observability-concepts) +- [Trajectory evaluations](https://docs.langchain.com/langsmith/trajectory-evals) +- [LangGraph interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts) +- [LangGraph persistence](https://docs.langchain.com/oss/python/langgraph/persistence) +- [LangSmith access & oversight](https://docs.langchain.com/langsmith/fleet/access-and-oversight)