---
title: エージェントを定義する
url: https://platform.claude.com/docs/ja/managed-agents/agent-setup
description: 再利用可能でバージョン管理されたエージェント設定を作成します。
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

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

エージェントは再利用可能なリソースとして一度作成し、[セッションを開始](https://platform.claude.com/docs/ja/managed-agents/sessions)するたびにIDで参照します。エージェントはバージョン管理されており、多数のセッションにわたって管理しやすくなっています。

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

| フィールド                                                                           | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` (csharp, go: `Name`)                                                     | 必須。エージェントの人間が読める名前。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `model` (csharp, go: `Model`)                                                   | 必須。エージェントを動かすClaudeの[モデル](https://platform.claude.com/docs/ja/models/overview)。モデルID文字列またはオブジェクト（例：`{"id": "claude-opus-5-5"}`）を受け付けます。Claude 4.5以降のモデルがサポートされています。オブジェクト形式では`speed`、`effort`、`inference_geo`フィールドも受け付けます。[エージェントを作成する](https://platform.claude.com/docs/ja/managed-agents/agent-setup#create-an-agent)のヒント、[Effortレベル](https://platform.claude.com/docs/ja/build-with-claude/effort#effort-levels)、[推論ジオを固定する](https://platform.claude.com/docs/ja/managed-agents/agent-setup#pin-the-inference-geo)を参照してください。 |
| `system` (csharp, go: `System`; ruby: `system_`)                                | エージェントの振る舞いとペルソナを定義する[システムプロンプト](https://platform.claude.com/docs/ja/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role)。システムプロンプトは、実行すべき作業を記述する[ユーザーメッセージ](https://platform.claude.com/docs/ja/managed-agents/reference#event-types)とは区別されます。                                                                                                                                                                                                                                             |
| `tools` (csharp, go: `Tools`)                                                   | エージェントが利用できるツール。[事前構築済みのエージェントツール](https://platform.claude.com/docs/ja/managed-agents/tools)、[MCPツール](https://platform.claude.com/docs/ja/managed-agents/mcp-connector)、[カスタムツール](https://platform.claude.com/docs/ja/managed-agents/tools#custom-tools)を組み合わせます。                                                                                                                                                                                                                                                               |
| `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | 標準化されたサードパーティ機能を提供する[MCPサーバー](https://platform.claude.com/docs/ja/managed-agents/mcp-connector)。                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `skills` (csharp, go: `Skills`)                                                 | 段階的な開示によってドメイン固有のコンテキストを提供する[スキル](https://platform.claude.com/docs/ja/managed-agents/skills)。                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `multiagent` (csharp, go: `Multiagent`)                                         | エージェントが、サブエージェントとして、または[動的ワークフロー](https://platform.claude.com/docs/ja/managed-agents/multiagent-orchestration#dynamic-workflows)の中で他のエージェントに作業を引き渡せるようにし、オプションで[アドバイザー](https://platform.claude.com/docs/ja/managed-agents/multiagent-orchestration#give-the-session-an-advisor)モデルに相談できるようにします。`multiagent_20261001`タイプでは、無効にしない限り動的ワークフローが有効になります。[マルチエージェントオーケストレーション](https://platform.claude.com/docs/ja/managed-agents/multiagent-orchestration)を参照してください。                                                                |
| `description` (csharp, go: `Description`)                                       | エージェントが何をするかの説明。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `metadata` (csharp, go: `Metadata`)                                             | 独自の追跡用の任意のキーと値のペア。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

エージェントを変更せずに、単一のセッションに対して`model` (csharp, go: `Model`)、`system` (csharp, go: `System`; ruby: `system_`)、`tools` (csharp, go: `Tools`)、`mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)、`skills` (csharp, go: `Skills`)をオーバーライドすることもできます。`model` (csharp, go: `Model`)のオーバーライドはエージェントの`model` (csharp, go: `Model`)オブジェクトを完全に置き換えるため、エージェント自身の`effort` (csharp, go: `Effort`)は引き継がれません。特定のeffortレベルでセッションを実行するには、オーバーライドの`model` (csharp, go: `Model`)オブジェクト内で`effort` (csharp, go: `Effort`)を設定してください。[セッションのエージェント設定をオーバーライドする](https://platform.claude.com/docs/ja/managed-agents/sessions#override-agent-configuration-for-a-session)を参照してください。

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

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

例ではcurl、`ant` CLI、またはいずれかのSDKを使用します。まだセットアップしていない場合は、[クイックスタート](https://platform.claude.com/docs/ja/managed-agents/quickstart#install-the-cli)でインストールとクライアントのセットアップを説明しています。

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  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"}]
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply coding-assistant.md
    ```

    <File filename="coding-assistant.md">
      ```markdown
      ---
      name: Coding Assistant
      model: claude-opus-5-5
      tools:
        - type: agent_toolset_20260401
      ---

      You are a helpful coding agent.
      ```
    </File>

    [`ant apply`](https://platform.claude.com/docs/ja/cli-sdks-libraries/cli/apply)は`coding-assistant.md`からエージェントを作成し、そのIDを出力して`claude-lock.json`に記録します。`claude-lock.json`をコミットしておくと、次回の`ant apply`で2つ目のエージェントを作成する代わりにこのエージェントが更新されます。
  </CodeGroupItem>

  ```python Python
  agent = client.beta.agents.create(
      name="Coding Assistant",
      model="claude-opus-5-5",
      system="You are a helpful coding agent.",
      tools=[
          {"type": "agent_toolset_20260401"},
      ],
  )
  ```

  ```typescript TypeScript
  const agent = await client.beta.agents.create({
    name: "Coding Assistant",
    model: "claude-opus-5-5",
    system: "You are a helpful coding agent.",
    tools: [{ type: "agent_toolset_20260401" }],
  });
  ```

  ```csharp C#
  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Coding Assistant",
      Model = BetaManagedAgentsModel.ClaudeOpus5_5,
      System = "You are a helpful coding agent.",
      Tools =
      [
          new BetaManagedAgentsAgentToolset20260401Params
          {
              Type = "agent_toolset_20260401",
          },
      ],
  });
  ```

  ```go Go
  agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name: "Coding Assistant",
  	Model: anthropic.BetaManagedAgentsModelConfigParams{
  		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  	},
  	System: anthropic.String("You are a helpful coding agent."),
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
  			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var agent = client.beta().agents().create(
      AgentCreateParams.builder()
          .name("Coding Assistant")
          .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
          .system("You are a helpful coding agent.")
          .addTool(
              BetaManagedAgentsAgentToolset20260401Params.builder()
                  .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                  .build()
          )
          .build()
  );
  ```

  ```php PHP
  $agent = $client->beta->agents->create(
      name: 'Coding Assistant',
      model: 'claude-opus-5-5',
      system: 'You are a helpful coding agent.',
      tools: [
          BetaManagedAgentsAgentToolset20260401Params::with(
              type: 'agent_toolset_20260401',
          ),
      ],
  );
  ```

  ```ruby Ruby
  agent = client.beta.agents.create(
    name: "Coding Assistant",
    model: "claude-opus-5-5",
    system_: "You are a helpful coding agent.",
    tools: [{type: "agent_toolset_20260401"}]
  )
  ```
</CodeGroup>

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

```json
{
  "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`には、デフォルトの[パーミッションポリシー](https://platform.claude.com/docs/ja/managed-agents/permission-policies)である`always_allow`が表示されます。これは、ポリシーを設定しない限り適用されます。

<Tip>
  Claude Opus 5.5、Claude Opus 5、またはClaude Opus 4.8を[高速モード](https://platform.claude.com/docs/ja/build-with-claude/fast-mode)で使用するには、`model`をオブジェクトとして渡します。例：`{"id": "claude-opus-5-5", "speed": "fast"}`。高速モードのページの[サポートされているモデル](https://platform.claude.com/docs/ja/build-with-claude/fast-mode#supported-models)を参照してください。
</Tip>

<Tip>
  モデルのeffortレベルを設定するには、`model`をオブジェクトとして渡します。例：`{"id": "claude-opus-5-5", "effort": "high"}`。`effort`フィールドは、レベルの文字列（`low`、`medium`、`high`、`xhigh`、または`max`）、または`{"type": "high"}`のようなオブジェクトを受け付けます。各レベルの動作については[Effortレベル](https://platform.claude.com/docs/ja/build-with-claude/effort#effort-levels)を参照してください。
</Tip>

### 推論ジオを固定する

`speed` (csharp, go: `Speed`)や`effort` (csharp, go: `Effort`)と同様に、`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)は`model` (csharp, go: `Model`)のオブジェクト形式で設定します。`model` (csharp, go: `Model`)をオブジェクトとして渡し、`id` (csharp, go: `ID`)と並べて`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)を設定します。このフィールドは`"us"`または`"global"`を受け付けます。未設定の場合、各モデルリクエストは処理される時点でのワークスペースのデフォルト推論ジオに従います。ワークスペースレベルのジオ制御と料金については、[データレジデンシー](https://platform.claude.com/docs/ja/manage-claude/data-residency)を参照してください。

次の例では、エージェントを米国での推論に固定し、エージェントの`model` (csharp, go: `Model`)オブジェクトから`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)の値を出力します：

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  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": "Geo-pinned assistant",
      "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
      "system": "You are a helpful assistant."
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply geo-pinned-assistant.md
    ```

    <File filename="geo-pinned-assistant.md">
      ```markdown
      ---
      name: Geo-pinned assistant
      model:
        id: claude-opus-5-5
        inference_geo: us
      ---

      You are a helpful assistant.
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  agent = client.beta.agents.create(
      name="Geo-pinned assistant",
      model={
          "id": "claude-opus-5-5",
          "inference_geo": "us",
      },
      system="You are a helpful assistant.",
  )

  print(f"Inference geo: {agent.model.inference_geo}")
  ```

  ```typescript TypeScript
  const agent = await client.beta.agents.create({
    name: "Geo-pinned assistant",
    model: { id: "claude-opus-5-5", inference_geo: "us" },
    system: "You are a helpful assistant.",
  });

  console.log(`Inference geo: ${agent.model.inference_geo}`);
  ```

  ```csharp C#
  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Geo-pinned assistant",
      Model = new BetaManagedAgentsModelConfigParams
      {
          ID = BetaManagedAgentsModel.ClaudeOpus5_5,
          InferenceGeo = "us",
      },
      System = "You are a helpful assistant.",
  });

  Console.WriteLine($"Inference geo: {agent.Model.InferenceGeo}");
  ```

  ```go Go
  agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name: "Geo-pinned assistant",
  	Model: anthropic.BetaManagedAgentsModelConfigParams{
  		ID:           anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  		InferenceGeo: anthropic.String("us"),
  	},
  	System: anthropic.String("You are a helpful assistant."),
  })
  if err != nil {
  	panic(err)
  }

  fmt.Printf("Inference geo: %s\n", agent.Model.InferenceGeo)
  ```

  ```java Java
  var agent = client.beta().agents().create(
      AgentCreateParams.builder()
          .name("Geo-pinned assistant")
          .model(
              BetaManagedAgentsModelConfigParams.builder()
                  .id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
                  .inferenceGeo("us")
                  .build()
          )
          .system("You are a helpful assistant.")
          .build()
  );

  IO.println("Inference geo: " + agent.model().inferenceGeo().orElseThrow());
  ```

  ```php PHP
  $agent = $client->beta->agents->create(
      name: 'Geo-pinned assistant',
      model: BetaManagedAgentsModelConfigParams::with(
          id: 'claude-opus-5-5',
          inferenceGeo: 'us',
      ),
      system: 'You are a helpful assistant.',
  );

  echo "Inference geo: {$agent->model->inferenceGeo}\n";
  ```

  ```ruby Ruby
  agent = client.beta.agents.create(
    name: "Geo-pinned assistant",
    model: {id: "claude-opus-5-5", inference_geo: "us"},
    system_: "You are a helpful assistant."
  )

  puts "Inference geo: #{agent.model.inference_geo}"
  ```
</CodeGroup>

`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)の固定は、エージェントの保存時、そのエージェントからのセッション作成時、およびセッションが処理するすべてのターンで、ワークスペースの[`allowed_inference_geos`](https://platform.claude.com/docs/ja/manage-claude/data-residency#workspace-level-restrictions)に照らして検証されます。ワークスペースの許可リストが狭められて固定が許可されなくなった場合、そのエージェントから新しいセッションを作成できなくなり、実行中のセッションはそれ以降のターンを拒否します。ワークスペースはコンプライアンスとデータレジデンシーのために固定に依存しているため、固定が例外扱いされることはありません。

地理的な推論の固定をサポートしていないモデルで`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)を設定すると、400エラーが返されます。サポートしているモデルについては、[モデルの利用可能性](https://platform.claude.com/docs/ja/manage-claude/data-residency#model-availability)を参照してください。`multiagent` (csharp, go: `Multiagent`)設定では、エージェントの固定と、`subagents` (csharp, go: `Subagents`)または`workflows` (csharp, go: `Workflows`)の`predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)リストに含まれるすべてのエージェントの固定は、すべて同じ値に設定するか、すべて未設定にする必要があります。[マルチエージェントオーケストレーション](https://platform.claude.com/docs/ja/managed-agents/multiagent-orchestration)を参照してください。後で固定を変更またはクリアするには、エージェントの`model` (csharp, go: `Model`)オブジェクトを更新します。[更新のセマンティクス](https://platform.claude.com/docs/ja/managed-agents/agent-setup#update-semantics)で説明しているように、`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)なしで`model` (csharp, go: `Model`)を指定すると固定がクリアされます。

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

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

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

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  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."
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply coding-assistant.md
    ```

    <File filename="coding-assistant.md">
      ```markdown
      ---
      name: Coding Assistant
      model: claude-opus-5-5
      tools:
        - type: agent_toolset_20260401
      ---

      You are a helpful coding agent. Always write tests.
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  updated_agent = client.beta.agents.update(
      agent.id,
      version=agent.version,
      system="You are a helpful coding agent. Always write tests.",
  )

  print(f"New version: {updated_agent.version}")
  ```

  ```typescript TypeScript
  const updatedAgent = await client.beta.agents.update(agent.id, {
    version: agent.version,
    system: "You are a helpful coding agent. Always write tests.",
  });

  console.log(`New version: ${updatedAgent.version}`);
  ```

  ```csharp C#
  var updatedAgent = await client.Beta.Agents.Update(agent.ID, new()
  {
      Version = agent.Version,
      System = "You are a helpful coding agent. Always write tests.",
  });

  Console.WriteLine($"New version: {updatedAgent.Version}");
  ```

  ```go Go
  updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
  	Version: anthropic.Int(agent.Version),
  	System:  anthropic.String("You are a helpful coding agent. Always write tests."),
  })
  if err != nil {
  	panic(err)
  }

  fmt.Printf("New version: %d\n", updatedAgent.Version)
  ```

  ```java Java
  var updatedAgent = client.beta().agents().update(
      agent.id(),
      AgentUpdateParams.builder()
          .version(agent.version())
          .system("You are a helpful coding agent. Always write tests.")
          .build()
  );

  IO.println("New version: " + updatedAgent.version());
  ```

  ```php PHP
  $updatedAgent = $client->beta->agents->update(
      $agent->id,
      version: $agent->version,
      system: 'You are a helpful coding agent. Always write tests.',
  );

  echo "New version: {$updatedAgent->version}\n";
  ```

  ```ruby Ruby
  updated_agent = client.beta.agents.update(
    agent.id,
    version: agent.version,
    system_: "You are a helpful coding agent. Always write tests."
  )

  puts "New version: #{updated_agent.version}"
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash cURL
  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."
    }'
  ```

  ```bash CLI
  ant beta:agents update \
    --agent-id "$AGENT_ID" \
    --description "Writes and reviews code."
  ```

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

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

  ```typescript TypeScript
  const unconditionalAgent = await client.beta.agents.update(agent.id, {
    description: "Writes and reviews code.",
  });

  console.log(`New version: ${unconditionalAgent.version}`);
  ```

  ```csharp C#
  var unconditionalAgent = await client.Beta.Agents.Update(agent.ID, new()
  {
      Description = "Writes and reviews code.",
  });

  Console.WriteLine($"New version: {unconditionalAgent.Version}");
  ```

  ```go Go
  unconditionalAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
  	Description: anthropic.String("Writes and reviews code."),
  })
  if err != nil {
  	panic(err)
  }

  fmt.Printf("New version: %d\n", unconditionalAgent.Version)
  ```

  ```java Java
  var unconditionalAgent = client.beta().agents().update(
      agent.id(),
      AgentUpdateParams.builder()
          .description("Writes and reviews code.")
          .build()
  );

  IO.println("New version: " + unconditionalAgent.version());
  ```

  ```php PHP
  $unconditionalAgent = $client->beta->agents->update(
      $agent->id,
      description: 'Writes and reviews code.',
  );

  echo "New version: {$unconditionalAgent->version}\n";
  ```

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

  puts "New version: #{unconditional_agent.version}"
  ```
</CodeGroup>

### 更新のセマンティクス

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

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

* **スカラーフィールド**（`model` (csharp, go: `Model`)、`system` (csharp, go: `System`; ruby: `system_`)、`name` (csharp, go: `Name`)、`description` (csharp, go: `Description`)）は新しい値で置き換えられます。`system` (csharp, go: `System`; ruby: `system_`)と`description` (csharp, go: `Description`)は、`null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.Null[string]()`; php: `requestOptions: ['extraBodyParams' => ['system' => null, 'description' => null]]`)を渡すことでクリアできます。`model` (csharp, go: `Model`)と`name` (csharp, go: `Name`)は必須であり、クリアできません。指定した`model` (csharp, go: `Model`)オブジェクト内では、`effort` (csharp, go: `Effort`)が唯一の例外です。モデルの`id` (csharp, go: `ID`)が変わらない場合、`effort` (csharp, go: `Effort`)を省略すると保存済みのeffortレベルは変更されません。モデルの`id` (csharp, go: `ID`)を変更した場合、省略された`effort` (csharp, go: `Effort`)は新しいモデルのデフォルトにリセットされます。その他の`model` (csharp, go: `Model`)フィールドはオブジェクトとともに置き換えられます。`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)なしで`model` (csharp, go: `Model`)を指定すると、エージェントの推論ジオの固定がクリアされます。

* **配列フィールド**（`tools` (csharp, go: `Tools`)、`mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)、`skills` (csharp, go: `Skills`)）は新しい配列で完全に置き換えられます。配列フィールドを完全にクリアするには、`null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.NullSlice[[]anthropic.BetaAgentUpdateParamsToolUnion]()`; php: `requestOptions: ['extraBodyParams' => ['mcp_servers' => null]]`)または空の配列を渡します。

