Anthropic ant CLI実践ガイド — YAML駆動でManaged Agents・Sessions・Environmentsをバージョン管理する新しいAPI開発ワークフロー

Claude APIの開発、まだcurlやPythonスクリプトで回していませんか？ 2026年4月、AnthropicがリリースしたGo製CLI「ant」は、Agent・Environment・SessionをYAMLファイルで定義し、Gitでバージョン管理できる——いわばClaude APIの「Terraform」です。本記事では、Claude Code CLIユーザーの視点から、ant CLIで日常のAPI開発ワークフローをどう変えられるかを実践コード付きで解説します。

ant CLIとは何か — Claude Code CLIとの棲み分け

Claude Code CLI = 開発支援、ant CLI = API基盤管理

ant CLIはAnthropicが公式に提供するGo製のOSSです。2026年4月8日にv1.0.0が初回リリースされ、本記事執筆時点の最新バージョンはv1.3.2（2026年4月23日）です。

よくある混同として「Claude Code CLIとは何が違うのか」という疑問がありますが、役割は明確に異なります。

• Claude Code CLI（claudeコマンド）: コードを書く・編集するための開発支援ツール
• ant CLI（antコマンド）: Managed Agents・Environment・SessionなどのAPI基盤を操作・管理するツール

つまり、Claude Code CLIが「エディタ」なら、ant CLIは「インフラ管理ツール」です。

curlやSDKスクリプトから乗り換えるメリット

従来、Managed Agentsを操作するにはcurlでbetaヘッダーを手動付与する必要がありました。

# curlの場合 — betaヘッダーを毎回手動で指定
curl -X POST https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "claude-sonnet-4-6",
    "system": "You are a code review assistant.",
    "max_tokens": 4096
  }'

# ant CLIの場合 — betaヘッダーは自動付与、typed flagsでバリデーション付き
ant beta:agents create \
  --name code-reviewer \
  --model claude-sonnet-4-6 \
  --system "You are a code review assistant." \
  --max-tokens 4096

betaヘッダーの手動管理が不要になるだけでなく、タブ補完、型バリデーション、わかりやすいエラーメッセージなど、日常の開発体験が大きく改善されます。

セットアップと初期設定

インストール

macOSではHomebrewが推奨です。

# macOS（推奨）
brew install anthropics/tap/ant

# Go 1.22+がある環境
go install github.com/anthropics/anthropic-cli/cmd/ant@latest

認証設定

# 環境変数でAPIキーを設定
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# 動作確認
ant --version
# ant version 1.3.2

# コマンド体系の確認
ant help

# Agentの一覧を取得して接続テスト
ant beta:agents list

プロキシ環境下ではHTTPS_PROXYの設定も忘れずに。また、--base-urlフラグでカスタムAPIエンドポイントを指定することも可能です。

YAML駆動のAgent定義 — Gitでバージョン管理する

agent.yamlの構造

ant CLIの真価はここにあります。Agent定義をYAMLファイルに記述し、stdinリダイレクトで読み込ませることで、宣言的にAgentを管理できます。

# agents/code-reviewer.yaml
name: code-reviewer
model: claude-sonnet-4-6
system: "@./prompts/code-review-system.md"
max_tokens: 4096
tools:
  - type: agent_toolset_20260401

@でsystem promptを外部管理

systemフィールドに@./prompts/code-review-system.mdと書くと、外部ファイルの内容がインラインで読み込まれます。これにより、prompt管理とagent定義を分離でき、promptだけを変更したPRも追跡しやすくなります。正直、この機能だけでもcurlから乗り換える価値があると感じています。

ディレクトリ構成例

claude-agents/
├── agents/
│   ├── code-reviewer.yaml
│   ├── test-generator.yaml
│   └── doc-writer.yaml
├── environments/
│   ├── staging.yaml
│   └── production.yaml
├── prompts/
│   ├── code-review-system.md
│   ├── test-gen-system.md
│   └── doc-writer-system.md
├── .github/
│   └── workflows/
│       └── deploy-agents.yaml
└── README.md

この構成をGitリポジトリとして管理すれば、PRレビューでagent設定の変更を追跡でき、誰がいつどのpromptを変更したかが一目瞭然になります。

# YAMLからAgentを作成
ant beta:agents create < agents/code-reviewer.yaml

# 定義を更新（promptの変更など）— optimistic lockingのため--versionが必須
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 3 < agents/code-reviewer.yaml

toolsの設定ポイント

toolsは配列として指定し、agent_toolset_20260401を含めることでbash, read, write, edit, glob, grep, webfetch, websearchなどの標準ツールセットがまとめて有効化されます。agent_toolset_20260401と独自のカスタムツールを併記することも可能です。

Environment・Sessionの操作と--transformによるレスポンス抽出

概念の整理

• Environment: Agentの実行環境（サンドボックス）。環境変数やリソースを定義
• Session: Environmentの上で動く実行インスタンス。1つのAgentに対して複数のSessionを同時実行可能

料金構造の注意点

Managed Agentsの料金は3層構造です:

Sessionのライフサイクル

# Session作成 — Agentとenvironmentを指定して実行開始（メッセージは別途送信）
ant beta:sessions create \
  --agent agent_011CYm1BLqPXpQRk5khsSXrs \
  --environment-id env_011CYm1BLqPXpQRk5khsSXrs \
  --title "src/配下のコードレビュー"

