基础篇
进阶篇
高频篇
精选篇
手写篇
面经篇
AI 篇
原理篇
每日一题
小程序题库
  • 知识卡片碎片时间过考点
  • 场景篇按分类整理的大前端场景考点
  • 历年面经按年份追踪真实考点
  • 算法题库NEW在线编码即时判题
  • 专项自测100 题快速查漏
  • 前端基础
    • HTTP从报文一路讲到 HTTPS
    • 浏览器渲染、事件循环、进程
    • 计算机基础Linux、网络、操作系统
  • 进阶专项
    • 设计模式23 种模式怎么用
    • 前端系统进阶学习大型项目工程化
    • 前端综合文章长期沉淀的实践文
  • 工程与工具
    • Node学习指南从环境搭建到服务端
    • NPM工作流script、依赖与发布
    • Docker容器化部署上手
    • Canvas图形与动画实战
  • 路线与导图
    • 思维导图知识点全景图
    • 学习路线按图索骥不跑偏
  • 动态
    • 公众号动态公众号历史文章
    • 博客动态站长的技术博客
    • 开发者导航常用工具与文档站
    • AI 热点每日 AI 资讯与动向
AI 工作台
旧版
AIHT
内容
精选全部 AI 动态热点榜AI 日报收藏
分类
模型行业编程产品技术观点开源
更多
Agent 接入
返回首页开发者导航
AIHT
精选 / 资讯详情
8.0
热点
AI SCORE
技术实践2026-11-22 16:10

为 Agent 提交接口增加写入预演

dev.to · AI#接口设计#Agent#写入预演
Editor brief · 编辑速览

文章建议面向 Agent 的提交接口在实际写入前提供 dry-run,让调用方提前获取校验结果和接近真实提交的响应。作者借鉴 Kubernetes 与 Google API 设计指导,强调预演应避免持久化和其他副作用。

文章思维导图
Knowledge map
拖拽缩放
AI deep read

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 编程工作流里分别处理永久拒绝、限流和待复核。永久拒绝就停手并告知用户,限流按说明等待,待复核就保留提交标识符。
  • 给正式提交单独设计超时恢复路径。接口支持幂等键时,重试沿用第一次的键。只有主机去重时,把重复错误和首次提交结果未知分别处理。
Original source

本文由 AI 通读原文后重新编写,观点部分为站内判断,细节以原文为准,来源 dev.to · AI,原文版权归原作者所有。

阅读原文
上一篇
Agent 推送前审批规则为何没有生效
下一篇
用 Claude Code 钩子拦截危险命令

资讯速览

dev.to · AI · 2026-11-22 16:10

AI 评分 8.0 / 10

相关标签

#接口设计#Agent#写入预演

继续阅读

  • 通过 MCP 让 Claude Code 直接查询日志
  • Agent 推送前审批规则为何没有生效
  • 用 Claude Code 钩子拦截危险命令
  • 用单次调用能耗定位 Agent 工具浪费
  • Agent 开发环境选型:先分清四层能力