エージェントを定義する

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

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

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

エージェントを変更せずに、単一のセッションに対してmodel、system、tools、mcp_servers、skillsをオーバーライドすることもできます。modelのオーバーライドはエージェントのmodelオブジェクトを完全に置き換えるため、エージェント自身のeffortは引き継がれません。特定のeffortレベルでセッションを実行するには、オーバーライドのmodelオブジェクト内でeffortを設定してください。セッションのエージェント設定をオーバーライドするを参照してください。

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

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

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

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-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-5",
    "effort": { "type": "medium" },
    "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-5
  inference_geo: us
---

You are a helpful assistant.

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

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

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

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

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

ant apply coding-assistant.md

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

You are a helpful coding agent. Always write tests.

前の例では作成レスポンスのversionを指定しているため、読み取った後に他の何もエージェントを変更していない場合にのみ更新が適用されます。更新を無条件に適用するには、リクエストからversionを省略します：

unconditional_agent = client.beta.agents.update(
    agent.id,
    description="Writes and reviews code.",
)

print(f"New version: {unconditional_agent.version}")

更新のセマンティクス

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

• 省略したフィールドは保持されます。 変更したいフィールドのみを含めれば十分です。

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

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

• multiagentは、更新でmultiagent_20261001タイプが維持される場合、保存済みのブロックに階層ごとにマージされます。省略した設定は保存済みの値を保持し、送信したpredefined_agentsリストは保存済みのリストを置き換えます。multiagentを送信するその他の更新は、保存済みのブロック全体を置き換え、省略された設定はデフォルト値になります。ブロック全体をクリアするには、multiagent=Noneを渡します。ブロック内では、nullは設定をデフォルトにリセットするため、workflowsをnullに設定すると動的ワークフローが有効になります。動的ワークフローを有効にするを参照してください。

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

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

• 他のエージェントのpredefined_agentsリストは更新されません。 subagentsまたはworkflowsのpredefined_agentsリストにこのエージェントを含むエージェントは、参照でversionが省略されていても、作成時または最後にそのリストを送信した更新時に固定されたバージョンを保持します。新しいバージョンに委任するには、リストが新しいバージョンを参照するようにそれを含むエージェントを更新してください。

次の更新では、説明をクリアし、metadataからteamキーを削除し、workflowsをnullに設定して動的ワークフローを有効にします：

ant apply code-reviewer.md

---
name: Code Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
metadata:
  owner: docs
multiagent:
  type: multiagent_20261001
  workflows: null
---

You are a helpful coding agent.

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

バージョンを一覧表示する

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

for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")

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

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

archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")

次のステップ