エージェントを定義する

エージェントは、ペルソナと機能を定義する再利用可能なバージョン管理された設定です。セッション中の Claude の動作を形成するモデル、システムプロンプト、ツール、MCP サーバー、およびスキルをまとめたものです。

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

すべての Managed Agents API リクエストには managed-agents-2026-04-01 ベータヘッダーが必要です。SDK はベータヘッダーを自動的に設定します。

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

フィールド	説明
`name`	必須。エージェントの人間が読める名前。
`model`	必須。エージェントを動かす Claude モデル。Claude 4.5 以降のすべてのモデルがサポートされています。
`system`	エージェントの動作とペルソナを定義するシステムプロンプト。システムプロンプトは、実行する作業を記述するユーザーメッセージとは区別されます。
`tools`	エージェントが使用できるツール。事前構築済みエージェントツール、MCP ツール、およびカスタムツールを組み合わせたもの。
`mcp_servers`	標準化されたサードパーティ機能を提供する MCP サーバー。
`skills`	プログレッシブディスクロージャーによってドメイン固有のコンテキストを提供するスキル。
`callable_agents`	このエージェントがマルチエージェントオーケストレーションのために呼び出せる他のエージェント。これはリサーチプレビュー機能です。試すにはアクセスをリクエストしてください。
`description`	エージェントが何をするかの説明。
`metadata`	独自のトラッキング用の任意のキーと値のペア。

エージェントを作成する

次の例では、事前構築済みエージェントツールセットにアクセスできる Claude Sonnet 4.6 を使用したコーディングエージェントを定義します。ツールセットにより、エージェントはコードの記述、ファイルの読み取り、ウェブ検索などが可能になります。サポートされているツールの完全なリストについては、エージェントツールリファレンスを参照してください。

高速モードで Claude Opus 4.6 を使用するには、model をオブジェクトとして渡します: {"id": "claude-opus-4-6", "speed": "fast"}。

レスポンスは設定をエコーし、id、version、created_at、updated_at、および archived_at フィールドを追加します。version は 1 から始まり、エージェントを更新するたびにインクリメントされます。

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-sonnet-4-6",
    "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": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

エージェントを更新する

エージェントを更新すると新しいバージョンが生成されます。既知の状態から更新していることを確認するために、現在の version を渡します。

更新のセマンティクス

省略されたフィールドは保持されます。 変更したいフィールドのみを含める必要があります。
スカラーフィールド（model、system、name など）は新しい値に置き換えられます。system と description は null を渡すことでクリアできます。model と name は必須であり、クリアできません。
配列フィールド（tools、mcp_servers、skills、callable_agents）は新しい配列で完全に置き換えられます。配列フィールドを完全にクリアするには、null または空の配列を渡します。

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

操作	動作
更新	新しいエージェントバージョンを生成します。
バージョン一覧	時間の経過に伴う変更を追跡するために完全なバージョン履歴を取得します。
アーカイブ	エージェントが読み取り専用になります。新しいセッションはそれを参照できませんが、既存のセッションは引き続き実行されます。

バージョン一覧

エージェントが時間の経過とともにどのように変化したかを追跡するために、完全なバージョン履歴を取得します。

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

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

次のステップ

ツールを設定するでエージェントが使用できる機能をカスタマイズします。
スキルをアタッチするでドメイン固有の専門知識を追加します。
エージェントを参照するセッションを開始する。

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-sonnet-4-6",
    "system": "You are a helpful coding agent.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }')

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

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 @- <<EOF
{
  "version": $AGENT_VERSION,
  "system": "You are a helpful coding agent. Always write tests."
}
EOF
)

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

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)"'

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")"