agent-setup changedmanaged-agents/agent-setup
Recorded here
Lines+144added
Lines−28removed
From line
16
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits24to this page, all time
The whole hunk
from line 16, old and new numbered
/
from line 16
1616
1717## Agent configuration fields
1818
19| Field | Description |
20| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
21| `name` | Required. A human-readable name for the agent. |
22| `model` | Required. The Claude [model](https://platform.claude.com/docs/en/models/overview) that powers the agent. Accepts a model ID string or an object, for example `{"id": "claude-opus-5"}`. Claude 4.5 and later models are supported. The object form also accepts `speed`, `effort`, and `inference_geo` fields; see the tips under [Create an agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#create-an-agent), [Effort levels](https://platform.claude.com/docs/en/build-with-claude/effort#effort-levels), and [Pin the inference geo](https://platform.claude.com/docs/en/managed-agents/agent-setup#pin-the-inference-geo). |
23| `system` | A [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role) that defines the agent's behavior and persona. The system prompt is distinct from [user messages](https://platform.claude.com/docs/en/managed-agents/reference#event-types), which should describe the work to be done. |
24| `tools` | The tools available to the agent. Combines [pre-built agent tools](https://platform.claude.com/docs/en/managed-agents/tools), [MCP tools](https://platform.claude.com/docs/en/managed-agents/mcp-connector), and [custom tools](https://platform.claude.com/docs/en/managed-agents/tools#custom-tools). |
25| `mcp_servers` | [MCP servers](https://platform.claude.com/docs/en/managed-agents/mcp-connector) that provide standardized third-party capabilities. |
26| `skills` | [Skills](https://platform.claude.com/docs/en/managed-agents/skills) that supply domain-specific context with progressive disclosure. |
27| `multiagent` | Lets the agent hand work to other agents, as subagents or in [dynamic workflows](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#dynamic-workflows), and optionally consult an [advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) model. With the `multiagent_20261001` type, dynamic workflows are on unless you disable them. See [Multiagent orchestration](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration). |
28| `description` | A description of what the agent does. |
29| `metadata` | Arbitrary key-value pairs for your own tracking. |
19| Field | Description |
20| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
21| `name` (java, php; csharp, go: `Name`) | Required. A human-readable name for the agent. |
22| `model` (java, php; csharp, go: `Model`) | Required. The Claude [model](https://platform.claude.com/docs/en/models/overview) that powers the agent. Accepts a model ID string or an object, for example `{"id": "claude-opus-5"}`. Claude 4.5 and later models are supported. The object form also accepts `speed`, `effort`, and `inference_geo` fields; see the tips under [Create an agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#create-an-agent), [Effort levels](https://platform.claude.com/docs/en/build-with-claude/effort#effort-levels), and [Pin the inference geo](https://platform.claude.com/docs/en/managed-agents/agent-setup#pin-the-inference-geo). |
23| `system` (java, php; csharp, go: `System`; ruby: `system_`) | A [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role) that defines the agent's behavior and persona. The system prompt is distinct from [user messages](https://platform.claude.com/docs/en/managed-agents/reference#event-types), which should describe the work to be done. |
24| `tools` (java, php; csharp, go: `Tools`) | The tools available to the agent. Combines [pre-built agent tools](https://platform.claude.com/docs/en/managed-agents/tools), [MCP tools](https://platform.claude.com/docs/en/managed-agents/mcp-connector), and [custom tools](https://platform.claude.com/docs/en/managed-agents/tools#custom-tools). |
25| `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | [MCP servers](https://platform.claude.com/docs/en/managed-agents/mcp-connector) that provide standardized third-party capabilities. |
26| `skills` (java, php; csharp, go: `Skills`) | [Skills](https://platform.claude.com/docs/en/managed-agents/skills) that supply domain-specific context with progressive disclosure. |
27| `multiagent` (java, php; csharp, go: `Multiagent`) | Lets the agent hand work to other agents, as subagents or in [dynamic workflows](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#dynamic-workflows), and optionally consult an [advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) model. With the `multiagent_20261001` type, dynamic workflows are on unless you disable them. See [Multiagent orchestration](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration). |
28| `description` (java, php; csharp, go: `Description`) | A description of what the agent does. |
29| `metadata` (java, php; csharp, go: `Metadata`) | Arbitrary key-value pairs for your own tracking. |
3030
31You can also override `model`, `system`, `tools`, `mcp_servers`, and `skills` for a single session without changing the agent. A `model` override replaces the agent's `model` object in full, so the agent's own `effort` isn't carried over. To run the session at a specific effort level, set `effort` inside the override's `model` object. See [Override agent configuration for a session](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session).
31You can also override `model` (java, php; csharp, go: `Model`), `system` (java, php; csharp, go: `System`; ruby: `system_`), `tools` (java, php; csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), and `skills` (java, php; csharp, go: `Skills`) for a single session without changing the agent. A `model` (java, php; csharp, go: `Model`) override replaces the agent's `model` (java, php; csharp, go: `Model`) object in full, so the agent's own `effort` (java, php; csharp, go: `Effort`) isn't carried over. To run the session at a specific effort level, set `effort` (java, php; csharp, go: `Effort`) inside the override's `model` (java, php; csharp, go: `Model`) object. See [Override agent configuration for a session](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session).
3232
3333## Create an agent
3434
from line 212
212212
213213### Pin the inference geo
214214
215Like `speed` and `effort`, `inference_geo` is set through the object form of `model`: pass `model` as an object and set `inference_geo` alongside `id`. The field accepts `"us"` or `"global"`. When it's unset, each model request follows the workspace's default inference geo at the time it's served. See [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) for the workspace-level geo controls and pricing.
215Like `speed` (java, php; csharp, go: `Speed`) and `effort` (java, php; csharp, go: `Effort`), `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) is set through the object form of `model` (java, php; csharp, go: `Model`): pass `model` (java, php; csharp, go: `Model`) as an object and set `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) alongside `id` (java, php; csharp, go: `ID`). The field accepts `"us"` or `"global"`. When it's unset, each model request follows the workspace's default inference geo at the time it's served. See [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) for the workspace-level geo controls and pricing.
216216
217The following example pins an agent to US inference and prints the `inference_geo` value from the agent's `model` object:
217The following example pins an agent to US inference and prints the `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) value from the agent's `model` (java, php; csharp, go: `Model`) object:
218218
219219<CodeGroup defaultLanguage="CLI">
220220 ```bash cURL
from line 346
346346 ```
347347</CodeGroup>
348348
349An `inference_geo` pin is validated against the workspace's [`allowed_inference_geos`](https://platform.claude.com/docs/en/manage-claude/data-residency#workspace-level-restrictions) when the agent is saved, when a session is created from it, and on every turn the session serves. If the workspace allowlist narrows so a pin is no longer allowed, new sessions can't be created from the agent and running sessions refuse further turns; pins are never exempted, because workspaces rely on them for compliance and data residency.
349An `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) pin is validated against the workspace's [`allowed_inference_geos`](https://platform.claude.com/docs/en/manage-claude/data-residency#workspace-level-restrictions) when the agent is saved, when a session is created from it, and on every turn the session serves. If the workspace allowlist narrows so a pin is no longer allowed, new sessions can't be created from the agent and running sessions refuse further turns; pins are never exempted, because workspaces rely on them for compliance and data residency.
350350
351Setting `inference_geo` on a model that doesn't support geographic inference pinning returns a 400 error; see [Model availability](https://platform.claude.com/docs/en/manage-claude/data-residency#model-availability) for the models that do. In a `multiagent` configuration, the agent's pin and the pin of every agent listed in `subagents.predefined_agents` or `workflows.predefined_agents` must all be set to the same value or all be unset; see [Multiagent orchestration](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration). To change or clear the pin later, update the agent's `model` object; supplying `model` without `inference_geo` clears it, as described under [Update semantics](https://platform.claude.com/docs/en/managed-agents/agent-setup#update-semantics).
351Setting `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) on a model that doesn't support geographic inference pinning returns a 400 error; see [Model availability](https://platform.claude.com/docs/en/manage-claude/data-residency#model-availability) for the models that do. In a `multiagent` (java, php; csharp, go: `Multiagent`) configuration, the agent's pin and the pin of every agent listed in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `subagents` (java, php; csharp, go: `Subagents`) or `workflows` (java, php; csharp, go: `Workflows`) must all be set to the same value or all be unset; see [Multiagent orchestration](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration). To change or clear the pin later, update the agent's `model` (java, php; csharp, go: `Model`) object; supplying `model` (java, php; csharp, go: `Model`) without `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) clears it, as described under [Update semantics](https://platform.claude.com/docs/en/managed-agents/agent-setup#update-semantics).
352352
353353## Update an agent
354354
355Updating an agent generates a new version when the configuration changes. The `version` field is optional: supply it for optimistic concurrency (a mismatch returns a 409), or omit it to apply the update unconditionally (last write wins). Updates to archived agents are rejected.
355Updating an agent generates a new version when the configuration changes. The `version` (java, php; csharp, go: `Version`) field is optional: supply it for optimistic concurrency (a mismatch returns a 409), or omit it to apply the update unconditionally (last write wins). Updates to archived agents are rejected.
356356
357357With the CLI, edit the agent's file and run `ant apply` again; apply supplies `version` for you.
358358
from line 486
486486
487487### Update semantics
488488
489* **`version`** is optional and must be at least 1 when supplied. When supplied, the request returns a 409 if it doesn't match the agent's current version, even when the fields you send already match the stored values; re-read the agent and retry. When omitted, the update applies unconditionally and the most recent update silently replaces any concurrent one, with no error to either caller. Supplying `version` is the recommended default for interactive callers, and omitting it fits declarative apply loops, such as a CI job that syncs checked-in agent definitions, where the loop owns the agent.
489* **`version` (java, php; csharp, go: `Version`)** is optional and must be at least 1 when supplied. When supplied, the request returns a 409 if it doesn't match the agent's current version, even when the fields you send already match the stored values; re-read the agent and retry. When omitted, the update applies unconditionally and the most recent update silently replaces any concurrent one, with no error to either caller. Supplying `version` (java, php; csharp, go: `Version`) is the recommended default for interactive callers, and omitting it fits declarative apply loops, such as a CI job that syncs checked-in agent definitions, where the loop owns the agent.
490490
491491* **Omitted fields are preserved.** You only need to include the fields you want to change.
492492
493* **Scalar fields** (`model`, `system`, `name`, `description`) are replaced with the new value. `system` and `description` can be cleared by passing `null`. `model` and `name` are mandatory and cannot be cleared. Within a `model` object you supply, `effort` is the sole exception: if the model `id` is unchanged, omitting `effort` leaves the stored effort level unchanged. If you change the model `id`, an omitted `effort` resets to the new model's default. Other `model` fields are replaced along with the object: supplying `model` without `inference_geo` clears the agent's inference geo pin.
493* **Scalar fields** (`model` (java, php; csharp, go: `Model`), `system` (java, php; csharp, go: `System`; ruby: `system_`), `name` (java, php; csharp, go: `Name`), `description` (java, php; csharp, go: `Description`)) are replaced with the new value. `system` (java, php; csharp, go: `System`; ruby: `system_`) and `description` (java, php; csharp, go: `Description`) can be cleared by passing `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.Null[string]()`; php: `requestOptions: ['extraBodyParams' => ['system' => null, 'description' => null]]`). `model` (java, php; csharp, go: `Model`) and `name` (java, php; csharp, go: `Name`) are mandatory and cannot be cleared. Within a `model` (java, php; csharp, go: `Model`) object you supply, `effort` (java, php; csharp, go: `Effort`) is the sole exception: if the model `id` (java, php; csharp, go: `ID`) is unchanged, omitting `effort` (java, php; csharp, go: `Effort`) leaves the stored effort level unchanged. If you change the model `id` (java, php; csharp, go: `ID`), an omitted `effort` (java, php; csharp, go: `Effort`) resets to the new model's default. Other `model` (java, php; csharp, go: `Model`) fields are replaced along with the object: supplying `model` (java, php; csharp, go: `Model`) without `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) clears the agent's inference geo pin.
494494
495* **Array fields** (`tools`, `mcp_servers`, `skills`) are fully replaced by the new array. To clear an array field entirely, pass `null` or an empty array.
495* **Array fields** (`tools` (java, php; csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), `skills` (java, php; csharp, go: `Skills`)) are fully replaced by the new array. To clear an array field entirely, pass `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.NullSlice[[]anthropic.BetaAgentUpdateParamsToolUnion]()`; php: `requestOptions: ['extraBodyParams' => ['mcp_servers' => null]]`) or an empty array.
496496
497* **`multiagent`** is merged into the stored block level by level when the update keeps the `multiagent_20261001` type. A setting that you omit keeps its stored value, and a `predefined_agents` list that you send replaces the stored list. Any other update that sends `multiagent` replaces the stored block as a whole, and the settings that it omits take their defaults. Pass `"multiagent": null` to clear the whole block. Inside the block, `null` resets a setting to its default, so `"workflows": null` turns dynamic workflows on. See [Turn on dynamic workflows](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
497* **`multiagent` (java, php; csharp, go: `Multiagent`)** is merged into the stored block level by level when the update keeps the `multiagent_20261001` type. A setting that you omit keeps its stored value, and a `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list that you send replaces the stored list. Any other update that sends `multiagent` (java, php; csharp, go: `Multiagent`) replaces the stored block as a whole, and the settings that it omits take their defaults. Pass `"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]]`) to clear the whole block. Inside the block, `null` resets a setting to its default, so setting `workflows` (java, php; csharp, go: `Workflows`) to `null` turns dynamic workflows on. See [Turn on dynamic workflows](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
498498
499499* **Metadata** is merged at the key level. Keys you provide are added or updated. Keys you omit are preserved. To delete a specific key, set its value to `null`.
500500
501501* **No-op detection.** If the update produces no change relative to the current version, no new version is created and the existing version is returned.
502502
503* **Other agents' `predefined_agents` lists are not updated.** Agents that list this agent in `subagents.predefined_agents` or `workflows.predefined_agents` keep the version that was pinned when they were created or when an update last sent that list, even if the reference omits `version`. To delegate to the new version, [update the agent that lists it](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#list-the-subagents) so that the list references the new version.
503* **Other agents' `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) lists are not updated.** Agents that list this agent in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `subagents` (java, php; csharp, go: `Subagents`) or `workflows` (java, php; csharp, go: `Workflows`) keep the version that was pinned when they were created or when an update last sent that list, even if the reference omits `version` (java, php; csharp, go: `Version`). To delegate to the new version, [update the agent that lists it](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#list-the-subagents) so that the list references the new version.
504504
505The following update clears the description, deletes the `team` key from `metadata` (java, php; csharp, go: `Metadata`), and sets `workflows` (java, php; csharp, go: `Workflows`) to `null`, which turns dynamic workflows on:
506
507<CodeGroup exclude="shell:CLI">
508 ```bash cURL
509 cleared_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
510 -H "x-api-key: $ANTHROPIC_API_KEY" \
511 -H "anthropic-version: 2023-06-01" \
512 -H "anthropic-beta: managed-agents-2026-04-01" \
513 -H "content-type: application/json" \
514 -d '{
515 "description": null,
516 "metadata": {"team": null},
517 "multiagent": {"type": "multiagent_20261001", "workflows": null}
518 }')
519
520 echo "Description: $(jq -r '.description' <<< "$cleared_agent")"
521 ```
522
523 ```python Python
524 cleared_agent = client.beta.agents.update(
525 agent.id,
526 description=None,
527 metadata={"team": None},
528 multiagent={"type": "multiagent_20261001", "workflows": None},
529 )
530
531 print(f"Description: {cleared_agent.description}")
532 ```
533
534 ```typescript TypeScript
535 const clearedAgent = await client.beta.agents.update(agent.id, {
536 description: null,
537 metadata: { team: null },
538 multiagent: { type: "multiagent_20261001", workflows: null },
539 });
540
541 console.log(`Description: ${clearedAgent.description}`);
542 ```
543
544 ```csharp C#
545 var clearedAgent = await client.Beta.Agents.Update(agent.ID, new()
546 {
547 Description = null,
548 Metadata = new Dictionary<string, string?> { ["team"] = null },
549 Multiagent = new BetaManagedAgentsMultiagent20261001Params { Workflows = null },
550 });
551
552 Console.WriteLine($"Description: {clearedAgent.Description}");
553 ```
554
555 ```go Go
556 // Metadata is a map[string]string, so send the null for team as a request option.
557 clearedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
558 Description: param.Null[string](),
559 Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
560 OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
561 Workflows: param.NullStruct[anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion](),
562 },
563 },
564 }, option.WithJSONSet("metadata.team", nil))
565 if err != nil {
566 panic(err)
567 }
568
569 fmt.Printf("Description: %q\n", clearedAgent.Description)
570 ```
571
572 ```java Java
573 var clearedAgent = client.beta().agents().update(
574 agent.id(),
575 AgentUpdateParams.builder()
576 .description(Optional.empty())
577 .metadata(
578 AgentUpdateParams.Metadata.builder()
579 .putAdditionalProperty("team", JsonValue.from(null))
580 .build()
581 )
582 .multiagent(
583 BetaManagedAgentsMultiagent20261001Params.builder()
584 .workflows(Optional.empty())
585 .build()
586 )
587 .build()
588 );
589
590 IO.println("Description: " + clearedAgent.description().orElse(null));
591 ```
592
593 ```php PHP
594 // update() drops null arguments, so pass the nulls in extraBodyParams.
595 $clearedAgent = $client->beta->agents->update(
596 $agent->id,
597 requestOptions: [
598 'extraBodyParams' => [
599 'description' => null,
600 'metadata' => ['team' => null],
601 'multiagent' => ['type' => 'multiagent_20261001', 'workflows' => null],
602 ],
603 ],
604 );
605
606 echo 'Description: ' . json_encode($clearedAgent->description) . "\n";
607 ```
608
609 ```ruby Ruby
610 cleared_agent = client.beta.agents.update(
611 agent.id,
612 description: nil,
613 metadata: {team: nil},
614 multiagent: {type: :multiagent_20261001, workflows: nil}
615 )
616
617 puts "Description: #{cleared_agent.description.inspect}"
618 ```
619</CodeGroup>
620
505621## Agent lifecycle
506622
507623| Operation | Behavior |
from line 694
578694
579695### Archive an agent
580696
581Archiving makes the agent read-only and cannot be undone. Existing sessions continue to run, but new sessions cannot reference the agent. The response sets `archived_at` to the archive timestamp.
697Archiving makes the agent read-only and cannot be undone. Existing sessions continue to run, but new sessions cannot reference the agent. The response sets `archived_at` (java, php: `archivedAt`; csharp, go: `ArchivedAt`) to the archive timestamp.
582698
583699<CodeGroup>
584700 ```bash cURL
No line in this hunk matches that.