Agents API 生产验收清单：从身份边界到数据出站的可复核门槛

Agent API 进入生产，验收对象不是一次模型调用，而是一条能够读取上下文、选择工具、触发副作用、继续执行并留下证据的运行链。只验证“能不能返回答案”远远不够：请求来自谁、能调用什么、失败后会不会重复扣款、并发任务会不会串数据、人工能不能拦截高风险动作、出问题后能不能恢复，才决定这套系统是否适合承载真实业务。

下面的清单按生产验收顺序组织。每一项都要求提供可复核证据，并给出最低通过线与直接拒收条件。阈值是验收门槛，不是对任何具体厂商、模型或产品能力的事实判断。公告、演示页或二手介绍中出现的能力，只能作为待核对线索；只有当前版本官方 API 文档、实际响应、配置记录和受控测试结果，才能进入上线结论。尚未在文档中确认的字段、事件、模型名称、计费规则或测试资格，不得写入部署承诺。

一、先锁定验收范围与事实来源

验收开始前要建立一份版本化的范围表，至少记录 API 基础地址、SDK 或 HTTP 客户端版本、运行环境、使用的模型标识、工具清单、数据分类、地区限制、保留策略以及回滚目标。模型和接口名称必须逐字采用当前配置与官方文档中的名称，不要把宣传材料里的概念自动当成可调用的 API 参数。若公告描述了新的 Agent、Responses、工具调用、线程或后台运行能力，验收时应分别确认：能力是否已经进入目标账户可用范围；接口是否有稳定文档；请求和响应字段是否有版本承诺；错误码、限流、计费与数据处理说明是否完整。

证据最低要求是：每个关键结论至少绑定一份可访问的官方文档版本或接口契约、一组脱敏请求与响应、一次在目标环境中的执行记录。涉及权限、付款、删除、外发或生产写入的结论，还必须有配置快照和人工审批记录。只有截图而没有原始请求、响应和时间戳的材料，不足以证明接口行为。若发现宣传描述与当前文档或实际响应不一致，按较严格的一方处理，并把差异列为上线阻断项，不能用“后续可能开放”替代验收。

二、身份认证与租户边界

身份验收要回答三个问题：请求是谁发起的，系统代表谁执行，执行结果属于哪个租户或业务对象。API 密钥、OAuth 访问令牌、服务账号、用户会话和内部任务身份不能混成一个字符串传递。服务端应在入口完成令牌来源、签发者、受众、有效期、作用域和租户绑定校验；不能只检查“有值”或把一个全局密钥复制到所有工作进程。

• 检查密钥和令牌是否只存在于密钥管理系统或受保护的运行时注入点，源码、镜像层、前端包、日志、异常堆栈和任务输入中不得出现完整凭据。
• 检查每个令牌的最小作用域、过期策略、撤销路径和轮换流程。轮换时旧令牌应在规定窗口后失效，不能依赖重启服务才能生效。
• 用两个租户、两个用户和两个任务标识做交叉访问测试：A 的会话、工具结果、文件引用和审批记录不得被 B 读取或继续使用。
• 检查重放防护。对有副作用的请求，服务端应绑定请求身份、时间窗口和幂等键，重复提交不能仅凭相同正文再次执行。

证据阈值：至少完成一轮有效令牌、过期令牌、错误受众、错误作用域、撤销令牌、跨租户标识和重放请求测试；每类测试都要保存状态码、错误类型、审计事件和服务端最终状态。最低通过线是所有负向用例都被拒绝，拒绝结果不泄露内部令牌、租户是否存在或工具详细配置。直接拒收条件包括：日志出现完整密钥；只要知道会话 ID 就能换租户；令牌撤销后仍能继续执行敏感动作；匿名请求可以触发未审批的生产写入。

三、工具权限必须细到动作和资源

Agent 的工具注册表不是功能列表，而是权限边界。读数据库、写数据库、发消息、删除对象、执行代码、访问网络、下载文件和提交发布都应有独立的工具名、参数约束、资源范围与审批策略。不要因为一个工具内部“通常只读”，就把写入能力藏在同一个接口里；也不要用自然语言提示词代替服务端授权。

为每个工具建立权限卡：调用者身份、允许的租户、允许的资源前缀、可接受参数、数据分类、是否产生副作用、超时、重试方式、审批等级、审计字段和回滚动作。工具服务端必须再次校验这些内容，即使调用来自受信任的 Agent 编排器。参数应采用结构化 schema，拒绝未知字段、越界数量、危险路径、任意 URL、未登记的资源 ID 和把用户文本当作系统指令的混合输入。

