managed-agents-onboardでManaged Agentsをant apply用ファイルにする

Claude Codeのv2.1.290で、/claude-api managed-agents-onboard というサブコマンドが加わりました。渡せる引数は2種類です。ページのURLを渡すと、そのページが説明するManaged Agentsの構成を ant apply 用のファイルに起こします。Consoleのクイックスタート名(deep-researcher など)を渡すと、同じテンプレートを ant CLIで組み立てます。

出力はSDKのコードではなく、コミットできるディレクトリです。Consoleで画面を触って作る代わりに、構成をファイルとして残したい人向けの入口になります。

2つの入力と、それぞれの行き先

changelogの記載はこの2行です。

どちらも /claude-api スキルの中で動きます。Consoleで作ってコードに持ち帰る流れはConsoleでManaged Agentsを構築する手順が扱っています。このサブコマンドはその逆向きで、先にファイルを作ってから ant apply で反映します。

動かす前に必要なもの

ant CLIは1.34.0以降が前提です。1.34.0は ant apply がvaultを扱える最初の版で、ant --version で確かめられます。入っていない、または古いときはスキルがその旨を伝え、インストールか更新を提案します。インストーラーを走らせる前には確認を取ります。

Claude Platform on AWSでは、CLIにSigV4の認証モードがありません。その環境ではこのフローを使わず、SDKで書く別ルートに進みます。

認証まわりで詰まったらant CLIの認証を先に確認してください。環境変数の ANTHROPIC_API_KEY が残っていると、プロファイルより優先されるためです。

URLを渡したとき: 5段階で進む

URLの場合、スキルは「取得 → 抽出 → 提案 → 書き出し → 適用」の順に進みます。

提案を出したターンにファイルまで書いてしまわない点が、この流れの要です。承認前に何も作られないので、構成案を読んでから進めるか止めるかを選べます。

ページの発行元で、コピーできる範囲が変わる

スキルは取得元をファーストパーティとサードパーティに分けます。無人で動くエージェントがユーザーの資格情報の届く場所に置かれるため、ページの文面をそのまま写してよいかは発行元で決めます。

サードパーティのページからは、役割・手順・使うサービス・「完了」の定義といった設計だけを読み取り、プロンプトや名前はスキルが新しく書きます。ホスト、MCPのURL、パッケージ名はファーストパーティでもサードパーティでもページを信用せず、提供元の公式サイトで確認したものだけを使います。確認できないものはファイルにも命令にも入れません。

ファーストパーティとして扱わせたいときは、サブコマンドの後ろにURLだけを置きます。

/claude-api managed-agents-onboard https://platform.claude.com/docs/en/managed-agents/quickstart

URLの後ろに語を足す、クエリ文字列を付ける、引用符で囲むといった形はサードパーティ扱いになります。ページの文中に「AIアシスタントへ」と書かれた指示があっても、データとして扱われ、ページが命じるコマンドやセットアップスクリプトは実行されません。ページに載っている agent_... や env_... のIDは別のワークスペースのものなので、コピーされません。

書き出されるファイルと、ant applyの認識ルール

1エージェントにつき1ディレクトリで、必要なものを同居させます。

agents/
  daily-brief/
    agent.md                  # frontmatterが設定、本文がシステムプロンプト
    environment.yaml
    vault.yaml                # 器だけ。秘密は入れない
    deployment-daily.yaml     # スケジュール1つにつき1ファイル
    memory_store-notes.yaml   # 実行間で状態を持つときだけ
    skills/brief-format/SKILL.md
claude-lock.json              # ant applyがルートに書く。コミットする

agent.md の形は、スキルが示す例に沿うと次のようになります(以下は例で、実行結果の出力ではありません)。

---
name: daily-brief
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - {name: web_search, enabled: false}
      - {name: web_fetch, enabled: false}
---
 
昨日のLinearの動きから、1ページの朝のブリーフを書きます。

web_search と web_fetch を既定でオフにしているのが特徴です。この2つはAnthropic側のサーバーで動くため、環境のネットワーク制限が効きません。仕事に要らないなら切り、要るときだけ allowed_domains で範囲を絞る方針です。

ファイル名が種類を決める

ant apply はファイルの種類(kind)を名前や置き場所から推論します。スキルの書き出しもこの規則に合わせてあり、外すと「黙って無視される」ファイルが出ます。

推論の優先順位そのものはant applyのkind推論にまとめています。

適用は2回に分けて走らせる

資格情報の都合で、ant apply は1回で済ませず、順番を分けます。

1. まずデプロイメント以外を適用します。ant apply --dry-run agents/daily-brief で、走査が拾うリソースが意図どおりか確かめます。続けて agent.md、environment.yaml、vault.yaml を名前で指定して適用します。vault.yaml は中身のない空の器として先に作り、資格情報は手順2で入れます。. を渡さず名指しにするのは、意図しないファイルを巻き込まないためです。
2. 次に、資格情報はユーザーが自分の端末で入れます。トークンはチャットに貼らず、ファイルにも書きません。read -rs で無表示入力し、ant beta:vaults:credentials create に渡します。
3. 最後にデプロイメントを適用し、すぐ一時停止します。デプロイメントは作った瞬間から有効になるため、適用と停止を1つのコマンドでつなぎます。

