博客
面向 agent 的后端

发布于 更新于

Arag 和 Shouryamaan

如何构建 AI Coding Agent 可运维的后端

以 Markdown 阅读

如果 coding agent 能通过结构化契约创建、检查、使用、恢复、移交和移除后端资源,这个后端才称得上可由 agent 运维。运行时 API 访问只是其中一步,项目配置、凭据、故障、所有权和清理也都必须覆盖。

最快的测试方法,是追踪一个数据库或部署的完整生命周期。缺少状态查询或删除契约,就仍然依赖人工操作控制台。

Agent 可访问与 agent 可运维并不相同

在 agent 可访问的后端中,人工完成配置后,应用才能调用数据库或 API。在 agent 可运维的后端中,获得授权的 agent 还能执行建立并维护这一状态所需的管理工作。

生命周期步骤 可访问的后端 可运维的后端
创建 人工使用控制台 Agent 调用类型明确的创建操作
发现 人工复制 ID 和 URL Agent 获得结构化标识符和端点
使用 应用调用服务 应用使用限定范围的数据面凭据
恢复 人工读取日志并重试 Agent 查询操作状态并遵循重试契约
轮换 人工替换密钥 Agent 请求轮换,但无法看到上游凭据
移交 账户一开始就属于个人 用户通过明确流程认领或接管所有权
删除 通过控制台操作 使用具备依赖和恢复规则的授权删除操作

Agent-native 基础设施指南将同样的区分应用于完整平台。

分离控制面与数据面

控制面负责创建资源、更改配置、报告状态、处理所有权和执行计费规则。数据面负责响应应用请求,两者应使用不同的凭据。

Coding agent 在构建应用时可能需要管理凭据,但部署后的应用只能获得它所需的数据面访问权限。除非某项凭据明确用于公开访问,或只用于换取短期会话 token,否则浏览器 bundle 不应获得这两类凭据中的任何一种。

NIST 的零信任指南围绕主体、资源和策略做出访问决策,而不是依据网络位置。同样的原则也适用于这里:先针对请求的资源和操作授权 agent 身份,再由服务强制执行授权结果。

让资源创建过程可观察

创建调用应该返回资源 ID 和操作状态。如果后台仍在异步工作,应提供状态查询操作,并使用 ready、failed 或 deleted 等稳定的终态。

不要让 agent 根据控制台 URL 或 DNS 记录是否存在来猜测资源是否就绪。平台应该明确说明哪些部分已就绪,哪些仍在等待。

定义安全的写入行为

每个写入操作都应说明:

  • 它是否具备幂等性;
  • 哪个操作键或幂等键用于标识重试;
  • 服务端保留该键多长时间;
  • 超时后结果是已知还是未知;
  • 调用方如何取回原始结果;
  • 哪些故障可以安全重试。

Stripe 的幂等性文档是一个清晰的公开示例:保存并返回某个键首次请求的结果。你的契约可以采用不同的保留期限和参数规则,但必须同样明确。

返回能指导下一步操作的错误

Agent 需要稳定的错误码、简短消息和结构化详情。以下区分很有用:

错误 下一步操作
invalid_request 修正指定字段
not_authorized 停止操作,并申请范围更窄或不同的身份
approval_required 向用户展示需要审批的确切操作
operation_in_progress 轮询返回的操作 ID
rate_limited 等待到返回的可重试时间
quota_exceeded 停止操作,或在更改套餐或费用前询问用户
dependency_conflict 处理指定的依赖资源

HTML 错误页或笼统的 500 错误会迫使 agent 猜测。配置资源时靠猜测,容易产生重复资源并导致清理出错。

将所有权与初始配置分开

用户尚未准备创建账户时,agent 可能需要先创建一个隔离项目。这个项目仍必须设置过期时间,并提供后续人工认领路径。只有在用户明确同意后,认领流程才能扩大所有权范围,而且审批 URL 不应暴露 agent 的临时密钥。

Cohesivity 采用了这种模式。npx @cohesivity/init 会创建或复用一个有效期为 72 小时的临时租户。资源文档位于 /offerings/<name>,资源通过管理面配置,应用则使用独立的 edge 凭据。用户认领属于后续的授权步骤。

使用 coding agent 配置后端资源实用指南展示了完整流程。

在依赖资源前测试删除操作

创建一项一次性资源,中断创建后再次发起相同操作,轮换访问凭据,然后删除资源。确认依赖服务能够继续运行,或以结构化说明阻止删除。还要确认旧凭据已经失效。

下方的提示词会针对当前项目已经使用的一项资源执行同样的生命周期检查,但不会触碰提供商。