验收证据至少包括完整工具清单、权限矩阵、注册 schema、服务端拒绝日志和一组越权测试。每个高风险工具至少要有一个允许样例和三个拒绝样例，覆盖错误租户、错误资源、危险参数或缺失审批。最低通过线是：只读身份无法写入；普通业务身份无法管理权限；工具不能自行扩展工具列表或作用域；未登记的外部域名、文件路径和回调地址全部被阻断。出现一次越权成功、隐式工具可调用、工具返回中夹带另一租户的敏感数据，直接拒收。

四、上下文连续性不能靠“看起来记得”判断

上下文能力应拆成会话标识、消息顺序、状态存储、工具结果引用和失效策略。一个 Agent 在第二次请求中能复述前文，不等于状态边界正确。验收需要验证服务端实际保存了什么、何时过期、谁能读取、上下文被截断时如何告知、工具结果是否可追溯，以及并行更新时采用什么版本规则。

• 创建会话后记录会话 ID、租户、创建者、版本和保留期限；用同一身份继续请求，确认只恢复预期上下文。
• 用旧会话 ID、另一租户身份、被撤销身份和过期会话分别访问，确认返回明确的拒绝或已过期状态。
• 制造超过上下文预算的长对话，检查系统是否按已知策略截断、压缩或拒绝，而不是静默丢掉权限约束和关键用户要求。
• 让工具返回一个可追踪结果，再在后续轮次引用它；结果必须带来源、时间、权限范围和失效信息，不能只保留模型生成的自然语言。

证据阈值：至少覆盖连续请求、并发更新、服务重启后的恢复、过期会话、上下文超限和工具结果引用六类场景；每类保留原始请求、响应、状态存储版本与审计链。最低通过线是状态恢复结果可重复解释，跨身份读取始终失败，截断不会移除系统级安全约束。若会话 ID 可枚举、删除会话后仍能从缓存或工具侧恢复敏感内容、上下文压缩改变了授权结论而没有阻断，直接拒收。

五、子 Agent 并发要验证隔离与汇聚规则

子 Agent 并发不是简单地开更多线程。必须明确父任务能授予哪些能力、子任务能否再创建子任务、各子任务的上下文和文件空间是否隔离、结果如何汇聚、部分失败如何表示、谁对最终副作用负责。并发任务应拥有独立的任务 ID、父任务 ID、租户标识、权限快照、预算和取消信号。

验收时同时启动多个任务，让它们使用相似的输入、不同的租户、不同的工具权限和不同的文件名。检查消息、缓存、临时目录、队列、数据库记录和日志索引是否串线。再测试一个子任务超时、一个被取消、一个返回不可信结果的情况，确认父任务不会把缺失结果当成成功，也不会因为某个子任务失败而无条件重放所有副作用。

证据阈值：至少完成一组可重复的并发交叉测试，包含不同租户、相同资源名、共享父任务、取消、超时和部分成功；保存任务拓扑、权限快照、开始结束时间、结果状态和资源清理记录。最低通过线是任何子任务都不能获得父任务未授予的工具和数据权限，父任务能区分成功、失败、取消和未执行，资源清理在任务结束后完成。发现跨任务文件可读、子 Agent 静默升级权限、部分失败被标记为整体成功，直接拒收。

六、沙箱隔离要以逃逸测试为准

沙箱验收不应停留在“使用了容器”或“运行在隔离环境”这样的描述。需要明确进程、文件系统、网络、环境变量、凭据、内核能力、设备、临时目录和资源配额。Agent 能执行代码或调用命令时，默认应是无特权、最小文件系统、最小网络、无宿主凭据挂载；确需例外时，应登记资源、理由、时长和审批人。

在非生产环境运行受控的负向用例：读取不应暴露的宿主路径，访问同机其他任务目录，读取环境变量中的秘密，连接未登记地址，创建过量进程和文件，使用超出配额的 CPU、内存、磁盘或时间。测试只验证隔离是否生效，不把真实生产秘密放入样例。网络出口要通过允许列表或明确的代理策略，DNS、HTTP、HTTPS、文件上传和回调地址都应纳入审计。

证据阈值：每次沙箱运行都能关联镜像或运行时版本、策略哈希、资源配额、网络规则和任务 ID；负向测试全部得到拒绝或受控终止；异常退出后临时文件和进程被清理。最低通过线是沙箱不能读取宿主密钥、不能访问其他任务的工作区、不能绕过出站策略。任何真实凭据默认出现在沙箱环境、任意网络访问未被记录、任务结束后残留可继续使用的进程或挂载，直接拒收。