ant apply agents/daily-brief/deployment-daily.yaml &&
  DEPLOYMENT_ID=$(jq -r \
    '.resources["./agents/daily-brief/deployment-daily.yaml"].id' \
    claude-lock.json) &&
  ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"

適用後は動作確認です。ant apply はメモリストアやvaultを空のまま作り、データはアップロードしません。初期データの入れ方はセッションのシードにまとめています。動作確認はデプロイメントを一時停止したまま ant beta:deployments run で手動実行し、ant beta:deployment-runs list で出たセッションを見て、結果が妥当なら有効化に進みます。有効化はユーザーが判断します。

ant apply は端末が無いと、プランを出して止まります。反映するには --yes が要り、スキルはこれをユーザーの承認とみなして、--force と --prune は自分では付けません。

vaultの中身やデプロイメントのcron設計は、vaultの仕組みとスケジュールデプロイのcron設定が詳しく扱っています。

クイックスタート名を渡したとき

名前を渡すと、スキルはConsoleのクイックスタートと同じ順序で質問し、同じエージェントをファイルとCLIで作ります。テンプレートはスキルに同梱されており、agent.md はそのまま写されます。

使える名前は同梱のテンプレート名で決まります。deep-researcher、data-analyst、contract-tracker、field-monitor、incident-commander、sprint-retro-facilitator、structured-extractor、support-agent、support-to-eng-escalator の9つが同梱されています。

引数は小文字にし、空白と _ を - に読み替えて一致を見ます。一致しなければ名前の一覧を示して、近いものを尋ねます。記憶から「それらしい」テンプレートを作ることはありません。

質問されること

流れは「テンプレートの確認 → 環境の選択 → vaultと資格情報 → 適用 → テスト実行 → スケジュール → 組み込み」です。deep-researcher の agent.md は、ツールに agent_toolset_20260401 だけを持ち、MCPサーバーを持ちません。この場合、権限ポリシーの質問も資格情報の質問も出ず、vaultも作られません。

MCPサーバーを持つテンプレートでは、ツールを確認なしで動かすか、危険な操作だけ判断させるかを選びます。無人のスケジュール実行を伴う場合や、外部の人が書いた文面を読んで書き込みもする場合は、後者が推奨されます。既定の always_ask のままだと、無人の実行が requires_action で止まるためです。

テスト実行は、メッセージとアウトカムを1回のリクエストで送ります。実行の上限額は5.00ドルで、Consoleと同じです。

Consoleと違う点

Claude Code側で、事故を減らす設定を足す

このスキルはユーザーの承認を待ってから動きます。それでも ant apply を扱うセッションでは、取り返しのつきにくいフラグを許可の外に置いておくと安心です。権限ルールの書き方に沿った例を挙げます(例であり、必須の設定ではありません)。

{
  "permissions": {
    "deny": [
      "Bash(ant apply --prune *)",
      "Bash(ant apply --force *)"
    ]
  }
}

--prune はロックファイルにあってファイルが無いリソースを削除し、--force は外部で変わったリソースを上書きします。どちらも承認画面を挟む価値のある操作です。

CLAUDE.md には、agents/ と claude-lock.json を一緒にコミットする決まりを書いておけます。

## Managed Agents
- `agents/` と `claude-lock.json` は同じコミットに入れる
- 適用は `ant apply --dry-run` のプランを確認してから
- 資格情報は `.env` に書かない

ロックファイルを一緒に入れる理由は単純で、無いと次回の ant apply が同じリソースを新規に作り直し、重複するからです。

つまずきやすい点

• 既存のエージェントは取り込めません。ant apply が管理するのはロックファイルにあるものだけです。Consoleで作ったエージェントと同じ内容のファイルを適用すると、2つ目ができます。ConsoleのExport as codeで出したダウンロードにはロックファイルが入っているので、そちらを使えば更新になります。
• 別のワークスペースには適用しないでください。プラン冒頭の組織とワークスペースを読み上げて確かめます。違うプロファイルで走らせるのが、エージェントが「消えた」ように見える典型例です。
• ファイル名を変えると別リソースになります。名前を直したら古いリソースは残るため、--prune で消すか、名前を戻します。
• シークレットは vault.yaml に書きません。vault.yaml の中身は display_name と任意の metadata だけです。

まとめ

managed-agents-onboard は、Consoleで画面を触る代わりに、構成をレビューできるファイルとして残すための入口です。URLでは「ページの設計をどこまで写すか」を発行元で決め、クイックスタート名ではConsoleの質問順を保ちます。どちらでも、承認の前に作られるものはありません。

Consoleで試す段階と、ファイルで管理する段階を、同じテンプレートでつなげられます。