Agent Developer 阶段总结：交付可证伪、可恢复、可约束的系统

核验日期：2026-07-16。阶段范围：LLM/Prompt/Structured Output、RAG、Tool Calling、MCP、A2A、OpenAI Agents SDK TS、LangGraph.js、AI SDK、评测、安全与生产化。

Agent 系统可以沿这条路径理解：goal → trusted identity/policy → context manifest → model proposal → validate/authorize/approve → retrieve/tool/remote task → observation → terminate → validate answer → trace/evaluate。模型负责生成候选，应用负责事实、权限、状态与副作用。任何一步都可能失败、重试、取消、等待人或跨部署恢复，因此最终文案只是交付的一部分。

十一个主题的核心结论

LLM 是有限上下文中的概率 next-token 引擎，不是数据库、权限系统或事务管理器。Prompt 是版本化输入程序，Structured Output 只保证形状后仍需语义验证。RAG 用可更新、可授权、可引用的外部语料约束事实，但需完整摄取/ACL/检索/引用/删除/评测。

Tool Calling 是模型提出调用，Agent Loop 是有限状态机；执行器拥有验证、授权、审批、幂等和 timeout。MCP 标准化 Host 与工具/资源/Prompt server；A2A 标准化独立 Agent 的 Message/Task/Artifact。Agents SDK 提供轻量 Agent/Runner/tool/handoff/guardrail/session/trace；LangGraph 提供持久状态图/checkpoint/interrupt；AI SDK 提供 TypeScript 多 provider 与 Web 流/UI parts。评测和安全贯穿全部层。

端到端证据链

线上每一步留下可脱敏证据；离线评测用 case/config/run/trace 关联这些证据。发现回归时找第一个错误中间状态：任务理解、context、检索、工具建议、验证、授权、执行、终止还是输出。不要用“幻觉”概括所有失败。

贯穿项目最终示例

技术目录助手的最终最小能力：

• POST /assistant/runs 接收目标和会话版本，认证后创建 run/task，返回 run id 与流/轮询入口。
• 只读 search_technologies/get_technology 工具复用后端服务，参数/结果有 Schema、tenant、deadline 和 trace。
• 文档 RAG 保存 source/chunk/index/version/ACL，回答只引用本次可见 source id。
• Agent 有 max steps、总 deadline、token/cost/tool 预算、取消和明确 termination。
• 写动作使用 preview/approval/commit，绑定参数哈希与 operation id；默认不启用也不影响只读示例。
• 会话消息、run/task、checkpoint、approval、业务副作用和长期 memory 分开持久。
• UI 消费类型化 text/tool/source/status/error/finish 事件，断线可按 run id 恢复，取消语义明确。
• CI 用假模型/工具/语料；真实模型只在受控评测与 canary；所有配置有版本指纹。

没有必要为了显得内容齐全而同时使用三种框架、MCP 和 A2A。一个推荐对照方案是普通 TypeScript 有限循环 + 领域工具 + 固定 RAG + 自有 task/trace；根据 Web 流选择 AI SDK，根据 Agent 原语选择 Agents SDK，根据持久复杂图选择 LangGraph；只有出现真实互操作边界时才加入 MCP/A2A。

数据模型

agent_run：id、tenant/principal 引用、goal hash/安全摘要、status、deadline、step/budget/usage、config fingerprint、termination、result/error、created/updated/version。agent_event：run id、sequence、kind、payload reference/hash、created。tool_operation：call/operation id、tool/version、normalized input hash、authorization/approval、attempt、status、result/error reference。

source_chunk：source/chunk id、URI/范围、content hash、ACL、parser/chunker/embedding/index version、deleted/updated。approval：proposal hash、resource version、risk、requester/approver、decision、expiry。eval_run：case/config/run/trace、grader versions、scores/evidence。敏感正文进入受控对象存储或不保存，表中保存引用和分类。

状态变更使用乐观版本/事务；事件 sequence 稳定；同 operation id 不同 input hash 冲突。数据库不依赖 SDK 私有序列化，便于迁移。

