エージェントを定義する

エージェントとは、ペルソナと機能を定義する、再利用可能でバージョン管理された設定です。セッション中にClaudeがどのように振る舞うかを形作るモデル、システムプロンプト、ツール、MCPサーバー、スキルをひとまとめにします。

エージェントを再利用可能なリソースとして一度作成し、セッションを開始するたびにIDで参照します。エージェントはバージョン管理されており、多数のセッションにわたって管理しやすくなっています。

エージェント設定フィールド

エージェントを変更せずに、単一のセッションに対して model、system、tools、mcp_servers、skills をオーバーライドすることもできます。セッションごとの model オーバーライド内で設定された effort レベルは適用されません。また、オーバーライドはエージェントの model オブジェクト全体を置き換えるため、model オーバーライドを指定して作成されたセッションはモデルのデフォルトのエフォートレベルで実行されます。特定のエフォートレベルで実行するには、エージェントに effort を設定し、そのセッションでは model をオーバーライドしないでください。セッションのエージェント設定をオーバーライドするを参照してください。

エージェントを作成する

次の例では、組み込みのエージェントツールセットにアクセスできる、Claude Opus 5を使用するコーディングエージェントを定義します。このツールセットにより、エージェントはコードの記述、ファイルの読み取り、ウェブ検索などを行えます。サポートされているツールの完全なリストについては、エージェントツールリファレンスを参照してください。

例ではcurl、ant CLI、またはいずれかのSDKを使用します。まだセットアップしていない場合は、クイックスタートでインストールとクライアントのセットアップについて説明しています。

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent.

レスポンスは設定をそのまま返し、id、type、version、created_at、updated_at、archived_at フィールドを追加します。また、effort など省略した model フィールドにはデフォルト値が設定されます。version は1から始まり、更新によってエージェントが変更されるたびに増加します。

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-5",
    "effort": { "type": "high" },
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "multiagent": null,
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

ツールセットの default_config には、デフォルトの権限ポリシーである always_allow が示されています。これは、別のポリシーを設定しない限り適用されます。

推論ジオを固定する

speed や effort と同様に、inference_geo は model のオブジェクト形式を通じて設定します。model をオブジェクトとして渡し、id と並べて inference_geo を設定します。このフィールドは "us" または "global" を受け付けます。未設定の場合、各モデルリクエストは処理される時点でのワークスペースのデフォルト推論ジオに従います。ワークスペースレベルのジオ制御と料金については、データレジデンシーを参照してください。

次の例では、エージェントを米国での推論に固定し、エージェントのmodelオブジェクトからinference_geoの値を出力します。

ant apply geo-pinned-assistant.md

---
name: Geo-pinned assistant
model:
  id: claude-opus-5
  inference_geo: us
---

You are a helpful assistant.

inference_geo の固定は、エージェントの保存時、そこからセッションが作成される時、およびセッションが処理するすべてのターンで、ワークスペースの allowed_inference_geos に対して検証されます。ワークスペースの許可リストが狭められて固定が許可されなくなった場合、そのエージェントから新しいセッションを作成できなくなり、実行中のセッションはそれ以降のターンを拒否します。ワークスペースはコンプライアンスとデータレジデンシーのために固定に依存しているため、固定が免除されることはありません。

地理的な推論固定をサポートしていないモデルに inference_geo を設定すると、400エラーが返されます。サポートしているモデルについては、モデルの利用可能性を参照してください。multiagent 設定では、コーディネーターの固定とすべてのロスターメンバーの固定がすべて同じ値に設定されているか、すべて未設定である必要があります。マルチエージェントオーケストレーションを参照してください。後で固定を変更またはクリアするには、エージェントの model オブジェクトを更新します。更新のセマンティクスで説明されているように、inference_geo なしで model を指定すると固定がクリアされます。

エージェントを更新する

エージェントを更新すると、設定が変更された場合に新しいバージョンが生成されます。version フィールドは任意です。楽観的並行性制御のために指定する（不一致の場合は409が返されます）か、省略して無条件に更新を適用します（最後の書き込みが優先されます）。アーカイブ済みエージェントへの更新は拒否されます。

CLIでは、エージェントのファイルを編集して再度ant applyを実行します。applyがversionを自動的に指定します。

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent. Always write tests.

上記の例では作成レスポンスから 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 '{
    "description": "Writes and reviews code."
  }')

echo "New version: $(jq -r '.version' <<< "$updated_agent")"

更新のセマンティクス

• version は任意であり、指定する場合は1以上である必要があります。指定した場合、送信したフィールドがすでに保存されている値と一致していても、エージェントの現在のバージョンと一致しなければリクエストは409を返します。エージェントを再読み込みして再試行してください。省略した場合、更新は無条件に適用され、最新の更新が同時に行われた更新を暗黙的に置き換えます。どちらの呼び出し元にもエラーは返されません。対話的な呼び出し元には version を指定することが推奨されるデフォルトであり、省略は、チェックインされたエージェント定義を同期するCIジョブのように、ループがエージェントを所有する宣言的な適用ループに適しています。

• 省略されたフィールドは保持されます。 変更したいフィールドのみを含める必要があります。

• スカラーフィールド（model、system、name、description）は新しい値で置き換えられます。system と description は null を渡すことでクリアできます。model と name は必須であり、クリアできません。指定する model オブジェクト内では、effort が唯一の例外です。モデルの id が変更されていない場合、effort を省略すると保存されているエフォートレベルはそのまま維持されます。モデルの id を変更した場合、省略された effort は新しいモデルのデフォルトにリセットされます。その他の model フィールドはオブジェクトとともに置き換えられます。inference_geo なしで model を指定すると、エージェントの推論ジオの固定がクリアされます。

• 配列フィールド（tools、mcp_servers、skills）は新しい配列で完全に置き換えられます。配列フィールドを完全にクリアするには、null または空の配列を渡します。

• multiagent は、その agents ロスターを含めて全体として置き換えられます。クリアするには null を渡します。

• メタデータはキーレベルでマージされます。指定したキーは追加または更新されます。省略したキーは保持されます。特定のキーを削除するには、その値を null に設定します。

• 無操作の検出。 更新によって現在のバージョンに対して変更が生じない場合、新しいバージョンは作成されず、既存のバージョンが返されます。

• コーディネーターのロスターは更新されません。 multiagent.agents ロスターでこのエージェントを参照しているコーディネーターは、参照が version を省略している場合でも、コーディネーターが作成または最後に更新された時点で固定されたバージョンを保持します。新しいバージョンに委任するには、ロスターがそれを参照するようにコーディネーターを更新してください。

エージェントのライフサイクル

バージョンの一覧

完全なバージョン履歴を取得して、エージェントが時間の経過とともにどのように変化したかを追跡します。結果はページ分割されており、SDKの例ではすべてのページを自動的に取得します。

ant beta:agents:versions list --agent-id "$AGENT_ID"

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

アーカイブするとエージェントは読み取り専用になり、元に戻すことはできません。既存のセッションは引き続き実行されますが、新しいセッションはそのエージェントを参照できません。レスポンスでは archived_at にアーカイブのタイムスタンプが設定されます。

ant beta:agents archive --agent-id "$AGENT_ID"

次のステップ