# 作成したSessionにメッセージを送信
ant beta:sessions:events send \
  --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
  --event '{type: user.message, content: [{type: text, text: "src/配下のコードをレビューして"}]}'

# Session状態の確認
ant beta:sessions get --session-id session_01JZCh78XvmxJjiXVy3oSi7K

# 稼働中のSession一覧
ant beta:sessions list --status running

--transformで必要なフィールドだけ取り出す

ant CLIの--transformフラグはGJSON構文に対応しており、JSONレスポンスから必要な部分だけを抽出できます。シェルスクリプトでjqを別途インストールする必要がありません。

# Sessionのイベント一覧から各eventのテキスト部分を抽出
# （list endpointではtransformは各itemに対して個別に実行される）
ant beta:sessions:events list --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
  --transform 'content.0.text'

# Agent一覧からnameだけをリスト表示（list endpointなので各itemに適用される）
ant beta:agents list --transform 'name'

# 出力フォーマットの指定も可能（auto, json, jsonl, yaml, pretty, raw, explore）
ant beta:agents list --format yaml

地味に便利なのが--formatオプションで、yamlを指定すればそのままYAMLファイルとして保存できます。デフォルトのautoはターミナル環境を判定して最適な形式で出力し、exploreを指定するとTUIブラウザでインタラクティブにレスポンスを探索できます。

実践ワークフロー — antでAgent定義→Claude Codeで実装→antでデプロイ

開発サイクルの全体像

実務では以下の3フェーズで回すのが効果的です。

1. 定義フェーズ（ant CLI）: agent.yamlでAgent定義を記述・テスト
2. 実装フェーズ（Claude Code CLI）: ツール用の実装コードを開発・デバッグ
3. デプロイフェーズ（ant CLI）: Agent・Environmentを本番環境に反映・監視

CI/CDパイプラインへの組み込み

GitHub Actionsで、agent.yamlの変更をトリガーにデプロイを自動化する例です。

# .github/workflows/deploy-agents.yaml
name: Deploy Managed Agents
on:
  push:
    branches: [main]
    paths:
      - 'agents/**'
      - 'prompts/**'
      - 'environments/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ant CLI
        run: |
          go install github.com/anthropics/anthropic-cli/cmd/ant@v1.3.2

      - name: Deploy Agents
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          for f in agents/*.yaml; do
            ant beta:agents update \
              --agent-id "$(yq '.agent_id' "$f")" \
              --version "$(yq '.version' "$f")" \
              < "$f"
          done

      - name: Notify Slack
        if: success()
        run: |
          curl -X POST "$SLACK_WEBHOOK" \
            -d '{"text":"Managed Agents deployed successfully"}'

staging/productionのEnvironmentを分けておけば、PRマージでproductionに自動反映するGitOpsパターンも構築できます。

ハマりポイントと対処法

betaヘッダーとAPIバージョンの罠

ant CLIはmanaged-agents-2026-04-01のbetaヘッダーを自動付与しますが、同じプロジェクトでPython SDKやcurlも併用している場合は、SDK側に手動でbetaヘッダーを設定する必要があります。ここを忘れると「ant CLIでは動くのにSDKからは404」という状況になりがちです。

--versionによるoptimistic locking

Agent/Environmentの更新時には--versionフラグが必須です。これは複数の開発者が同時に同じリソースを更新した際の衝突を防ぐためのoptimistic lockingで、現在のバージョン番号と一致しない場合は更新が拒否されます。本番運用では、更新前に最新バージョンを取得→--versionに指定する流れを徹底しましょう。

Sessionタイムアウトに注意

Sessionの終了し忘れは課金に直結します（idle時間は非課金ですが、明示的に終了しない限りSessionは残り続けます）。長時間タスクでは適切なtimeout設定を行い、ant beta:sessions list --status runningで定期的に稼働中のSessionを確認する運用を推奨します。

YAMLの構文エラー

ant CLIにはYAMLバリデーション専用のサブコマンドはありません（v1.3.2時点）。ant beta:agents create < ...で実際にAPIを呼んだ際のエラーメッセージから判断するか、事前にyamllintなどの汎用ツールで構文チェックしておくと安心です。

まとめ — ant CLIが変えるClaude API開発の日常

ant CLIの本質的な価値は、API操作を宣言的なYAMLファイルに落とし込み、Git管理可能にすることです。Terraformがクラウドインフラ管理を変えたように、ant CLIはAIエージェント基盤の管理を「コード化」します。

日常の開発では、Claude Code CLI（コードを書く）とant CLI（Agent基盤を管理する）の二刀流が最適解です。この2つのCLIは競合ではなく補完関係にあり、それぞれの得意領域で使い分けることで、API開発のワークフロー全体が効率化されます。

なお、Managed Agentsは現在public beta段階です。GA時にAPIの破壊的変更が入る可能性はありますが、YAML駆動のワークフロー自体は定義ファイルの修正だけで追従できるため、今のうちに組み込んでおくことをおすすめします。ant CLIは活発に開発が進んでおり（v1.0.0からわずか2週間でv1.3.2まで到達）、v1.3.0ではCMA Memoryのpublic betaや--raw-outputオプションなど、着実に機能が拡充されています。