ant apply Brings GitOps to Claude Agents: What Every Gateway Operator Must Track

When a team swaps a model inside a routing gateway, the decision usually lives somewhere inconvenient—a config file nobody reads, an environment variable set by hand, or institutional memory. Anthropic's ant apply, released September 3 as part of ant CLI v1.30.0, moves that decision into a Markdown file in your repository, subject to the same pull-request review as your code.

That shift is operationally significant for teams whose agents call Claude through a proxy or AI gateway.

What ant apply actually does

ant apply is a plan-and-apply command modelled on Terraform. You write each Claude API resource—agents, environments, skills, memory stores, scheduled deployments—as a file in your repository. The frontmatter holds the configuration; Markdown prose becomes the system prompt or deployment message. Running ant apply . prints a plan showing what will be created or updated, waits for approval, then writes claude-lock.json.

ant apply agents/summarizer.md

The lockfile records the real API resource ID alongside two content hashes—what was last sent and what the API returned. On the next run, any divergence between the file and the remote resource shows up as a diff in the plan. If someone updated the agent through the Claude Console rather than the file, ant apply refuses to proceed until you either reconcile or pass --force.

The model field is now a reviewed config value

This is the part gateway operators need to internalize. An agent file looks like this:

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

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

The model field controls which Claude version this agent requests. Before ant apply, changing that field meant an API call, a Console edit, or a manual ant beta:agents update. Now it means a pull request. Every model upgrade, downgrade, or test against a new version goes through review—with history.

For teams routing Claude requests through a gateway, this has a concrete consequence: the model the agent file specifies is the model the gateway will see in the incoming request. If your routing policy treats claude-opus-5 and claude-fable-5-1 differently—different cost budgets, different fallback chains, different latency SLOs—those policies now need to stay in sync with what your agents/ files declare.

Drift between the gateway's routing rules and the agent's declared model used to be invisible. After ant apply, it becomes auditable.

What claude-lock.json actually tracks

The lockfile is not just housekeeping. It maps each local file path to an API resource ID and version, plus the two content hashes:

{
  "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"
    }
  }
}

The id field is the canonical reference for starting sessions. If you write tooling that calls the Managed Agents API directly—or if your gateway constructs agent sessions—you need to read the agent ID from claude-lock.json, not hard-code it from a previous apply. An apply that creates a new resource generates a new ID; the old one is not updated.

The two hashes detect out-of-band changes. When hash and remote_hash diverge, ant apply will refuse to proceed and report the conflict. This is the same drift-detection mechanism Terraform uses for remote state. Teams that manage Claude agents across multiple engineers now have a concrete signal when someone edits an agent through a channel outside the repo.

Before and after: the operator workflow change

Before ant apply: An agent's model, system prompt, tools, and environment were configured through API calls or the Console. Capturing that state meant either maintaining separate documentation or running ant beta:agents describe and hoping the output was current. CI pipelines had no standard way to preview or validate agent changes before merge.

After ant apply:

• Agent files live in the repo under agents/, environments/, memory_stores/, deployments/, skills/
• ant apply --dry-run . in PR checks prints a plan without applying it—reviewers see exactly what will change
• ant apply --yes . on merge to main applies and updates claude-lock.json
• The lockfile is committed back; the next engineer's apply operates on the same resources
• Resources deleted from files are left in place with a warning until --prune runs—preventing accidental deletion of a live agent

The dependency resolution matters for multi-agent setups. If a coordinator agent references a reviewer agent by relative path (./reviewer.md), ant apply creates them in dependency order and fills in the real IDs. You don't manage IDs manually.

Routing and governance consequences

For teams using an AI gateway between their application code and the Claude API, ant apply changes two operational assumptions:

Model pinning is now in source control. The model field in an agent file is the ground truth for what Claude version a given agent requests. If your gateway applies routing policies or spend limits per model, those policies need to be reviewed alongside agent file changes. A reviewer that only looks at code and ignores agents/*.md files will miss the model governance decision.

Session IDs come from the lockfile. The Managed Agents API requires an agent ID to start a session. That ID is in claude-lock.json after an apply. If you build tooling that starts sessions—your gateway adapter, your CI job, your developer CLI—it needs to read the lockfile rather than rely on a constant. An apply that replaces a resource (for example, after a name change) generates a new ID.

Console edits conflict with the repo. Any out-of-band change—updating an agent through the Claude Console, running ant beta:agents update outside the repo workflow—will make ant apply refuse to proceed. Teams that want deterministic agent state need to establish the repo as the sole write path, or accept that every Console edit generates a conflict that someone has to resolve.

No equivalent at other providers

No other major model provider has shipped a Terraform-style declarative CLI for managing AI agent configurations as code. AWS Bedrock Agent management is done through CloudFormation or the Bedrock console. Vertex AI Agent Builder uses the Google Cloud Console and REST APIs. Azure AI Foundry has ARM templates, but they manage infrastructure, not prompt-level agent configuration.

ant apply is narrower than those infrastructure tools but more directly targeted at the problem of keeping agent behavior reproducible across a team. It does not manage compute or scaling—it manages configuration: which model, which system prompt, which tools. That's exactly the slice that changes the most often and has the fewest existing review disciplines.

What to do this week

If your team runs Claude agents through a routing gateway or a shared API key:

1. Audit which agents are defined by API calls or Console edits versus files. Those are candidates for migration to ant apply files.
2. Check whether your gateway's routing rules reference model IDs that match what your agents declare. Document any divergence.
3. Decide whether ant apply --yes belongs in your CI pipeline on merge, or whether you want a manual apply step with explicit approval.
4. Commit claude-lock.json to the repo and treat it as a required review artifact on PRs that touch agents/ files.

For more on routing policies and how model selection affects gateway behavior, see the TheRouter docs.