运行状态

所有终态有 reason；waiting 状态有 owner/expiry；running 有 lease/heartbeat；部署不会把内存 Promise 当持久状态。重试回到 queued 或特定节点并保留 attempt/剩余预算。

Context Manifest

每次模型调用生成 manifest：系统/产品策略版本、当前任务、用户提供内容、会话选择/摘要、检索 chunk/citation、工具结果、token 估算、信任级别、权限范围、创建时间、内容哈希与被裁剪项。Manifest 使上下文可解释，也支持删除和数据外发审计。

高优先级策略与结构化业务状态不由摘要替代。外部文档/工具结果均标记不可信，不能指挥系统。模型调用只收到所需字段，不获得数据库/secret/全量历史。

Tool Registry

每个工具记录 owner、名称/版本、描述、input/output schema、read/write/risk、required action、tenant handling、side effect/idempotency、timeout/concurrency/cost、approval、result size、错误码、数据分类、测试和 kill switch。运行只暴露允许子集，执行时再次授权。

工具服务沿用全栈后端的约束：验证、认证、资源级授权、事务、constraint、idempotency、outbox、deadline、审计和稳定错误。Agent 不能为不可靠 API 补出一致性。

模型与配置指纹

configFingerprint = hash(app commit + model/profile/parameters + prompt + output schema + tools + policy/guardrails + corpus/index + framework/sdk)。运行、评测和发布记录它。别名模型更新、Prompt 改字、工具描述或 index 切换都可能改变行为，必须可关联。

配置由服务端选择，客户端只能请求受允许的产品模式。高风险 profile 无未评测 fallback。升级一次尽量改变一个主要因素，离线/对抗/shadow/canary 后扩量，保留兼容回滚。

离线验收套件

确定性控制流

假模型脚本覆盖 final、合法/未知/无效工具、工具修正、永久/可重试错误、max step、deadline、费用、cancel、审批暂停/恢复、并行 call id、结果过大和异常结束。断言真实执行次数、顺序、参数、状态和 termination。CI 无模型密钥和付费网络。

检索与引用

固定语料包含正常、旧版、同词反义、其他 tenant、恶意注入与已删除 source。测 parser/chunk manifest、ACL、recall@k/rank、context selection、空召回拒答、citation 存在/支持和删除切换。Index 可从 manifest 重建。

协议与框架

MCP 测版本/能力、stdio/HTTP、auth/session/断连；A2A 测 Card、Message/Task/Artifact、流/push/取消/幂等；框架测 session/checkpoint/interrupt/stream 迁移。只采用的组件进入发布门禁，不为未使用技术增加生产依赖。

安全与故障

直接/间接注入、跨 tenant、SSRF/路径/命令、secret、审批绕过、memory poisoning、恶意 server/Agent、资源耗尽；数据库/模型/工具慢与断开、429、响应丢失、worker 强杀、部署和凭证轮换。断言无越权/重复副作用、状态可恢复和 trace 脱敏。

真实模型质量

数据按任务/风险/语言/来源/长度/故障分层，确定性 grader 优先，模型 grader 经人工校准，报告样本/区间/失败 taxonomy、质量/安全/延迟/成本。测试集与 Prompt 示例分离。真实调用不可用时门禁显示未运行，不用缓存伪造。

生产 SLO 与预算

系统：run 接受/完成可用性、queue、TTFT、完整 p95/p99、stream error、任务 stuck/recovery。质量：任务成功、引用支持、正确拒答、tool/trajectory。安全：false allow/deny、跨 tenant、危险副作用/审批绕过、注入成功。经济：每成功任务 token/API/存储/人工，租户与全局预算。

报警映射 runbook：provider 限流、tool error、index lag、checkpoint failure、费用异常、循环、审批积压和安全事件。指标低基数，详细 ID 在 trace/audit。用户可见状态区分排队、生成、工具、等待审批、完成、失败、取消。

部署与恢复演练

