ant applyのkind推論とagentを初めて適用する手順

ant applyはファイルの場所からkindを決める

ant apply は、エージェント・環境・スキル・メモリストア・デプロイメント・ボールトといったClaude APIのリソースを、リポジトリ内のファイルから作成・更新するCLIコマンドです。各リソースをファイルに書き、ant apply を実行してプランを承認すれば、APIへのリクエストを自分で組み立てる必要はありません。

このコマンドの起点が「kind推論」です。ファイルに「これはagent」と毎回書かなくても、ant apply は置き場所とファイル名から種類を判定します。判定には優先順位があり、順序を知らないと意図しないkindになったり、ファイルが黙って無視されたりします。

ant apply にはCLIバージョン1.30.0以降が必要です。インストールと認証がまだなら、ant CLIのインストール方法を先に済ませてください。

kindは6種類で、ファイルの形が違う

ant apply が扱うkindは、agent・environment・memory store・deployment・skill・vaultの6種類です。skill以外は「ファイル1つがリソース1つ」で、YAML・JSON・Markdownのどれでも書けます。

Markdownで書くときは、frontmatterがそのリソースのリクエストボディになり、本文がkindごとのテキストフィールドを埋めます。agentなら system、environmentとmemory storeなら description、deploymentなら最初のメッセージです。

vaultにはテキストフィールドがありません。本文を書いたvaultのMarkdownファイルは、ant apply が受け付けません。

skillの作り方はManaged AgentsのカスタムSkillを追加する方法で扱っています。

kindはどの順序で推論されるか

ant apply がディレクトリを走査するとき、各ファイルのkindは次の3つを上から順に当てはめ、最初に一致したもので決まります。

vaultを例外にしている理由は、他のツールがシークレットのファイルを vault.yml と名付けるためです。vaultは vaults/ に置くか、type: vault を書きます。

type を書いておけば、ディレクトリ構成に関係なく意図したkindになります。

走査では黙ってスキップ、名指しでは扱いが変わる

3つのルールのどれにも合わないファイルの扱いは、コマンドの渡し方で分かれます。

最初のagentを適用する

kindの推論ルールを踏まえて、agentを1つ適用します。

ステップ1: agentをMarkdownファイルとして書く

agents/ ディレクトリの下にMarkdownファイルを作ります。frontmatterがagentの設定、本文がシステムプロンプトです。

---
name: Summarizer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---
 
You are a helpful assistant that writes concise summaries.

frontmatterに書けるフィールドはManaged Agentsのagent設定にまとめています。ファイルが agents/ 直下にあるので、type を書かなくてもagentとして推論されます。

ステップ2: ant applyでプランを確認する

保存したら、パスを指定して実行します。

ant apply agents/summarizer.md

初回は claude-lock.json がまだ無いので、新規作成のプランが出ます。対話端末では、作成予定のリソース一覧の前に、どの認証情報・ホスト・組織・ワークスペースに作るかの確認ブロックも表示されます。

First apply  ./claude-lock.json does not exist yet and will be created
 
Resources will be created with
  credentials   API key (--api-key / ANTHROPIC_API_KEY)
  host          api.anthropic.com
  organization  1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f
  workspace     wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ
 
Preview  ./claude-lock.json (new)
 
± Name                    Plan
+ ./agents/summarizer.md  create
 
Resources  + 1 to create
 
Apply these changes? (y)es / (n)o / (d)etails y

d を選ぶと、新規リソースの各フィールドの値を見てから進めます。更新のときは、フィールドごとの差分が出ます。変更を加えずに詳細なプランだけ見たいなら、--dry-run を付けます。

ステップ3: 承認して結果を確認する

y で承認すると、ant apply がリクエストを送り、作成されたリソースのIDを表示します。

Apply  ./claude-lock.json
 
± Name                    Status
+ ./agents/summarizer.md  created    agent_011CYm1BLqPXpQRk5khsSXrs
 
Resources  + 1 created
 
State written to ./claude-lock.json

claude-lock.json は、コマンドを実行したディレクトリに作られます。リポジトリのルートで実行するのが前提です。

{
  "version": 1,
  "origin": {
    "base_url": "https://api.anthropic.com",
    "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"
    }
  }
}

