ant CLIでAPIリソースをスクリプトで自動化する — シェルパイプラインとClaude Codeからの呼び出し
ant CLIでエージェント設定をファイル管理し、コマンド出力をパイプでつなぎ、Claude Codeやcurlからも呼び出す実践手順を解説します。
ant CLIでAPIリソースを操作する前に押さえること
ant はClaude APIをターミナルから呼び出す公式CLIです。curl と違い、リクエストボディを手書きのJSONではなく型付きフラグやYAMLから組み立て、--transform で応答フィールドを抜き出せます。jq のような別ツールを足す必要がありません。
インストールはmacOSならHomebrew、Linux/WSLならリリースバイナリのダウンロード、ソースからならGoのビルドで済みます。
brew install anthropics/tap/antインストール後は ant auth login でブラウザ経由のOAuthを実行し、認証情報をローカルに保存します。APIキーを自分で発行・管理する必要はありません。
ant auth login
ant auth statusant auth status は現在ログイン中の組織とワークスペースを表示します。ANTHROPIC_API_KEY と ANTHROPIC_AUTH_TOKEN が設定されていると、ログイン情報より優先されます。気づかないうちに別の組織へリクエストが飛ぶため、CLIログイン前提のスクリプトではこの2つの環境変数を空にしておきます。
コマンドの並びは ant <リソース>[:<サブリソース>] <アクション> [フラグ] です。エージェント・セッション・環境のようなベータ機能は beta: 接頭辞を持ち、そのリソースに必要な anthropic-beta ヘッダーを自動で付けます。
ant models list
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...複数のワークスペースを行き来してスクリプトを実行するなら、--profile で名前付きプロファイルを指定します(ANTHROPIC_PROFILE 環境変数と同じ効果)。APIキーが複数ワークスペースへアクセスできる場合は --workspace-id で送信先を明示します。この2つのフラグをスクリプトの引数として外出ししておくと、同じスクリプトを別の組織・ワークスペースへ流用しやすくなります。
エージェント設定をファイルで宣言し、ant applyでコード管理する
ant apply はエージェント・環境・スキル・メモリーストア・デプロイメントをファイルから作成・更新するコマンドです。設定をリポジトリに置き、コードと同じレビューを通せます。
ant apply agents/summarizer.mdagents/ ディレクトリ配下のMarkdownは、frontmatterがエージェントの設定、本文がシステムプロンプトとして扱われます。ファイルの置き場所からリソースの種類を自動判定する仕組みで、判定順は①ファイル内の type フィールド②置かれているディレクトリ名(agents/ environments/ memory_stores/ deployments/)③ファイル名の接頭辞、の3段階です。
初回実行では claude-lock.json が作られます。作成したリソースのIDと、それが属する組織・ワークスペースを記録するロックファイルで、これをコミットしておくことで次回以降の実行が同じリソースを更新します。コミットしないと、再実行のたびに同名のリソースが増えていきます。
ファイルを編集して ant apply を再実行すると、プランは作成でなく更新として表示されます。コンソール側で編集・アーカイブ・削除されたリソースに対して実行すると refusing to apply で止まり、上書きするには --force が必要です。--dry-run は実際の変更を加えずプランだけを表示するので、レビュー用途に向きます。
複数リソースを1つのプロジェクトとしてまとめて宣言する
単体のエージェントだけでなく、環境・メモリーストア・デプロイメント・スキルも同じ仕組みでファイル管理できます。環境は environments/ 配下のYAML、メモリーストアは memory_stores/ 配下のYAML、デプロイメントは deployments/ 配下のMarkdown(frontmatterがリクエストボディ、本文が起動メッセージ)、スキルは SKILL.md を持つディレクトリという対応です。
ファイル同士は相対パスで参照し合います。エージェントのfrontmatterに skills: [../skills/pr-summary] と書けば、ant apply はスキルを先に作成してから、そのIDをエージェントの skills フィールドへ自動で埋め込みます。デプロイメントの agent フィールドに ../agents/reviewer.md と書けば、対応するエージェントのIDとバージョンが {type: agent, id, version} の形で送信されます。
ant apply .依存関係の順序(スキル→エージェント→環境・メモリーストア→デプロイメント)は ant apply 側が解決するため、ファイルを書く順序を気にする必要はありません。GitHubのURL(https://github.com/<owner>/<repo>/tree/<branch>/<dir>)をスキル参照に使うこともでき、その場合は解決したコミットにピン留めされ、--upgrade を付けたときだけ再解決されます。
コマンドの出力を次のコマンドへつなぐ
--transform id --raw-output を一覧系のコマンドに付けると、IDだけが1行1件で出力されます。JSONの引用符が付かないので、head や xargs にそのまま渡せます。
FIRST_AGENT=$(ant beta:agents list --transform id --raw-output | head -1)
ant beta:agents:versions list \
--agent-id "$FIRST_AGENT" \
--transform "{version,created_at}" --format jsonl一覧コマンドは自動でページネーションを処理し、--format jsonl を付けると1件ごとに1行のJSONで出力されるため、grep や --transform によるフィルタとパイプで素直につながります。エラー応答にも同じ仕組みが使えます。--transform-error と --format-error はエラーレスポンスに対して --transform --format と同じ絞り込みを適用するフラグです。--raw-output はエラーには効かないため、引用符なしで文字列を取りたいときは --format-error yaml を使います。
ant beta:agents retrieve --agent-id bogus \
--transform-error error.message --format-error yaml 2>&1このコマンドは 404 Not Found と Agent not found. をエラーメッセージとして返し、スクリプト側でリトライ判定やアラート送信の分岐に使えます。想定と違う応答が返ってきてこの絞り込みだけでは原因がつかめないときは、--debug を先頭に足すとHTTPリクエストとレスポンスの全体(ヘッダー含む、APIキーは自動でマスク)がstderrに出力され、送っているヘッダーやボディが期待通りかをその場で確認できます。
Claude Codeからant CLIを呼び出す
Claude Codeは ant CLIをインストールして認証済みであれば、追加の連携コードなしでそのまま利用できます。Claude Codeが ant コマンドをシェル経由で実行し、構造化された出力を解析して結果をもとに応答を組み立てる仕組みです。
たとえば次のような指示をそのまま渡せます。
- 「直近のエージェントセッションを一覧にして、エラーになったものを要約して」
- 「
./reports配下のPDFを全部Files APIへアップロードして、できたIDを表示して」 - 「セッション
session_01...のイベントを取得して、どこで詰まったか教えて」
Claude CodeがAPIリソースを直接操作できるという点は、Agent SDKでエージェントをプログラムから構築する話とは別軸です。SDKでプログラムに組み込む構成を検討している場合は、Agent SDKのManaged Agentsの設計思想でセッション・ハーネス・サンドボックスの分離を先に押さえておくと、CLIとSDKのどちらで自動化するかを判断しやすくなります。
シェルスクリプトのcurl呼び出しにCLIの認証情報を使う
curl など別のHTTPクライアントを使うスクリプトでも、静的なAPIキーの代わりに ant auth login が保存した認証情報を使えます。ant auth print-credentials --access-token は、有効期限が近ければ自動で更新したうえでアクセストークンを表示するコマンドです。
curl https://api.anthropic.com/v1/messages \
-H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 256,
"messages": [{"role": "user", "content": "hi"}]
}'OAuthのアクセストークンは Authorization ヘッダーにBearerトークンとして入れます。x-api-key ヘッダーは静的なAPIキー専用なので、CLIログインの認証情報とは混在させません。
CIでant applyを回すときに踏みやすい落とし穴
CIでの運用でつまずきやすい点を5つにまとめます。
- デフォルトブランチでは
--yes必須:ant apply --yes .をマージ後に実行します。引数なしのant apply --yesはロックファイルが既に追跡しているファイルだけを対象にし、新規追加分をスキップします - プルリクエストでは
--dry-runを使う:ant apply --dry-run .はプランを表示するだけで実際には変更せず、ブロックされるプランでも終了コード0を返します。レビュー用の情報表示に向きます - ロックファイルは必ずコミットする: applyが途中で失敗しても、それまでに作成された分はロックファイルに記録されるので、失敗時も更新後のファイルをコミットします
- applyの同時実行を避ける: ロックファイル自体にはロック機構が無いため、同時に複数のapplyジョブを走らせません
- APIキーの直書きよりWorkload Identity Federationを使う:
ant applyはclaude-lock.jsonに記録された組織・ワークスペースと一致しない認証情報を拒否するため、Workload Identity Federationで認証したほうが、キー漏洩時の影響範囲を絞り込めます
GitHub ActionsでClaude Code自体を動かす構成に慣れている場合、認証まわりの考え方はClaude CodeをGitHub Actionsに組み込むで扱っているheadless実行の設計と共通する部分が多く、比較しながら読むと理解が早まります。
リクエストボディの3つの渡し方を使い分ける
ant へのリクエストボディは、データの形によって渡し方を変えます。
| 渡し方 | 向くデータ | 例 |
|---|---|---|
| フラグ | 向くデータスカラー値・短い構造体 | 例--title "Summarization task" |
| 標準入力(YAML/JSON) | 向くデータネストした本体・複数フィールド | 例echo '{"description": "...", "version": 1}' | ant beta:agents update --agent-id "$ID" |
@file 参照 | 向くデータファイルの中身をそのまま1フィールドへ | 例--system @./prompts/researcher.txt |
標準入力から渡したフィールドとフラグで指定したフィールドが重なる場合は、フラグが優先されます。ヒアドキュメントも同じ扱いなので、複数行のYAMLを渡すときに便利です。@ 付きのパスはファイル内容をそのまま文字列フィールドへ埋め込み、バイナリファイルは自動でbase64エンコードされます。プレーンテキストとして送りたいときは @file://、強制的にbase64にしたいときは @data:// を使います。
まとめ
ant CLIはエージェント・セッション・環境をファイルとコマンドの組み合わせで扱えるようにする道具です。ant apply でリソースをコード化し、--transform と --raw-output でコマンドの出力を次のコマンドへ渡し、Claude Codeからは連携コードなしでそのまま呼び出せます。CIに組み込むときは --yes と --dry-run の使い分け、ロックファイルのコミット、同時実行の回避という3点を押さえておくと、初回のつまずきを避けられます。