ant applyのkind推論とagentを初めて適用する手順
ant applyはファイルの置き場所からagentやenvironmentなどのkindを自動推論します。最初のagentファイルを書いて適用し、承認までの流れを確認します。
ant applyはファイルの場所からkindを決める
ant apply はエージェント・環境・スキル・メモリストア・デプロイメントといったClaude APIのリソースを、リポジトリ内のファイルから作成・更新するCLIコマンドです。各リソースをファイルに記述し、ant apply を実行してプランを承認するだけで、APIへのリクエストを自分で組み立てる必要がありません。
このコマンドの起点になるのが「kind推論」です。ファイルに何のリソースかを毎回書かなくても、ant apply は置き場所やファイル名からagentなのかenvironmentなのかを自動で判定します。判定の優先順位は3段階あり、順序を知らないと意図しないkindで作成されることがあります。本記事ではその推論ルールと、最初のagentを適用するまでの手順を確認します。
ant apply にはCLIバージョン1.30.0以降が必要です。インストールと認証がまだの場合はant CLIのインストール方法を先に済ませてください。
推論対象になる5つのkind
ant apply が扱うkindは、agent・environment・memory store・deployment・skillの5種類です。kind推論のルールを理解する前に、それぞれが何のファイルなのかを押さえておきます。
- agent:
agents/配下のMarkdownファイル。frontmatterがエージェントの設定、本文がシステムプロンプトになります - environment:
environments/配下のYAMLファイル。エージェントを実行するクラウドコンテナの設定です - memory store:
memory_stores/配下のYAMLファイル。セッションをまたいで参照される記憶領域です - deployment:
deployments/配下のMarkdownファイル。frontmatterがスケジュール実行の設定、本文が最初のメッセージになります - skill: ルートに
SKILL.mdを持つディレクトリ。慣例的にskills/配下に置き、ディレクトリ単位で1つのリソースとしてアップロードします
agent・environment・memory store・deploymentの4つはYAML・JSON・Markdownのいずれでも書けます。Markdownで書く場合、frontmatterがそのリソースのリクエストボディ、本文がkindごとのテキストフィールド(agentならsystem、environmentやmemory storeならdescription、deploymentなら最初のメッセージ)を埋めます。skillだけはディレクトリ構造が特殊で、この5分類の中で唯一「ファイル1つ」ではなく「ディレクトリ1つ」が単位です。具体的な作成手順はManaged AgentsのカスタムSkillを追加する方法で扱っています。
kindはどの順序で推論されるか
ant apply がディレクトリを走査するとき、各ファイルのkindは次の3つを上から順に確認し、最初に一致したもので決まります。
- ファイル冒頭の
typeフィールド(明示指定は常に最優先) - ファイルが直接置かれているディレクトリ名(
agents/environments/memory_stores/deployments/) - kind名で始まるファイル名(例:
environment_staging.md)
いずれにも一致しないファイルはスキップされます。READMEやCI設定ファイルが誤ってリソース扱いされないのはこのためです。ただし、コマンドラインで名前を指定した場合だけ挙動が変わります。この3つのルールに一致しないMarkdownファイルは既定でagentとして扱われ、一致しないYAMLやJSONファイルはエラーになります。
置き場所ごとの判定結果を整理すると、次のようになります。
| ファイルの配置 | 推論されるkind | 判定の根拠 |
|---|---|---|
agents/summarizer.md(typeフィールドなし) | 推論されるkindagent | 判定の根拠ディレクトリ名から判定(ルール2) |
ファイル冒頭に type: environment を明記 | 推論されるkindenvironment | 判定の根拠明示フィールドが最優先(ルール1) |
ディレクトリ外の environment_staging.md | 推論されるkindenvironment | 判定の根拠ファイル名の接頭辞から判定(ルール3) |
README.md やCI設定ファイル | 推論されるkind判定されない(スキップ) | 判定の根拠3ルールいずれにも不一致 |
| コマンドラインで名指ししたMarkdownファイル(3ルール不一致) | 推論されるkindagent(既定) | 判定の根拠名前付きMarkdownの既定値 |
| コマンドラインで名指ししたYAML/JSONファイル(3ルール不一致) | 推論されるkindエラー | 判定の根拠既定値が無いため失敗する |
agents/ environments/ memory_stores/ deployments/ の4つのディレクトリ名がルール2の対象です。skillだけはディレクトリ構造が異なり、SKILL.md を持つディレクトリ単位でひとまとめにアップロードする点は前の節で触れたとおりです。3つのルールは上から順に1つでも一致した時点で確定し、後続のルールは評価されません。type フィールドさえ書いておけば、ファイルをどのディレクトリに置いても意図したkindになります。
最初のagentを適用する
kindの推論ルールを踏まえて、実際にagentを1つ適用してみます。手順は3ステップです。
ステップ1: agentをMarkdownファイルとして書く
agents/ ディレクトリの下にMarkdownファイルを作成します。frontmatterがagentの設定、本文がシステムプロンプトになります。
---
name: Summarizer
model: claude-opus-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 を実行します。
ant apply agents/summarizer.md初回実行時は claude-lock.json がまだ存在しないため、これから新規作成するというプランが表示されます。対話端末では認証情報・ホスト・組織・ワークスペースの確認に続けて、作成予定のリソース一覧が出力されます。この確認ブロックは、どのAPIキーでどの組織・ワークスペースにリソースを作ろうとしているかを実行のたびに可視化する役割を持ちます。複数のワークスペースを行き来する開発では、意図しない環境にagentを作ってしまう事故をここで防げます。
First apply ./claude-lock.json does not exist yet and will be created
Preview ./claude-lock.json (new)
± Name Plan
+ ./agents/summarizer.md create
Resources + 1 to create
Apply these changes? (y)es / (n)o / (d)etails yd を選ぶと、作成される各フィールドの値を確認してから進められます。
ステップ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このagent IDと今回のリクエスト・応答のハッシュ値は claude-lock.json に書き込まれます。このファイルをコミットすることで、次回の実行が同じリソースを新規作成でなく更新として扱えるようになります。lockファイルの運用ルールとコミットの意味はant CLIでAPIリソースをスクリプトで自動化するで扱っています。
エージェントを編集したいときは、ファイルを書き換えて同じコマンドをもう一度実行するだけです。プランはcreateではなくupdateとして表示されます。この時もkindの推論結果は変わりません。ファイルを agents/ 配下から動かさない限り、ant apply は同じagentへの更新だと認識し続けます。
よくあるつまずき
kind推論は単純なルールですが、置き場所を誤ると想定外の結果になります。
- agentのつもりが
environments/に置いてしまう: ディレクトリ名が優先されるため、中身がagentの設定でもenvironmentとして扱われます。ファイルの中身ではなく置き場所を先に確認します - サブディレクトリに配置している: ルール2が見るのは「ファイルが直接置かれているディレクトリ」です。
agents/team-a/summarizer.mdのように1階層深いと、直接の親ディレクトリ名(team-a)がkindの4種類のいずれとも一致せず、推論に失敗します - YAMLファイルをコマンドラインで直接指定した: 3ルールいずれにも一致しないYAML/JSONファイルはエラーになります。Markdownファイルのような既定値(agent扱い)はありません
- プロジェクト全体を一括適用したのに一部が無視される: READMEやCI設定など、3ルールに一致しないファイルは黙ってスキップされます。エラーではないため、想定したリソースが作成されていないときはファイル名とディレクトリを見直します
- skillだけ他のkindと同じ感覚で置いてしまう: agent・environment・memory store・deploymentは「ファイル1つ = リソース1つ」ですが、skillは「ディレクトリ1つ = リソース1つ」です。
skills/pr-summary/SKILL.mdのようにルートへSKILL.mdを置き忘れると、ディレクトリごと推論の対象外になります
エージェント以外のリソース(environment・memory store・deployment)をファイルとして書く具体的な形式は、Managed Agentsのクラウド環境を構築するで確認できます。kindの取り違えに気づくタイミングは、たいてい ant apply のプラン表示を見たときです。想定と違うkindや不要なcreateが出ていないか、承認前に必ず目を通します。
まとめ
ant apply は type フィールド・ディレクトリ名・ファイル名接頭辞の3段階でkindを推論し、agents/ environments/ memory_stores/ deployments/ に置くだけでファイルの種類を意識せずに運用できます。最初のagentを適用する流れは、Markdownファイルを書く、ant apply でプランを確認する、承認して claude-lock.json を受け取る、の3ステップです。
複数のリソースをまとめて管理するプロジェクト構成や、--dry-run によるプラン確認、既存リソースを壊さないための refusing to apply の挙動といった運用面は、ant CLIでAPIリソースをスクリプトで自動化するにまとまっています。CIでのスケジュール実行を組み込む場合はManaged Agentsのスケジュールデプロイをcronで定期実行するも参考になります。kind推論の仕組みさえ把握しておけば、agent以外のリソースを増やしていくときもディレクトリの置き方に迷わずに済みます。