* **`multiagent` (csharp, go: `Multiagent`)**&#x306F;、更新で`multiagent_20261001`タイプが維持される場合、保存済みのブロックに階層ごとにマージされます。省略した設定は保存済みの値を保持し、送信した`predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)リストは保存済みのリストを置き換えます。`multiagent` (csharp, go: `Multiagent`)を送信するその他の更新は、保存済みのブロック全体を置き換え、省略された設定はデフォルト値になります。ブロック全体をクリアするには、`"multiagent": null` (python: `multiagent=None`; typescript: `multiagent: null`; ruby: `multiagent: nil`; go: `Multiagent: param.NullStruct[anthropic.BetaManagedAgentsMultiagentParamsUnion]()`; java: `.multiagent(Optional.empty())`; csharp: `Multiagent = null`; php: `requestOptions: ['extraBodyParams' => ['multiagent' => null]]`)を渡します。ブロック内では、`null`は設定をデフォルトにリセットするため、`workflows` (csharp, go: `Workflows`)を`null`に設定すると動的ワークフローが有効になります。[動的ワークフローを有効にする](https://platform.claude.com/docs/ja/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)を参照してください。

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

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

* **他のエージェントの`predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)リストは更新されません。** `subagents` (csharp, go: `Subagents`)または`workflows` (csharp, go: `Workflows`)の`predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)リストにこのエージェントを含むエージェントは、参照で`version` (csharp, go: `Version`)が省略されていても、作成時または最後にそのリストを送信した更新時に固定されたバージョンを保持します。新しいバージョンに委任するには、リストが新しいバージョンを参照するように[それを含むエージェントを更新](https://platform.claude.com/docs/ja/managed-agents/multiagent-orchestration#list-the-subagents)してください。

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

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  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": null,
      "metadata": {"team": null},
      "multiagent": {"type": "multiagent_20261001", "workflows": null}
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply code-reviewer.md
    ```

    <File filename="code-reviewer.md">
      ```markdown
      ---
      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.
      ```
    </File>

    ファイルには`description`も`team`キーもなくなったため、`ant apply`はそれらに対して`null`を送信します。`multiagent`内の設定を削除すると保存済みの値が保持されるため、ファイルでは`workflows`を`null`に設定しています。
  </CodeGroupItem>

  ```python Python
  cleared_agent = client.beta.agents.update(
      agent.id,
      description=None,
      metadata={"team": None},
      multiagent={"type": "multiagent_20261001", "workflows": None},
  )

  print(f"Description: {cleared_agent.description}")
  ```

  ```typescript TypeScript
  const clearedAgent = await client.beta.agents.update(agent.id, {
    description: null,
    metadata: { team: null },
    multiagent: { type: "multiagent_20261001", workflows: null },
  });

  console.log(`Description: ${clearedAgent.description}`);
  ```

  ```csharp C#
  var clearedAgent = await client.Beta.Agents.Update(agent.ID, new()
  {
      Description = null,
      Metadata = new Dictionary<string, string?> { ["team"] = null },
      Multiagent = new BetaManagedAgentsMultiagent20261001Params { Workflows = null },
  });

  Console.WriteLine($"Description: {clearedAgent.Description}");
  ```

  ```go Go
  // Metadata は map[string]string のため、team の null はリクエストオプションとして送信します。
  clearedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
  	Description: param.Null[string](),
  	Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
  		OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
  			Workflows: param.NullStruct[anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion](),
  		},
  	},
  }, option.WithJSONSet("metadata.team", nil))
  if err != nil {
  	panic(err)
  }

  fmt.Printf("Description: %q\n", clearedAgent.Description)
  ```

  ```java Java
  var clearedAgent = client.beta().agents().update(
      agent.id(),
      AgentUpdateParams.builder()
          .description(Optional.empty())
          .metadata(
              AgentUpdateParams.Metadata.builder()
                  .putAdditionalProperty("team", JsonValue.from(null))
                  .build()
          )
          .multiagent(
              BetaManagedAgentsMultiagent20261001Params.builder()
                  .workflows(Optional.empty())
                  .build()
          )
          .build()
  );

  IO.println("Description: " + clearedAgent.description().orElse(null));
  ```

  ```php PHP
  // update() は null 引数を除外するため、null は extraBodyParams で渡します。
  $clearedAgent = $client->beta->agents->update(
      $agent->id,
      requestOptions: [
          'extraBodyParams' => [
              'description' => null,
              'metadata' => ['team' => null],
              'multiagent' => ['type' => 'multiagent_20261001', 'workflows' => null],
          ],
      ],
  );

  echo 'Description: ' . json_encode($clearedAgent->description) . "\n";
  ```

  ```ruby Ruby
  cleared_agent = client.beta.agents.update(
    agent.id,
    description: nil,
    metadata: {team: nil},
    multiagent: {type: :multiagent_20261001, workflows: nil}
  )

  puts "Description: #{cleared_agent.description.inspect}"
  ```
</CodeGroup>

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

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

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

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

<CodeGroup>
  ```bash cURL
  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"
  ```

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

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

  ```typescript TypeScript
  for await (const version of client.beta.agents.versions.list(agent.id)) {
    console.log(`Version ${version.version}: ${version.updated_at}`);
  }
  ```

  ```csharp C#
  var versions = await client.Beta.Agents.Versions.List(agent.ID);
  await foreach (var version in versions.Paginate())
  {
      Console.WriteLine($"Version {version.Version}: {version.UpdatedAt:O}");
  }
  ```

  ```go Go
  iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{})
  for iter.Next() {
  	version := iter.Current()
  	fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339))
  }
  if err := iter.Err(); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) {
      IO.println("Version " + version.version() + ": " + version.updatedAt());
  }
  ```

  ```php PHP
  foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) {
      echo "Version {$version->version}: {$version->updatedAt->format(\DateTimeInterface::ATOM)}\n";
  }
  ```

  ```ruby Ruby
  client.beta.agents.versions.list(agent.id).auto_paging_each do |agent_version|
    puts "Version #{agent_version.version}: #{agent_version.updated_at.iso8601}"
  end
  ```
</CodeGroup>

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

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

<CodeGroup>
  ```bash cURL
  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"
  ```

  ```bash CLI
  ant beta:agents archive --agent-id "$AGENT_ID"
  ```

  ```python Python
  archived = client.beta.agents.archive(agent.id)

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

  ```typescript TypeScript
  const archived = await client.beta.agents.archive(agent.id);
  console.log(`Archived at: ${archived.archived_at}`);
  ```

  ```csharp C#
  var archived = await client.Beta.Agents.Archive(agent.ID);
  Console.WriteLine($"Archived at: {archived.ArchivedAt:O}");
  ```

  ```go Go
  archived, err := client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{})
  if err != nil {
  	panic(err)
  }
  fmt.Printf("Archived at: %s\n", archived.ArchivedAt.Format(time.RFC3339))
  ```

  ```java Java
  var archived = client.beta().agents().archive(agent.id());
  IO.println("Archived at: " + archived.archivedAt().orElseThrow());
  ```

  ```php PHP
  $archived = $client->beta->agents->archive($agent->id);

  echo "Archived at: {$archived->archivedAt->format(\DateTimeInterface::ATOM)}\n";
  ```

  ```ruby Ruby
  archived = client.beta.agents.archive(agent.id)
  puts "Archived at: #{archived.archived_at.iso8601}"
  ```
</CodeGroup>

## 次のステップ

<CardGroup cols={2}>
  <Card title="ツール" icon="tool" href="https://platform.claude.com/docs/ja/managed-agents/tools">
    エージェントが利用できるツールを設定します。
  </Card>

  <Card title="スキル" icon="graduation-cap" href="https://platform.claude.com/docs/ja/managed-agents/skills">
    ドメイン固有のワークフローのために、再利用可能なファイルシステムベースの専門知識をエージェントに付与します。
  </Card>

  <Card title="セッションを開始する" icon="play" href="https://platform.claude.com/docs/ja/managed-agents/sessions">
    セッションを作成してエージェントを実行し、タスクの実行を開始します。
  </Card>

  <Card title="リファレンス" icon="book" href="https://platform.claude.com/docs/ja/managed-agents/reference">
    Claude Managed Agentsのイベントタイプ、セルフホストワーカーのCLIフラグ、サポートされているMCPサーバーの種類、レート制限、ブランディングガイドライン。
  </Card>
</CardGroup>