七、重试、超时与幂等必须共同设计

重试不是可靠性的同义词。网络超时、限流、服务端错误、客户端断线和工具执行中断的含义不同，重试策略也应不同。对于查询类动作，可以在确认错误可重试后采用指数退避和上限；对于写入、发信、扣款、发布、删除等副作用动作，必须先有幂等键、状态查询或事务性结果确认。不能因为客户端没收到响应，就假设服务端没有执行。

验收一项副作用工具时，连续发送相同幂等键、相同参数，观察服务端是否只产生一次业务效果；再用相同幂等键但改变关键参数，确认请求被拒绝而不是覆盖原状态。模拟响应丢失、连接中断、429、5xx、工具进程重启和编排器重启，检查恢复流程是否能查询真实状态。重试日志必须标明尝试次数、原因、退避时间和最终状态，不能把多次尝试伪装成一次。

证据阈值：每类可重试错误至少有一次成功恢复和一次达到上限的记录；每个副作用工具都能证明重复提交不会增加业务次数；所有超时都有最终可判定状态。最低通过线是重试次数、总时长和并发放大受到限制，幂等键冲突会阻断执行，未知状态进入人工或查询队列。无法确认一次写入是否已经生效却自动再次写入、无限重试、把超时当失败并立即补偿性删除，直接拒收。

八、成本上限要能在运行中生效

成本控制需要覆盖模型调用、输入输出 token、工具执行、网络流量、存储、并发任务和人工审批等待带来的资源占用。不要只在月末看账单。每个请求、会话、工作流和租户都应有预算归属、估算值、已消耗值、预留值和停止条件。预算由服务端执行，不能只靠提示词让 Agent“节约使用”。

设置单请求、单会话、单工作流、单租户和全局的上限；同时限制最大轮次、最大工具调用数、最长执行时间、最大输出长度、并发数和重试次数。接近阈值时应发出事件或要求降级，超过硬上限则停止新增调用并返回可解释的预算错误。对于后台任务，要考虑任务挂起、人工等待和网络重试期间的计费状态。

证据阈值：用可控的小预算跑出正常、接近上限和超过上限三组结果，核对应用日志、供应商用量字段和账单或用量接口之间的口径差异。最低通过线是硬上限确实阻止继续消耗，预算按租户隔离，失败重试不会绕过预算。若请求可以通过创建多个子 Agent、刷新会话或切换工具逃避上限；成本字段无法关联到任务；或系统在超预算后仍持续调用，直接拒收。未知的定价、折扣和免费额度不得写成业务成本承诺。

九、审计日志要能还原一次决策

生产审计不是把所有文本都复制到日志里，而是用最小必要信息还原谁在什么时候、以什么权限、基于哪一版配置、调用了哪个工具、产生了什么副作用以及结果如何。请求 ID、任务 ID、父子任务关系、租户、主体、模型或运行时标识、提示与工具版本、权限快照、输入输出摘要、错误、重试、审批和资源变化应能关联。

日志要区分业务审计、调试日志和安全事件，分别设置访问权限、保留期限、脱敏规则和导出路径。秘密、完整令牌、密码、支付数据和不必要的个人信息不得写入。对于模型输入输出，记录可验证的摘要、哈希或脱敏片段，并保留取证所需的原始材料在受控存储中的引用。日志时间要统一，事件顺序要可排序，删除或修改审计记录应产生不可抵赖的记录。

证据阈值：随机抽取一条成功任务、一条拒绝任务、一条重试任务、一条人工审批任务和一条回滚任务，能从入口一直追到最终状态；至少有一种告警能由审计事件触发。最低通过线是关键副作用都有唯一关联 ID、权限与审批信息，日志访问本身也被记录。出现审计缺口、无法区分模型建议与工具执行、日志泄露完整秘密、管理员可以无痕删除关键事件，直接拒收。

十、人工审批要挡在副作用之前

人工审批不是在 Agent 完成后补看一眼，而是要位于高风险动作真正执行之前。审批策略应按动作、资源、金额或数据分类定义，而不是按“模型觉得风险不高”决定。发布、删除、外部发送、权限变更、生产配置修改、批量写入和敏感数据出站，都应有明确的审批等级。

