ant apply 把 Claude Agent 纳入 GitOps：Gateway 运营者需要跟踪什么

一个团队在路由 gateway 里换一个模型，这个决定通常存在某个没人读的配置文件里，或者一个手动设置的环境变量里，或者只在某人的脑子里。Anthropic 在 9 月 3 日随 ant CLI v1.30.0 发布的 ant apply，把这个决定移进了仓库里的 Markdown 文件，走和代码一样的 pull request 审查流程。

对于通过代理或 AI gateway 调用 Claude 的团队，这个变化在运营层面影响相当具体。

ant apply 做什么

ant apply 是一个 plan-and-apply 命令，设计上参考了 Terraform。你把每个 Claude API 资源，包括 agent、环境、技能、记忆存储和定时部署，写成仓库里的文件。frontmatter 放配置参数，Markdown 正文变成系统提示或部署消息。运行 ant apply . 会打印一个 plan，等你确认，然后写入 claude-lock.json。

ant apply agents/summarizer.md

锁文件记录了真实的 API 资源 ID 和两个内容哈希，分别代表上次发送的内容和 API 返回的内容。下次运行时，文件和远端资源之间的任何差异都会以 diff 的形式出现在 plan 里。如果有人通过 Claude Console 修改了 agent 而没有改文件，ant apply 会拒绝执行，直到你把两边对齐或者传入 --force。

model 字段现在是一个受审查的配置值

这是 gateway 运营者需要记住的部分。一个 agent 文件的结构如下。

---
name: Code reviewer
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You review pull requests for correctness, security, and readability.

model 字段决定这个 agent 请求哪个 Claude 版本。在 ant apply 之前，修改这个字段意味着一次 API 调用、一次 Console 编辑或者手动运行 ant beta:agents update。现在它意味着一个 pull request，有历史记录，有审查。

对于通过 gateway 路由 Claude 请求的团队，这带来一个具体后果。agent 文件里声明的模型，就是 gateway 会在入站请求里看到的模型。如果你的路由策略对 claude-opus-5 和 claude-fable-5-1 有不同处理，比如不同的费用预算、不同的 fallback 链、不同的延迟 SLO，那这些策略现在需要和 agents/ 文件里的声明保持同步。

以前 gateway 路由规则和 agent 声明模型之间的漂移是不可见的，现在变成了可以审计的。

claude-lock.json 到底记录了什么

锁文件不只是簿记，它把每个本地文件路径映射到 API 资源 ID、版本以及两个内容哈希，格式如下。

{
  "version": 1,
  "origin": {
    "organization_id": "1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f",
    "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  },
  "resources": {
    "./agents/summarizer.md": {
      "kind": "agent",
      "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "version": "1",
      "hash": "d23251c8d99b3613a64f3f8d87f5fad4",
      "remote_hash": "1b771bee5bdbf600a5ad972fdac32d94"
    }
  }
}

id 字段是启动 session 的权威引用。如果你有工具直接调用 Managed Agents API，或者你的 gateway 构建 agent session，需要从 claude-lock.json 里读 agent ID，而不是把它硬编码进代码。每次 apply 创建新资源都会生成新 ID，旧 ID 不会自动更新。

两个哈希检测带外变更。当 hash 和 remote_hash 不一致时，ant apply 会拒绝执行并报告冲突。这和 Terraform 检测远端状态漂移的机制相同。多人维护 Claude agent 的团队，现在有了一个具体的信号，可以知道有人通过仓库工作流之外的渠道修改了 agent。

操作流程变化：前后对比

ant apply 之前的做法

agent 的模型、系统提示、工具和环境通过 API 调用或 Console 配置。记录当前状态要么靠额外维护的文档，要么靠运行 ant beta:agents describe 然后希望输出是最新的。CI 流水线没有标准方式在合并前预览或验证 agent 变更。

ant apply 之后的做法

• agent 文件存放在仓库的 agents/、environments/、memory_stores/、deployments/、skills/ 目录下
• PR 检查里运行 ant apply --dry-run . 打印 plan 但不执行，审查者能看到具体会改什么
• 合并到 main 时运行 ant apply --yes .，执行并更新 claude-lock.json
• 锁文件提交回仓库，下一个工程师的 apply 操作的是同一批资源
• 从文件里删掉的资源不会立刻删除，而是保留并警告，直到运行 --prune，防止误删线上 agent

对于多 agent 场景，依赖解析很关键。如果一个协调 agent 用相对路径引用另一个 agent，ant apply 会按依赖顺序创建它们并填入真实 ID，不需要手动管理 ID。

对路由和治理的影响

对于在应用代码和 Claude API 之间使用 AI gateway 的团队，ant apply 改变了两个运营假设。

模型固定现在在源码控制里。 agent 文件里的 model 字段是某个 agent 请求哪个 Claude 版本的唯一依据。如果你的 gateway 按模型应用路由策略或费用限制，这些策略需要和 agent 文件变更一起被审查。只看代码不看 agents/*.md 文件的审查者，会漏掉模型治理决策。

Session ID 来自锁文件。 Managed Agents API 需要 agent ID 才能启动 session，这个 ID 在 apply 之后存在 claude-lock.json 里。如果你有工具启动 session，比如 gateway 适配层、CI 任务、开发者 CLI，需要从锁文件里读，不能依赖硬编码的常量。名称变更导致资源被替换时会生成新 ID。

Console 里的修改会和仓库产生冲突。 任何带外变更，通过 Claude Console 更新 agent，或在仓库工作流之外运行 ant beta:agents update，都会让 ant apply 拒绝执行。想要确定性 agent 状态的团队，要么把仓库建立为唯一写入路径，要么接受每次 Console 修改都会产生需要有人解决的冲突。

其他提供商没有等价工具

目前没有其他主流模型提供商发布过类似 Terraform 的声明式 CLI 来管理 AI agent 配置。AWS Bedrock Agent 管理通过 CloudFormation 或 Bedrock Console 完成。Vertex AI Agent Builder 使用 Google Cloud Console 和 REST API。Azure AI Foundry 有 ARM 模板，但管理的是基础设施，不是提示层的 agent 配置。

ant apply 比这些基础设施工具的范围更窄，但更直接地解决了 agent 行为在团队间可复现的问题。它不管理算力或扩缩容，管理的是配置，即哪个模型、哪个系统提示、哪些工具。这正是变化最频繁、又最缺乏现有审查规范的那一层。

本周可以做的事

如果你的团队通过路由 gateway 或共享 API key 运行 Claude agent，可以这周做这几件事。

1. 梳理哪些 agent 是通过 API 调用或 Console 编辑定义的，这些是迁移到 ant apply 文件的候选对象。
2. 检查 gateway 的路由规则里引用的模型 ID 是否和 agent 文件里声明的一致，记录任何偏差。
3. 决定 ant apply --yes 是放进合并到 main 的 CI 流水线，还是保留为需要明确审批的手动步骤。
4. 把 claude-lock.json 提交到仓库，并把它作为触及 agents/ 文件的 PR 必须审查的产物。

关于路由策略以及模型选择如何影响 gateway 行为，参见 TheRouter 文档。