启动验证配置、模型 profile、tool Schema、数据库/index 与 protocol capability；readiness 后接流量。Canary 固定 config 指纹，比较现有质量、安全与成本。关闭停止领取 run，短 run drain，长 run checkpoint/释放 lease。旧任务按创建版本恢复或迁移。

演练模型 outage：有限 queue/退避、允许的 fallback 或明确失败；工具 timeout：取消/幂等重试；响应丢失：按 operation 查询；worker 强杀：lease 恢复；checkpoint/schema 升级：旧状态可读；index 切换：旧/新完整快照；kill switch：禁写工具仍可只读；回滚：应用、Prompt、tool/index 兼容组合恢复。

安全交付包

资产/主体/数据流/信任边界图；工具权限表；数据分类、供应商和保留；prompt injection/越权威胁；沙箱/网络/secret；approval/职责分离；预算/限流；MCP/A2A 信任；供应链/SBOM；audit/kill switch；事件响应与删除流程。每个高风险控制有负例和 owner。

故障排查总图

先找首错，修对应层并增加最小回归；不要通过换更大模型掩盖 ACL、Schema、工具或状态 bug。

评审问答

随机抽一个事实：来源在哪里、为何当前用户可见、哪一版 index、引用怎样验证。随机抽一个工具：模型看见什么、服务端怎样授权、超时/响应丢失如何处理、审批绑定什么。随机抽一个 run：为何继续/终止、总预算、部署后怎样恢复。随机抽一个发布：哪些 case 比对照方案变好/变坏、区间和回滚。

再抽协议/框架：MCP 与 A2A 为何不是一回事；选择 Agents SDK/LangGraph/AI SDK 的具体问题；若移除框架，领域状态和工具是否仍可用。答案必须有数据/trace/test，不只复述功能列表。

完成标准

能够解释模型、上下文、检索、工具与 Agent 分工；实现有限、可取消、可持久循环；RAG 有 ACL/引用/删除/评测；工具有 Schema/授权/审批/幂等；协议有版本/认证/恢复；框架 owner 清晰；CI 确定性；真实质量有数据；安全有外部控制；生产有 SLO、预算、发布、回滚和事故演练。满足这些条件，Agent 才从演示变成可运营软件。

容量模型与过载策略

容量不能只按“每秒请求数”估算。一个 run 可能包含多个模型 step、并行检索、远程工具和人工等待。先从历史或评测得到每种任务的 step、input/output token、工具次数和完整时间分布，再估算模型并发、供应商 rate/token limit、数据库连接、worker lease、流连接和队列。到达率上升或下游变慢都会增加在途量；无限队列只会把可见拒绝变成超时、内存和账单事故。

入口按租户与全局做 admission control：预算充足且预计能在 deadline 内完成才进入；否则返回带重试/任务语义的稳定错误。交互生成与后台批任务使用不同队列和配额，避免一次离线评测抢占所有在线流。模型、检索、每类工具和远程 Agent 分别有 semaphore/bulkhead，一个下游故障不占满全部 worker。

容量测试分两段。第一段用 fake model/tool 以可控延迟、流量和错误率压应用，观察连接、内存、backpressure、checkpoint 和数据库；第二段用小规模真实供应商验证 rate limit、TTFT 和 usage，不进行无上限付费压测。报告 task mix、并发、持续时间、p50/p95/p99、queue、完成/取消/错误、token/费用、资源和恢复。

过载降级必须保持语义：可以暂停低优先级批任务、减少经评测的候选召回、关闭非必要流细节、切已达门槛的模型 profile，或只提供搜索结果；不能跳过授权/引用/审批，也不能让模型凭记忆冒充实时工具。系统恢复后逐步放量，防止积压同时重试形成惊群。

配置与数据变更兼容组合

Agent 发布不只有代码版本。旧 run 可能引用旧 Prompt、tool Schema、index、MCP capability、A2A Card 和 checkpoint。对每一类变更写兼容策略：

