---
title: Defina seu agente
url: https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup
description: Crie uma configuração de agente reutilizável e versionada.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
Um agente é uma configuração reutilizável e versionada que define persona e capacidades. Ele agrupa o modelo, o "system prompt" (prompt do sistema), as ferramentas, os servidores MCP e as skills que moldam como Claude se comporta durante uma sessão.
Crie o agente uma vez como um recurso reutilizável e referencie-o por ID sempre que você [iniciar uma sessão](https://platform.claude.com/docs/pt-BR/managed-agents/sessions). Os agentes são versionados e mais fáceis de gerenciar em muitas sessões.
## Campos de configuração do agente
| Campo | Descrição |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` (csharp, go: `Name`) | Obrigatório. Um nome legível por humanos para o agente. |
| `model` (csharp, go: `Model`) | Obrigatório. O [modelo](https://platform.claude.com/docs/pt-BR/models/overview) Claude que alimenta o agente. Aceita uma string de ID de modelo ou um objeto, por exemplo `{"id": "claude-opus-5-5"}`. Modelos Claude 4.5 e posteriores são suportados. A forma de objeto também aceita os campos `speed`, `effort` e `inference_geo`; consulte as dicas em [Criar um agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup#create-an-agent), [Níveis de esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#effort-levels) e [Fixar a geo de inferência](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup#pin-the-inference-geo). |
| `system` (csharp, go: `System`; ruby: `system_`) | Um [prompt do sistema](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role) que define o comportamento e a persona do agente. O prompt do sistema é distinto das [mensagens do usuário](https://platform.claude.com/docs/pt-BR/managed-agents/reference#event-types), que devem descrever o trabalho a ser feito. |
| `tools` (csharp, go: `Tools`) | As ferramentas disponíveis para o agente. Combina [ferramentas de agente pré-construídas](https://platform.claude.com/docs/pt-BR/managed-agents/tools), [ferramentas MCP](https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector) e [ferramentas personalizadas](https://platform.claude.com/docs/pt-BR/managed-agents/tools#custom-tools). |
| `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | [Servidores MCP](https://platform.claude.com/docs/pt-BR/managed-agents/mcp-connector) que fornecem capacidades padronizadas de terceiros. |
| `skills` (csharp, go: `Skills`) | [Skills](https://platform.claude.com/docs/pt-BR/managed-agents/skills) que fornecem contexto específico de domínio com divulgação progressiva. |
| `multiagent` (csharp, go: `Multiagent`) | Permite que o agente repasse trabalho para outros agentes, como subagentes ou em [fluxos de trabalho dinâmicos](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#dynamic-workflows), e opcionalmente consulte um modelo [consultor](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#give-the-session-an-advisor). Com o tipo `multiagent_20261001`, os fluxos de trabalho dinâmicos ficam ativados, a menos que você os desative. Consulte [Orquestração multiagente](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration). |
| `description` (csharp, go: `Description`) | Uma descrição do que o agente faz. |
| `metadata` (csharp, go: `Metadata`) | Pares chave-valor arbitrários para seu próprio rastreamento. |
Você também pode substituir `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) e `skills` (csharp, go: `Skills`) para uma única sessão sem alterar o agente. Uma substituição de `model` (csharp, go: `Model`) substitui por completo o objeto `model` (csharp, go: `Model`) do agente, portanto o `effort` (csharp, go: `Effort`) do próprio agente não é mantido. Para executar a sessão em um nível de esforço específico, defina `effort` (csharp, go: `Effort`) dentro do objeto `model` (csharp, go: `Model`) da substituição. Consulte [Substituir a configuração do agente para uma sessão](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#override-agent-configuration-for-a-session).
## Criar um agente
O exemplo a seguir define um agente de programação que usa o modelo Claude Opus mais recente com acesso ao conjunto de ferramentas de agente pré-construído. O conjunto de ferramentas permite que o agente escreva código, leia arquivos, pesquise na web e muito mais. Consulte a [referência de ferramentas de agente](https://platform.claude.com/docs/pt-BR/managed-agents/tools) para a lista completa de ferramentas suportadas.
Os exemplos usam curl, a CLI `ant` ou um dos SDKs. Se você ainda não configurou nenhum deles, o [início rápido](https://platform.claude.com/docs/pt-BR/managed-agents/quickstart#install-the-cli) aborda a instalação e a configuração do cliente.
```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"}]
}'
```
```bash CLI
ant apply coding-assistant.md
```
```markdown
---
name: Coding Assistant
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a helpful coding agent.
```
[`ant apply`](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/apply) cria o agente a partir de `coding-assistant.md`, imprime seu ID e o registra em `claude-lock.json`. Faça commit de `claude-lock.json` para que o próximo `ant apply` atualize este agente em vez de criar um segundo.
```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"}]
)
```
A resposta repete sua configuração e adiciona os campos `id`, `type`, `version`, `created_at`, `updated_at` e `archived_at`, além de preencher com seus valores padrão os campos de `model` que você omitir, como `effort`. O `version` começa em 1 e é incrementado cada vez que uma atualização altera o agente.
```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
}
```
O `default_config` no conjunto de ferramentas mostra sua [política de permissões](https://platform.claude.com/docs/pt-BR/managed-agents/permission-policies) padrão, `always_allow`, que se aplica a menos que você configure uma.
Para usar Claude Opus 5.5, Claude Opus 5 ou Claude Opus 4.8 com o [modo rápido](https://platform.claude.com/docs/pt-BR/build-with-claude/fast-mode), passe `model` como um objeto, por exemplo: `{"id": "claude-opus-5-5", "speed": "fast"}`. Consulte os [modelos suportados](https://platform.claude.com/docs/pt-BR/build-with-claude/fast-mode#supported-models) na página do modo rápido.
Para definir o nível de esforço do modelo, passe `model` como um objeto, por exemplo: `{"id": "claude-opus-5-5", "effort": "high"}`. O campo `effort` aceita uma string de nível (`low`, `medium`, `high`, `xhigh` ou `max`) ou um objeto como `{"type": "high"}`. Consulte [Níveis de esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#effort-levels) para saber o que cada nível faz.
### Fixar a geo de inferência
Assim como `speed` (csharp, go: `Speed`) e `effort` (csharp, go: `Effort`), `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) é definido por meio da forma de objeto de `model` (csharp, go: `Model`): passe `model` (csharp, go: `Model`) como um objeto e defina `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) junto com `id` (csharp, go: `ID`). O campo aceita `"us"` ou `"global"`. Quando não está definido, cada requisição ao modelo segue a geo de inferência padrão do workspace no momento em que é atendida. Consulte [Residência de dados](https://platform.claude.com/docs/pt-BR/manage-claude/data-residency) para ver os controles de geo no nível do workspace e os preços.
O exemplo a seguir fixa um agente na inferência dos EUA e imprime o valor de `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) do objeto `model` (csharp, go: `Model`) do agente:
```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."
}'
```
```bash CLI
ant apply geo-pinned-assistant.md
```
```markdown
---
name: Geo-pinned assistant
model:
id: claude-opus-5-5
inference_geo: us
---
You are a helpful assistant.
```
```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}"
```
Uma fixação de `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) é validada em relação ao [`allowed_inference_geos`](https://platform.claude.com/docs/pt-BR/manage-claude/data-residency#workspace-level-restrictions) do workspace quando o agente é salvo, quando uma sessão é criada a partir dele e em cada turno que a sessão atende. Se a lista de permissões do workspace for restringida de modo que uma fixação não seja mais permitida, novas sessões não poderão ser criadas a partir do agente e as sessões em execução recusarão turnos adicionais; as fixações nunca são isentas, porque os workspaces dependem delas para conformidade e residência de dados.
Definir `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) em um modelo que não suporta fixação geográfica de inferência retorna um erro 400; consulte [Disponibilidade de modelos](https://platform.claude.com/docs/pt-BR/manage-claude/data-residency#model-availability) para ver os modelos que suportam. Em uma configuração `multiagent` (csharp, go: `Multiagent`), a fixação do agente e a fixação de cada agente listado na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) ou `workflows` (csharp, go: `Workflows`) devem estar todas definidas com o mesmo valor ou todas sem definição; consulte [Orquestração multiagente](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration). Para alterar ou remover a fixação posteriormente, atualize o objeto `model` (csharp, go: `Model`) do agente; fornecer `model` (csharp, go: `Model`) sem `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) a remove, conforme descrito em [Semântica de atualização](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup#update-semantics).
## Atualizar um agente
Atualizar um agente gera uma nova versão quando a configuração muda. O campo `version` (csharp, go: `Version`) é opcional: forneça-o para "optimistic concurrency" (concorrência otimista) (uma incompatibilidade retorna um 409), ou omita-o para aplicar a atualização incondicionalmente (a última gravação prevalece). Atualizações em agentes arquivados são rejeitadas.
Com a CLI, edite o arquivo do agente e execute `ant apply` novamente; o apply fornece `version` para você.
```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."
}'
```
```bash CLI
ant apply 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.
```
```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}"
```
O exemplo anterior fornece `version` a partir da resposta de criação, de modo que a atualização só é aplicada se nada mais tiver alterado o agente desde que você o leu. Para aplicar uma atualização incondicionalmente, omita `version` da requisição:
```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}"
```
### Semântica de atualização
* **`version` (csharp, go: `Version`)** é opcional e deve ser pelo menos 1 quando fornecido. Quando fornecido, a requisição retorna um 409 se não corresponder à versão atual do agente, mesmo quando os campos que você envia já correspondem aos valores armazenados; leia o agente novamente e tente de novo. Quando omitido, a atualização é aplicada incondicionalmente e a atualização mais recente substitui silenciosamente qualquer atualização concorrente, sem erro para nenhum dos chamadores. Fornecer `version` (csharp, go: `Version`) é o padrão recomendado para chamadores interativos, e omiti-lo é adequado para loops de apply declarativos, como um job de CI que sincroniza definições de agentes versionadas no repositório, em que o loop é o dono do agente.
* **Campos omitidos são preservados.** Você só precisa incluir os campos que deseja alterar.
* **Campos escalares** (`model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `name` (csharp, go: `Name`), `description` (csharp, go: `Description`)) são substituídos pelo novo valor. `system` (csharp, go: `System`; ruby: `system_`) e `description` (csharp, go: `Description`) podem ser limpos passando `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.Null[string]()`; php: `requestOptions: ['extraBodyParams' => ['system' => null, 'description' => null]]`). `model` (csharp, go: `Model`) e `name` (csharp, go: `Name`) são obrigatórios e não podem ser limpos. Dentro de um objeto `model` (csharp, go: `Model`) que você fornece, `effort` (csharp, go: `Effort`) é a única exceção: se o `id` (csharp, go: `ID`) do modelo não mudar, omitir `effort` (csharp, go: `Effort`) mantém inalterado o nível de esforço armazenado. Se você alterar o `id` (csharp, go: `ID`) do modelo, um `effort` (csharp, go: `Effort`) omitido é redefinido para o padrão do novo modelo. Outros campos de `model` (csharp, go: `Model`) são substituídos junto com o objeto: fornecer `model` (csharp, go: `Model`) sem `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) remove a fixação de geo de inferência do agente.
* **Campos de array** (`tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), `skills` (csharp, go: `Skills`)) são totalmente substituídos pelo novo array. Para limpar completamente um campo de array, passe `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.NullSlice[[]anthropic.BetaAgentUpdateParamsToolUnion]()`; php: `requestOptions: ['extraBodyParams' => ['mcp_servers' => null]]`) ou um array vazio.
* **`multiagent` (csharp, go: `Multiagent`)** é mesclado ao bloco armazenado nível por nível quando a atualização mantém o tipo `multiagent_20261001`. Uma configuração que você omite mantém seu valor armazenado, e uma lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) que você envia substitui a lista armazenada. Qualquer outra atualização que envie `multiagent` (csharp, go: `Multiagent`) substitui o bloco armazenado como um todo, e as configurações que ela omite assumem seus valores padrão. Passe `"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]]`) para limpar o bloco inteiro. Dentro do bloco, `null` redefine uma configuração para seu padrão, portanto definir `workflows` (csharp, go: `Workflows`) como `null` ativa os fluxos de trabalho dinâmicos. Consulte [Ativar fluxos de trabalho dinâmicos](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
* **Metadata** é mesclado no nível da chave. As chaves que você fornece são adicionadas ou atualizadas. As chaves que você omite são preservadas. Para excluir uma chave específica, defina seu valor como `null`.
* **Detecção de no-op.** Se a atualização não produzir nenhuma alteração em relação à versão atual, nenhuma nova versão é criada e a versão existente é retornada.
* **As listas `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de outros agentes não são atualizadas.** Agentes que listam este agente na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) ou `workflows` (csharp, go: `Workflows`) mantêm a versão que foi fixada quando foram criados ou quando uma atualização enviou essa lista pela última vez, mesmo que a referência omita `version` (csharp, go: `Version`). Para delegar à nova versão, [atualize o agente que o lista](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#list-the-subagents) para que a lista referencie a nova versão.
A atualização a seguir limpa a descrição, exclui a chave `team` de `metadata` (csharp, go: `Metadata`) e define `workflows` (csharp, go: `Workflows`) como `null`, o que ativa os fluxos de trabalho dinâmicos:
```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}
}'
```
```bash CLI
ant apply 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.
```
O arquivo não tem mais `description` nem a chave `team`, então `ant apply` envia `null` para eles. Excluir uma configuração dentro de `multiagent` mantém seu valor armazenado, por isso o arquivo define `workflows` como `null`.
```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 { ["team"] = null },
Multiagent = new BetaManagedAgentsMultiagent20261001Params { Workflows = null },
});
Console.WriteLine($"Description: {clearedAgent.Description}");
```
```go Go
// Metadata é um map[string]string, então envie o null para team como opção da requisição.
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() descarta argumentos nulos, então passe os nulos em 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}"
```
## Ciclo de vida do agente
| Operação | Comportamento |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Atualizar** | Gera uma nova versão do agente quando a configuração muda. |
| **Listar versões** | Retorna o histórico completo de versões para que você possa acompanhar as alterações ao longo do tempo. |
| **Arquivar** | Torna o agente somente leitura. Novas sessões não podem referenciá-lo, mas as sessões existentes continuam em execução. |
### Listar versões
Obtenha o histórico completo de versões para acompanhar como um agente mudou ao longo do tempo. Os resultados são paginados, e os exemplos de SDK buscam todas as páginas automaticamente.
```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
```
### Arquivar um agente
Arquivar torna o agente somente leitura e não pode ser desfeito. As sessões existentes continuam em execução, mas novas sessões não podem referenciar o agente. A resposta define `archived_at` (java, php: `archivedAt`; csharp, go: `ArchivedAt`) com o timestamp do arquivamento.
```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}"
```
## Próximos passos
Configure as ferramentas disponíveis para o seu agente.
Anexe ao seu agente conhecimento especializado reutilizável e baseado em sistema de arquivos para fluxos de trabalho específicos de domínio.
Crie uma sessão para executar seu agente e começar a executar tarefas.
Tipos de eventos, flags da CLI de worker auto-hospedado, tipos de servidores MCP suportados, limites de taxa e diretrizes de marca para Claude Managed Agents.