resources のキーはファイルのパスで、kind に推論結果が記録されます。2つのハッシュは、最後に送った内容とAPIが返した内容の指紋です。これで次の実行は、ファイルが編集されたことも、リソースがファイル外で変えられたことも検知します。

このファイルをソースと一緒にコミットすると、次回以降は手元でもCIでも、同じリソースを新規作成でなく更新として扱えます。運用ルールはant CLIでAPIリソースをスクリプトで自動化するで扱っています。

エージェントを編集したいときは、ファイルを書き換えて同じコマンドをもう一度実行します。プランはcreateでなくupdateになります。

ファイル名を変えると別リソースになる

lockファイルがパスをキーにしているため、ファイルの移動や改名は更新として扱われません。

• 新しいパスは、新規リソースとして宣言されます
• 古いパスのファイルを消しても、リソースはAPI側に残り、警告が出ます
• --prune を付けると、lockファイルにあって宣言の無いリソースが取り除かれます。agentなどはアーカイブされ、skillは削除されます

複数ファイルのプロジェクトでは、パス参照でつなぐ

agent以外のリソースも、同じ流れで書けます。ファイルには、そのkindのcreateエンドポイントに送るリクエストボディを書きます。

リソース同士はパスで参照します。APIが別リソースのIDを求める場所には、そのファイルへの相対パスを書きます。公式のプロジェクト例は次の6ファイルです。

• agents/reviewer.md: ../skills/pr-summary を skills に持つ
• agents/lead.md: ./reviewer.md を multiagent の名簿に持つ
• skills/pr-summary/SKILL.md
• environments/cloud.yaml
• memory_stores/review-notes.yaml
• deployments/nightly.md: agent・environment・memory storeをパスで指す

ディレクトリ全体は ant apply . で適用します。ant apply は依存順にリソースを作り、本物のIDを差し込みます。agentとskillの参照は、直前に適用したバージョンに固定されます。reviewer.md を編集すると、それを参照するリソースも同じ実行で更新されます。

lockファイルの管理外のリソースを指したいときは、パスの代わりにID(agent_... や skill_...)を書きます。skillの参照には、GitHubのディレクトリURLも使えます。

外部で変えられたリソースと、既存リソースの扱い

lockファイルの記録と実際のリソースが食い違うと、ant apply は止まります。プランが外部での編集・アーカイブ・削除を検知すると、This plan cannot be applied: で終わり、refusing to apply になります。上書きや再作成を承知で進めるときは --force を付けます。

Consoleや ant beta:agents create で作ったリソースは、そのままでは取り込めません。既存のagentと同じ内容のファイルを適用すると、2つ目のagentが作られます。Consoleの「Export as code」で書き出せば、lockファイル付きで手に入ります。ページのURLやクイックスタート名からファイル一式を起こす方法は、/claude-api managed-agents-onboardの解説にあります。

CIでは引数なしのant applyが新しいファイルを拾わない

CIで新しいファイルが反映されないとき、原因はkind推論ではなく、引数の渡し方にあります。

引数なしの ant apply は、lockファイルが追跡しているファイルだけを突き合わせます。端末で実行すると、追跡していないリソースファイルを一覧にして、追加するか尋ねます。

端末がないCIでは、確認に答えられないため、プランを出して次のメッセージで止まります。

cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan only

ant apply --yes だけでは、新しく足したファイルがスキップされます。マージ後の適用には、ant apply --yes . のようにディレクトリを名指しします。プルリクエストでは ant apply --dry-run . でプランをレビュアーに見せられます。ブロックされるプランでも終了コードは0です。

よくあるつまずき

kind推論は単純ですが、置き場所を誤ると想定外の結果になります。

• agentのつもりで environments/ に置いた: ディレクトリ名がファイル名より優先されるため、environmentとして扱われます。中身より先に置き場所を見ます
• サブディレクトリに入れた: ルール2が見るのは直接の親です。agents/team-a/summarizer.md のような階層は、どのkindとも一致しません

環境・memory store・deploymentの具体的な書式は、Managed Agentsのクラウド環境を構築するで確認できます。

まとめ

kindの取り違えに気づく最初の場面は、承認前のプランです。想定外のkindや、不要なcreateが並んでいないかを見てから y を押します。

プランを定期実行に組み込むなら、Managed Agentsのスケジュールデプロイをcronで定期実行するも参考になります。