迁移测试至少从每个长期状态抽一个旧样本，在新代码中读取、恢复、完成和审计。无法兼容时给出安全终止、用户通知和补偿，而不是让任务永久 stuck。评测数据的 reference/语料版本也要迁移或冻结，否则新旧分数没有同一事实基准。

从本地示例到生产的四个里程碑

第一里程碑是“确定性骨架”：领域端口、固定语料、假模型、两个只读工具、有限循环、稳定错误和 trace。此时不接写工具、不做多 Agent，CI 能覆盖所有状态与故障。

第二里程碑是“真实质量”：接一个已批准模型 profile，构建代表性/对抗数据集，分开评检索、工具和输出，测延迟/成本；Prompt、model、tools 和 index 形成指纹。未达门槛时修首个失败层，不扩大功能。

第三里程碑是“持久与受权”：run/task/session/checkpoint、tenant ACL、approval/idempotency、取消/恢复、数据保留与删除。根据真实需求选择 AI SDK/Agents SDK/LangGraph/MCP，不改变领域契约。完成强杀、断线、响应丢失和部署迁移演练。

第四里程碑是“受控生产”：shadow/canary、SLO/预算、告警/runbook、kill switch、审计、供应链和事故响应。少量流量验证用户体验和线上代理指标，人工复核失败，逐步扩量。每个新增写工具或远程 Agent 重新过威胁模型和评测门禁。

交接目录

交给维护团队的不是一个聊天页面，而是一组可定位资产：架构/信任边界图；任务与状态 Schema；模型/Prompt/tool/index 清单；数据来源/ACL/保留；工具权限/审批/幂等表；协议对端和认证；离线数据集/runner/报告；SLO/容量/费用；部署/迁移/回滚；安全测试/审计/kill switch；故障/事故 runbook；owner、复审日期与已知限制。

新人应能在没有生产 secret 的本地环境运行 fake suite，重现一条成功、一个检索空结果、一个无效工具、一个审批暂停、一个超时和一次恢复。On-call 应能从报警到 task/config/trace 找首错，禁用具体能力而非关闭全部服务。审查者应能从任意引用回到 source/version，从任意副作用回到用户/审批/operation。

继续学习与复审

模型/协议/SDK major、数据/权限、写工具、高风险领域、跨组织、长任务、流量/SLO、供应商政策、攻击或事故变化时重读对应文章和 技术选型比较。追新不是目标；每次升级都要说明解决了哪个已测问题，并保留更简单路径。

专栏完成后的复审节奏分三类：依赖安全公告和供应商政策变更立即处理；模型、协议、SDK 与语料版本按发布窗口评测；任务分布、质量、安全、容量和成本按月或季度回看。若指标长期证明某个 Agent 分支、框架或远端协议没有贡献，应删除并缩小故障面。若失败集中在后端数据、授权或事务，则回到第五栏修服务，不通过增加模型步骤绕过。

最终路线要求每一份自主权都有任务必要性、最小权限、可见状态、预算、测试和撤销路径，不以“让 Agent 自主做更多”为目标。模型能力增强时这些边界仍然成立；模型能力不足时，它们也能让失败稳定、可解释，并允许人工接管。

复审还要检查文档与实现是否一致：代码中新增的工具、数据源、远端 Agent、模型参数和保留字段必须回写清单；文档声明的 timeout、审批和删除策略必须有自动测试或演练记录。若只能在文档中找到控制、在 trace 和测试中找不到，它就不是已交付能力。反之，运行时存在但未登记的动态能力属于影子接口，应在发布前移除或纳入治理。

团队可以用季度抽查保持证据有效：随机选择一个线上 run，验证身份、来源、工具、费用和终止；随机选择一个等待任务，执行恢复和版本迁移；随机选择一条删除请求，追踪派生数据；随机选择一个安全拒绝，确认用户能获得可恢复说明。抽查结果进入下一轮数据集和容量计划，让路线图持续对应真实系统。

返回专栏导读 · 返回在线文档首页