Managed Agentsのagent設定 — フィールド一覧と更新・バージョン管理

Managed Agentsのエージェント(agent)は、モデル・システムプロンプト・ツールをまとめた「再利用可能でバージョン管理される設定」です。1回作成すればIDで何度も参照でき、更新のたびにversionが上がるため、どの構成でどのセッション(session)が動いていたかを後から追えます。本稿ではエージェントの設定項目(configuration fields)の一覧、更新時の細かい挙動(update semantics)、バージョン履歴の取得、アーカイブ(archive)の効果を実際のリクエスト例で確認します。

フィールドの意味と更新時の挙動

エージェントを一度作って終わりにするのではなく、運用しながら育てていくときに必要な知識をまとめます。具体的には、エージェントが持つ各フィールドの意味、フィールドの型ごとに更新がどう反映されるか、versionパラメータを付けたときと付けないときの挙動差、バージョン履歴の一覧取得、アーカイブによる読み取り専用化の4点です。エージェントの作り方自体の最短手順はClaude Managed Agentsクイックスタートで扱っているため、本稿はエージェントの中身をどう設計・運用するかに絞ります。

前提

Managed AgentsのAPIリクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です(メモリストア関連のエンドポイントのみagent-memory-2026-07-22)。SDKを使う場合は自動で付与されるため、cURLで直接叩くときだけ意識すれば足ります。

エージェントの設定項目(agent configuration fields)

エージェントが持つフィールドは次の9つです。

model・system・tools・mcp_servers・skillsはセッション単位でも上書きできます。ただしmodelをセッション単位で上書きすると、エージェント側に設定していたeffort(推論の強さ)は引き継がれず、モデルのデフォルトeffortで動く点に注意してください。特定のeffortで動かしたいなら、エージェント側にeffortを設定し、セッションではmodelを上書きしない構成にします。

次の例は、事前構築ツールセットを持つコーディングagentを作成するリクエストです。

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-opus-5",
    "system": "You are a helpful coding agent.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }')
 
AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

レスポンスは送った設定をそのまま返しつつ、id・type・version・created_at・updated_at・archived_atを追加し、省略したフィールド(effortなど)にはデフォルト値を補完します。versionは作成時に1から始まり、内容が変わる更新のたびに増えます。

effort・speed・inference_geoの指定

modelを文字列ではなくオブジェクトで渡すと、推論の強さ(effort: low/medium/high/xhigh/max)、応答速度(speed: fastなど)、推論地域(inference_geo: usまたはglobal)を追加で指定できます。inference_geoを明示しない場合は、リクエストが処理される時点のワークスペースのデフォルト地域に従います。

inference_geoを固定すると、エージェントの保存時・セッションの作成時・各ターンの実行時にワークスペースのallowed_inference_geosとの整合性が毎回検証されます。ワークスペース側の許可リストが後から狭められて固定値が対象外になると、そのエージェントから新しいセッションを作れなくなり、実行中のセッションも以降のターンを拒否します。コンプライアンスやデータレジデンシー(データ保存地域規制)のために固定しているという性質上、この検証には例外がありません。地域ピンをサポートしないモデルにinference_geoを指定すると400エラーになります。multiagent構成では、コーディネーターと配下の全agentでinference_geoの値を揃えるか、全員未設定にするかのどちらかにする必要があります。

セッションでエージェントの設定を一時的に上書きする

model・system・tools・mcp_servers・skillsの5フィールドは、エージェント本体を変更せずにセッション作成時だけ上書きできます。検証用に一度だけ違うモデルで試したい、特定のセッションだけツールを絞りたい、といった場面で使う仕組みです。上書きはそのセッション限りで、エージェントのversionには影響しません。前述のとおりmodelを上書きするとeffortはエージェント側の設定を引き継がないため、effortを固定したい運用ではこの上書きを避け、代わりに別のエージェントを用意するほうが安全です。

エージェントを更新する — 更新時の挙動(update semantics)

更新はversionを指定する方式と省略する方式の2通りがあり、用途によって使い分けます。

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d "{\"version\": $AGENT_VERSION, \"system\": \"You are a helpful coding agent. Always write tests.\"}")
 
echo "New version: $(jq -r '.version' <<< "$updated_agent")"

ant CLIを使う場合は、ローカルのエージェント定義ファイルを編集してant applyを再実行するだけです。CLIが現在のversionを自動で埋めてリクエストしてくれます。

更新時の挙動は、フィールドの型ごとに次のように整理できます。

