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

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

更新で何が置き換わり、何が残るのか

エージェントを更新するときに事故につながりやすいのは、フィールドの型によって「置き換え」「保持」「マージ」が分かれる点です。toolsを1つ足したつもりが配列ごと置き換わる、metadataだけは追記扱いになる、といった違いがあります。versionを付けるかどうかで、同時更新の扱いも変わります。

エージェントの作り方そのものの最短手順はClaude Managed Agentsクイックスタートにあります。ここでは作成後の運用、つまり更新・バージョン履歴・セッション単位の上書き・アーカイブを扱います。

前提

Managed AgentsのAPIリクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です。SDKを使う場合は自動で付与されるため、cURLで直接叩くときだけ意識すれば足ります。メモリストアのリクエストだけはagent-memory-2026-07-22に差し替えます。2つを同時に付けると400エラーになるので、追記ではなく置き換えです。

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

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

model・system・tools・mcp_servers・skillsの5つは、エージェントを変えずにセッション単位でも上書きできます。上書きの規則は後半の節で扱います。

次の例は、事前構築ツールセットを持つコーディング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-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の値を揃えるか、全員未設定にするかのどちらかにする必要があります。

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

検証用に一度だけ別のモデルで試したい、特定のセッションだけツールを絞りたいといった場面では、セッション作成時のagentをagent_with_overrides形式にします。idに加えて、上書きしたいフィールドだけを渡します。versionを省くと、そのエージェントの最新versionが土台になります。

curl -fsSL https://api.anthropic.com/v1/sessions \
  -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 @- <<EOF
{
  "agent": {
    "type": "agent_with_overrides",
    "id": "$AGENT_ID",
    "model": {"id": "claude-sonnet-5-5", "effort": "high"},
    "system": null
  },
  "environment_id": "$ENVIRONMENT_ID"
}
EOF

この例では、モデルを差し替えてeffortも指定し、システムプロンプトを空にしています。上書きの規則は3つです。

• フィールドを省くと、土台のversionの値を引き継ぎます。
• 値を渡すと、エージェント側の値を丸ごと置き換えます。マージはされないので、toolsの上書きにはセッションで使いたいツールを全部書きます。
• null(配列は空配列)を渡すと、そのフィールドを空にして動かせます。

modelの上書きはmodelオブジェクト全体の置き換えなので、エージェント側に設定したeffortは引き継がれません。特定のeffortで動かしたいときは、上書きのmodelオブジェクトの中にeffortを書きます。書かなければそのモデルのデフォルトで動き、モデルが対応しない水準を指定すると400エラーです。

空にできない組み合わせもあります。

• modelは空にできず、model: nullはagent_model_requiredの400エラーです。
• Skillsはreadツールを必要とするため、有効なskillsが残る状態でtoolsを空にすると400エラーです。
• 有効なtoolsにmcp_toolsetが残ったままmcp_serversを空にしても400エラーです。同じリクエストでtoolsから該当のmcp_toolsetを外します。

上書きはそのセッション限りで、エージェント本体のversionは増えません。レスポンスのagentには上書き後の設定が入りつつ、idとversionは土台のエージェントを指すので、どのエージェントから派生したセッションかを後から追えます。

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

更新リクエストは、変えたいフィールドだけを送ります。内容が変わると新しいversionが作られ、versionを付けるかどうかで同時更新の扱いが分かれます。

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を自動で埋めてリクエストしてくれます。claude-lock.jsonをコミットしておくと、次回のant applyは2つ目のエージェントを作らず、同じエージェントを更新します。

versionは指定するなら1以上です。変更前に現在のversionを読み、衝突したら再取得して再試行する流れは、次の4手順になります。

フィールドの型ごとの置き換え方は次のとおりです。

modelオブジェクトでeffortを省いたときの扱いは、モデルIDを変えるかどうかで分かれます。モデルIDを変えない更新なら、保存済みの値が残ります。モデルIDを変えて省くと、新しいモデルのデフォルトに戻ります。

省いたフィールドは保持されるので、変更したい項目だけを送れば足ります。

コーディネーターのロスターは自動で更新されません。あるエージェントを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行で同じ情報が得られます。設定変更の履歴を追いたいときや、意図しない変更が入っていないかを確認したいときに使う操作です。

セッションを作るときは、agentに{"type": "agent", "id": "...", "version": 1}のようなオブジェクトを渡すと、動かすversionを固定できます。新しいversionの展開を、既存の利用とは別に段階的に進めたいときの手段です。

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

アーカイブ(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")"

アーカイブ済みのエージェントに対する更新リクエストは拒否されます。設定を変えたいときは、新しいエージェントを作成します。

よくあるつまずき

• エージェント更新で地域ピンが消えた: modelオブジェクトを送ると、inference_geoは明示しない限りクリアされます。地域ピンを維持したまま他のフィールドだけ変えたい場合は、modelオブジェクトにinference_geoも含めて送ります。
• コーディネーターに新versionが反映されない: multiagent.agentsのロスターは自動更新されないため、配下のエージェントを更新しただけではコーディネーターは古いversionを使い続けます。コーディネーター自体を更新してロスターを書き直します。

まとめ

一度きりの検証ならセッション単位の上書き、恒久的に変えるならエージェント本体の更新、と使い分けます。本体の更新は、人が対話的に触るならversionを付けて衝突を検知し、CIのようにループ側が所有するなら省いて最後の書き込みを正にする、という分け方になります。

エージェントを実際に動かす手順はClaude Managed Agentsクイックスタートにあります。

エージェントが動くサンドボックス側の設定はManaged Agentsのクラウド環境を構築するです。Managed Agents全体の設計思想はAgent SDKのManaged Agentsの設計思想で読めます。