审批请求应展示足够的决策材料：发起主体、目标资源、拟执行参数、影响范围、数据分类、工具权限、预算消耗、相关上下文摘要、风险提示、回滚动作和有效期。审批人不能只看到模型生成的理由；关键参数必须来自结构化请求和服务端状态。审批应绑定不可替换的请求摘要，参数改变后必须重新审批。拒绝、超时、撤回和审批人变更都应有最终状态。

证据阈值：至少测试批准、拒绝、过期、撤回、参数改变、审批人无权限和审批服务不可用七种路径。最低通过线是未审批动作永远不会落地，审批后的执行参数与批准摘要一致，审批服务故障时系统默认拒绝或安全暂停。若 Agent 可以代替审批人签自己发起的请求、只改一个关键参数就绕过重新审批、审批通知丢失但动作仍执行，直接拒收。

十一、回滚和恢复要在上线前演练

回滚不只是恢复上一版代码。需要分别设计模型或提示配置回滚、工具注册回滚、权限策略回滚、数据变更补偿、队列任务暂停、会话冻结和外部副作用处置。对于已经发送的消息、已经发布的内容或已经出站的数据，不能假设撤回一定可行，应在验收前明确不可逆动作和应急处置。

每个变更包都应有版本号、差异、迁移步骤、回滚条件、负责人、预计影响、验证命令和恢复后的健康检查。先在隔离环境制造失败，再做一次从告警到冻结入口、保留证据、回退策略、恢复服务和复核数据的演练。回滚操作自身要经过权限校验并写入审计，不能由任何工作进程静默完成。

证据阈值：至少完成一次配置回滚、一次工具权限回滚和一次任务中断恢复；每次演练都能给出开始时间、结束时间、数据差异、未恢复项和责任人。最低通过线是能够停止新增高风险动作，历史任务状态不会被伪造为成功，恢复后新旧版本边界清楚。没有可执行回滚步骤、只备份代码不备份策略和状态、回滚会删除审计证据，直接拒收。

十二、数据出站要逐条可解释

Agent 最容易被低估的风险，是把上下文、工具结果、文件内容、日志摘要或用户输入送往不清楚的外部位置。出站验收要列出数据类别、目的地、协议、调用工具、区域、加密、保留期限、第三方处理者和阻断方式。模型供应商、检索服务、代码执行环境、遥测平台、Webhook、邮件和对象存储都应分别登记，不能用“内部服务”一笔带过。

建立出站允许列表，并对域名、端口、HTTP 方法、请求体字段、文件类型、大小、压缩包内容和回调签名进行校验。敏感字段默认脱敏或阻断；用户提供的 URL 不能自动成为系统允许的目的地；重定向后的域名也要重新检查。出站失败时不应把完整数据塞进错误消息或备用日志。对跨区域和第三方处理，要有业务授权、合同或合规依据，不能以技术上能连通代替允许发送。

证据阈值：对公开数据、内部数据、敏感数据和凭据样例分别测试，覆盖允许目的地、未登记目的地、重定向、超大文件、恶意压缩包和网络失败；每次出站都可关联目的地、数据分类、策略版本和结果。最低通过线是敏感数据默认不出站，未登记目标被拒绝，阻断事件可告警且不泄露原文。发现凭据进入模型上下文或遥测、任意 URL 可触发服务器请求、出站失败将原始数据写入日志，直接拒收。

十三、把验收结果写成可签字的放行单

最终放行单至少分为通过、限期整改、带条件上线和拒收四种状态。通过意味着证据齐全、所有硬门槛满足；限期整改只能用于不影响安全边界且有负责人和截止时间的低风险缺陷；带条件上线必须明确租户、工具、数据类型、并发量或地区范围，条件由系统强制执行而不是写在备注里。任何身份越权、沙箱逃逸、未审批副作用、不可解释的数据出站、无限重试、无审计或无法回滚的问题，都只能判为拒收。

建议每项检查记录“要求、测试输入、预期结果、实际结果、证据链接、责任人、复测日期和结论”。验收证据应能由另一名工程师在同一版本和同一配置下复现；如果只能依赖口头说明、临时手工改配置或某台机器上的缓存，说明系统还没有达到生产可接受状态。上线前最后一次复核应确认代码、策略、工具 schema、环境变量、文档和审批矩阵的版本一致，并检查所有待办是否真的被系统阻断。

Agent API 的生产标准不是“模型回答得像人”，而是每个关键动作都能回答：谁授权、调用了什么、影响了谁、花了多少、出了问题如何停、数据去了哪里、恢复后怎样证明没有继续扩散。能够拿出这些证据，系统才具备被控制、被审计和被复盘的基础；缺少其中任何一条，就不应把演示能力当作生产能力。