• versionは任意で、指定するなら1以上。指定した値が現在のエージェントのversionと一致しないと409エラーになります(送った内容が既存の値と同じでも一致しない限り409になる点に注意)。省略すると無条件で更新が適用され、同時に更新した別のリクエストは通知なく上書きされます(last write wins)。対話的な操作ではversionを指定するのが基本、チェックイン済みの定義を同期させるCIジョブのような宣言的applyループでは省略が向いています。
• 省略したフィールドは保持されます。変更したいフィールドだけを送れば十分です。
• スカラー値(model・system・name・description)は新しい値に置き換わります。systemとdescriptionはnullを渡すとクリアできますが、modelとnameは必須項目なのでクリアできません。modelオブジェクト内のeffortだけは例外で、モデルIDを変えない更新ならeffortを省略しても既存の値が保持されます。モデルID自体を変えた場合、effortを省略すると新しいモデルのデフォルトにリセットされます。inference_geoを含まないmodelオブジェクトを送ると、既存の地域ピンはクリアされます。
• 配列フィールド(tools・mcp_servers・skills)は新しい配列でまるごと置き換わります。空にしたい場合はnullか空配列を渡します。
• multiagentはロスター(agents配列)ごと丸ごと置き換わります。クリアするにはnullを渡します。
• metadataだけはキー単位でマージされます。渡したキーは追加・更新され、渡さなかったキーは残ります。特定のキーを削除したい場合はそのキーの値をnullにします。
• no-op検知: 更新内容が現在のversionと変わらない場合、新しいversionは作られず、既存のversionがそのまま返ります。
• コーディネーターのロスターは自動更新されません。あるエージェントをmultiagent.agentsに含むコーディネーターは、参照時にversionを省略していても、コーディネーター作成・更新時点のversionを固定で保持し続けます。新しいversionに委譲させたい場合は、コーディネーター側を明示的に更新してロスターを差し替える必要があります。

バージョン履歴を確認する

エージェントがどう変化してきたかは、versionsエンドポイントで一覧取得できます。結果はページネーションされており、SDKの例では自動で全ページを取得します。

curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

ant CLIならant beta:agents:versions list --agent-id "$AGENT_ID"の1行で同じ情報が得られます。設定変更の履歴を追いたいときや、意図しない変更が入っていないかを確認したいときに使う操作です。

エージェントをアーカイブする

アーカイブ(archive)はエージェントを読み取り専用にする操作で、取り消せません。既存のセッションはそのまま動き続けますが、新しいセッションをそのエージェントから作ることはできなくなります。レスポンスのarchived_atにアーカイブした時刻が入ります。

archived=$(curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")
 
echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"

アーカイブ済みのエージェントに対する更新リクエストは拒否されます。役目を終えたエージェントを消したいだけなら、削除ではなくアーカイブが正しい操作です。既存セッションの継続性を保ったまま、新規作成だけを止められます。

エージェントのライフサイクル早見表

よくあるつまずき

• versionを指定したのに409になる: 送った内容が現在の値と同じでも、versionの数値が一致していなければ409が返ります。最新のエージェントを再取得してから更新をやり直します。
• modelを上書きしたらeffortが消えた: modelオブジェクトごと送信すると、モデルIDが変わらない限りeffortは保持されますが、inference_geoは明示しない限りクリアされます。地域ピンを維持したまま他のフィールドだけ変えたい場合は、modelオブジェクトにinference_geoも含めて送りましょう。
• コーディネーターに新versionが反映されない: multiagent.agentsのロスターは自動更新されないため、配下のエージェントを更新しただけではコーディネーターは古いversionを使い続けます。コーディネーター自体を更新してロスターを書き直します。
• アーカイブしたエージェントを直そうとする: アーカイブ後の更新はすべて拒否されます。設定を直したい場合は新しいエージェントを作り直します。
• セッション単位の上書きとエージェント本体の更新を混同する: セッションのmodel上書きはそのセッションだけの一時的な変更で、エージェントのversionは増えません。恒久的に変えたいならエージェント自体の更新が必要です。

まとめ

Managed Agentsのエージェントは、フィールドごとに更新時の挙動が異なる点を理解しておくと事故を防げます。versionを指定する運用と省略する運用のどちらを選ぶかはチームの体制次第ですが、配列フィールドが丸ごと置換される点とmetadataだけがマージされる点は特に見落としやすいポイントです。エージェントを実際に動かす手順はClaude Managed Agentsクイックスタート、エージェントが動くサンドボックス側の設定はManaged Agentsのクラウド環境を構築するを参照してください。Managed Agents全体の設計思想はAgent SDKのManaged Agentsの設計思想にまとめています。