为 Agent 提交接口增加写入预演
文章建议面向 Agent 的提交接口在实际写入前提供 dry-run,让调用方提前获取校验结果和接近真实提交的响应。作者借鉴 Kubernetes 与 Google API 设计指导,强调预演应避免持久化和其他副作用。
AI 深度解读
让 AI Agent 代用户提交资料时,可以先发一遍预检请求,看看这份内容会被接受、被拒绝,还是进入人工复核。作者在自己维护的目录站点上,把这一步做成了提交 API 的 dry run。它走同一套检查,返回正式提交会给出的结果,但不创建记录,也不发邮件。
这套设计最值得借鉴的地方,是把每种结果对应的下一步讲清楚。Agent 收到 409 后该改内容还是停手,看到「已接受」后该等审核还是继续查询,这些都要在第一次提交前从文档里找到答案。
预检为什么要复用正式提交的检查和响应
作者从基础设施 API 借来两个例子。Kubernetes 用查询参数 dryRun 触发稳定的 dry-run 模式。变更请求会经过准入、校验、合并冲突检查等常规阶段,在持久化前停下。响应体尽可能贴近真实请求,Kubernetes 保证预检不会写入存储,也不会产生其他副作用。Google 的 API 设计指引 AIP-163 建议用 validate_only,让预检返回实际执行时会给出的状态码、响应头和响应体。
目录站点的做法是复用同一个 endpoint 和请求体,只多传一个标记。原文没给这个标记的名字。服务端依次检查输入校验、内容政策、重复提交、历史拒绝和限流。预检会读取限流状态,但不消耗正式提交的额度。通过时,它报告这次提交将被接受,并说明是否会进入额外人工复核。失败时,它返回正式提交会给出的错误。这样,Agent 可以用同一套响应解析和错误分支处理两种请求。
预检顺序也属于接口契约。输入校验失败时,后面的检查还没给出结论。Agent 修完一个拼写错误,再次预检得到 409,两次结果完全可以同时成立。只在前端校验表单字段,能提前发现部分输入问题,但重复记录和历史审核结论仍要查服务端状态。
同一个状态码,为什么可能对应不同的下一步
RFC 9110 对 409 Conflict 的描述是,用户有可能解决冲突后重新提交。可如果某个域名已经被人工审核拒绝,再改一遍请求也无法通过。作者因此在文档里单列这类永久拒绝,说明它涉及哪些主机,并告诉 Agent 停止重试、把结果转告用户。只写一个 409,Agent 得自己猜这个冲突能不能解决。
429 的处理方式又不同。RFC 6585 建议在 429 响应里解释触发条件。这个站点的文档会写清限流范围,告诉 Agent 等待审核。在短时间内集中收到多条提交时,请求还有可能被接受后转入额外人工复核。接受、暂缓复核和正式上线是不同状态,看到复核提示时无需再提交一遍。
作者把预检标记、永久拒绝和检查顺序放在端点说明旁边,借鉴的是 llms.txt 提案所强调的做法,把关键说明集中到 Agent 容易拿到的纯文本里。OpenAPI 描述里也写同一套规则。否则,Agent 即使拿到了接口定义,也可能只知道该传哪些字段,仍然不知道失败后该怎么做。
预检通过后,正式提交超时怎么办
预检回答的是「按当前状态,这份请求能不能通过」。正式提交超时后,Agent 面对的是另一个问题,服务端到底有没有收到并处理刚才的请求。作者以 Stripe 为例,客户端使用同一个幂等键(idempotency key)重发请求,可以避免因为连接故障重复创建对象。
这个目录站点的文档没有提供幂等键。它采用每个主机只允许一条记录的规则,第二次提交同一主机会得到重复错误。文档让 Agent 保存首次响应里的标识符,避免无谓重提。这能覆盖该站点的重复创建场景,但如果第一次响应在超时时丢了,原文没有交代如何找回标识符或确认那次提交的结果。
我的判断
最有说服力的是把检查顺序、永久拒绝和待复核状态都写进契约。复用响应能减少一套解析逻辑,写清下一步则能直接指导 Agent 何时修数据、何时等审核、何时停手。作者报告的是自己站点的设计经验,没有给出对照数据,无法判断它实际减少了多少错误提交或重试。
作者把预检做成公开且无需认证,因为在他的站点上,正式提交原本就会给出相同答案。换到正式接口有鉴权的团队,或者错误会暴露内部记录和审核历史的产品,这个前提就得重新核查。预检也是一次即时判断。两次请求之间,其他人可能先提交同一主机,限流状态也可能变化,正式提交仍需完整执行检查。
能拿来做什么
- 给 Agent 写提交接口说明时,把预检参数的位置、检查顺序和错误处理方式放在端点旁边,并核对纯文本说明与 OpenAPI 是否一致。
- 如果维护 Node 提交接口,可以让预检和正式提交共用服务端检查,给两者返回同样的业务结果,并验证预检不写记录、不发邮件、不扣正式提交额度。
- 在 AI 编程工作流里分别处理永久拒绝、限流和待复核。永久拒绝就停手并告知用户,限流按说明等待,待复核就保留提交标识符。
- 给正式提交单独设计超时恢复路径。接口支持幂等键时,重试沿用第一次的键。只有主机去重时,把重复错误和首次提交结果未知分别处理。