---
title: Define tu agente
url: https://platform.claude.com/docs/es/managed-agents/agent-setup
description: Crea una configuración de agente reutilizable y versionada.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
Un agente es una configuración reutilizable y versionada que define la personalidad y las capacidades. Agrupa el modelo, la "system prompt" (indicación del sistema), las herramientas, los servidores MCP y las skills que determinan cómo se comporta Claude durante una sesión.
Crea el agente una sola vez como un recurso reutilizable y haz referencia a él por su ID cada vez que [inicies una sesión](https://platform.claude.com/docs/es/managed-agents/sessions). Los agentes están versionados y son más fáciles de administrar a lo largo de muchas sesiones.
## Campos de configuración del agente
| Campo | Descripción |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` (csharp, go: `Name`) | Obligatorio. Un nombre legible para el agente. |
| `model` (csharp, go: `Model`) | Obligatorio. El [modelo](https://platform.claude.com/docs/es/models/overview) de Claude que impulsa al agente. Acepta una cadena con el ID del modelo o un objeto, por ejemplo `{"id": "claude-opus-5-5"}`. Se admiten los modelos Claude 4.5 y posteriores. La forma de objeto también acepta los campos `speed`, `effort` e `inference_geo`; consulta los consejos en [Crear un agente](https://platform.claude.com/docs/es/managed-agents/agent-setup#create-an-agent), [Niveles de esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort#effort-levels) y [Fijar la geo de inferencia](https://platform.claude.com/docs/es/managed-agents/agent-setup#pin-the-inference-geo). |
| `system` (csharp, go: `System`; ruby: `system_`) | Una [indicación del sistema](https://platform.claude.com/docs/es/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role) que define el comportamiento y la personalidad del agente. La indicación del sistema es distinta de los [mensajes de usuario](https://platform.claude.com/docs/es/managed-agents/reference#event-types), que deben describir el trabajo que se debe realizar. |
| `tools` (csharp, go: `Tools`) | Las herramientas disponibles para el agente. Combina [herramientas de agente predefinidas](https://platform.claude.com/docs/es/managed-agents/tools), [herramientas MCP](https://platform.claude.com/docs/es/managed-agents/mcp-connector) y [herramientas personalizadas](https://platform.claude.com/docs/es/managed-agents/tools#custom-tools). |
| `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | [Servidores MCP](https://platform.claude.com/docs/es/managed-agents/mcp-connector) que proporcionan capacidades estandarizadas de terceros. |
| `skills` (csharp, go: `Skills`) | [Skills](https://platform.claude.com/docs/es/managed-agents/skills) que aportan contexto específico del dominio con divulgación progresiva. |
| `multiagent` (csharp, go: `Multiagent`) | Permite que el agente delegue trabajo a otros agentes, como subagentes o en [flujos de trabajo dinámicos](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#dynamic-workflows), y opcionalmente consulte un modelo [asesor](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#give-the-session-an-advisor). Con el tipo `multiagent_20261001`, los flujos de trabajo dinámicos están activados a menos que los desactives. Consulta [Orquestación multiagente](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration). |
| `description` (csharp, go: `Description`) | Una descripción de lo que hace el agente. |
| `metadata` (csharp, go: `Metadata`) | Pares clave-valor arbitrarios para tu propio seguimiento. |
También puedes sobrescribir `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) y `skills` (csharp, go: `Skills`) para una sola sesión sin cambiar el agente. Una sobrescritura de `model` (csharp, go: `Model`) reemplaza por completo el objeto `model` (csharp, go: `Model`) del agente, por lo que el `effort` (csharp, go: `Effort`) propio del agente no se conserva. Para ejecutar la sesión con un nivel de esfuerzo específico, establece `effort` (csharp, go: `Effort`) dentro del objeto `model` (csharp, go: `Model`) de la sobrescritura. Consulta [Sobrescribir la configuración del agente para una sesión](https://platform.claude.com/docs/es/managed-agents/sessions#override-agent-configuration-for-a-session).
## Crear un agente
El siguiente ejemplo define un agente de programación que usa el modelo Claude Opus más reciente con acceso al conjunto de herramientas de agente predefinido. El conjunto de herramientas permite al agente escribir código, leer archivos, buscar en la web y más. Consulta la [referencia de herramientas de agente](https://platform.claude.com/docs/es/managed-agents/tools) para ver la lista completa de herramientas compatibles.
Los ejemplos usan curl, la CLI `ant` o uno de los SDK. Si aún no has configurado ninguno, el [inicio rápido](https://platform.claude.com/docs/es/managed-agents/quickstart#install-the-cli) cubre la instalación y la configuración del 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/es/cli-sdks-libraries/cli/apply) crea el agente a partir de `coding-assistant.md`, imprime su ID y lo registra en `claude-lock.json`. Haz commit de `claude-lock.json` para que el siguiente `ant apply` actualice este agente en lugar de crear uno 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"}]
)
```
La respuesta repite tu configuración y agrega los campos `id`, `type`, `version`, `created_at`, `updated_at` y `archived_at`, y completa con sus valores predeterminados los campos de `model` que omitas, como `effort`. El `version` comienza en 1 y se incrementa cada vez que una actualización cambia el 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
}
```
El `default_config` del conjunto de herramientas muestra su [política de permisos](https://platform.claude.com/docs/es/managed-agents/permission-policies) predeterminada, `always_allow`, que se aplica a menos que configures una.
Para usar Claude Opus 5.5, Claude Opus 5 o Claude Opus 4.8 con el [modo rápido](https://platform.claude.com/docs/es/build-with-claude/fast-mode), pasa `model` como un objeto, por ejemplo: `{"id": "claude-opus-5-5", "speed": "fast"}`. Consulta los [modelos compatibles](https://platform.claude.com/docs/es/build-with-claude/fast-mode#supported-models) en la página del modo rápido.
Para establecer el nivel de esfuerzo del modelo, pasa `model` como un objeto, por ejemplo: `{"id": "claude-opus-5-5", "effort": "high"}`. El campo `effort` acepta una cadena de nivel (`low`, `medium`, `high`, `xhigh` o `max`) o un objeto como `{"type": "high"}`. Consulta [Niveles de esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort#effort-levels) para saber qué hace cada nivel.
### Fijar la geo de inferencia
Al igual que `speed` (csharp, go: `Speed`) y `effort` (csharp, go: `Effort`), `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) se establece mediante la forma de objeto de `model` (csharp, go: `Model`): pasa `model` (csharp, go: `Model`) como un objeto y establece `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) junto con `id` (csharp, go: `ID`). El campo acepta `"us"` o `"global"`. Cuando no está establecido, cada solicitud al modelo sigue la geo de inferencia predeterminada del espacio de trabajo en el momento en que se atiende. Consulta [Residencia de datos](https://platform.claude.com/docs/es/manage-claude/data-residency) para conocer los controles de geo a nivel de espacio de trabajo y los precios.
El siguiente ejemplo fija un agente a la inferencia en EE. UU. e imprime el valor de `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) del objeto `model` (csharp, go: `Model`) del 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}"
```
Una fijación de `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) se valida contra los [`allowed_inference_geos`](https://platform.claude.com/docs/es/manage-claude/data-residency#workspace-level-restrictions) del espacio de trabajo cuando se guarda el agente, cuando se crea una sesión a partir de él y en cada turno que atiende la sesión. Si la lista de permitidos del espacio de trabajo se restringe de modo que una fijación ya no está permitida, no se pueden crear nuevas sesiones a partir del agente y las sesiones en ejecución rechazan turnos adicionales; las fijaciones nunca quedan exentas, porque los espacios de trabajo dependen de ellas para el cumplimiento normativo y la residencia de datos.
Establecer `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) en un modelo que no admite la fijación geográfica de inferencia devuelve un error 400; consulta [Disponibilidad de modelos](https://platform.claude.com/docs/es/manage-claude/data-residency#model-availability) para ver los modelos que sí la admiten. En una configuración `multiagent` (csharp, go: `Multiagent`), la fijación del agente y la fijación de cada agente incluido en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) o `workflows` (csharp, go: `Workflows`) deben tener todas el mismo valor o no estar establecidas; consulta [Orquestación multiagente](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration). Para cambiar o eliminar la fijación más adelante, actualiza el objeto `model` (csharp, go: `Model`) del agente; proporcionar `model` (csharp, go: `Model`) sin `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) la elimina, como se describe en [Semántica de actualización](https://platform.claude.com/docs/es/managed-agents/agent-setup#update-semantics).
## Actualizar un agente
Actualizar un agente genera una nueva versión cuando la configuración cambia. El campo `version` (csharp, go: `Version`) es opcional: proporciónalo para la concurrencia optimista (una discrepancia devuelve un 409), u omítelo para aplicar la actualización de forma incondicional (gana la última escritura). Las actualizaciones de agentes archivados se rechazan.
Con la CLI, edita el archivo del agente y vuelve a ejecutar `ant apply`; apply proporciona `version` por ti.
```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}"
```
El ejemplo anterior proporciona `version` a partir de la respuesta de creación, por lo que la actualización solo se aplica si nada más ha cambiado el agente desde que lo leíste. Para aplicar una actualización de forma incondicional, omite `version` de la solicitud:
```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 actualización
* **`version` (csharp, go: `Version`)** es opcional y debe ser al menos 1 cuando se proporciona. Cuando se proporciona, la solicitud devuelve un 409 si no coincide con la versión actual del agente, incluso cuando los campos que envías ya coinciden con los valores almacenados; vuelve a leer el agente y reintenta. Cuando se omite, la actualización se aplica de forma incondicional y la actualización más reciente reemplaza silenciosamente cualquier actualización concurrente, sin error para ninguno de los llamadores. Proporcionar `version` (csharp, go: `Version`) es el valor predeterminado recomendado para llamadores interactivos, y omitirlo es adecuado para bucles de aplicación declarativos, como un trabajo de CI que sincroniza definiciones de agentes registradas en el repositorio, donde el bucle es el propietario del agente.
* **Los campos omitidos se conservan.** Solo necesitas incluir los campos que quieres cambiar.
* **Los campos escalares** (`model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `name` (csharp, go: `Name`), `description` (csharp, go: `Description`)) se reemplazan con el nuevo valor. `system` (csharp, go: `System`; ruby: `system_`) y `description` (csharp, go: `Description`) se pueden borrar pasando `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.Null[string]()`; php: `requestOptions: ['extraBodyParams' => ['system' => null, 'description' => null]]`). `model` (csharp, go: `Model`) y `name` (csharp, go: `Name`) son obligatorios y no se pueden borrar. Dentro de un objeto `model` (csharp, go: `Model`) que proporciones, `effort` (csharp, go: `Effort`) es la única excepción: si el `id` (csharp, go: `ID`) del modelo no cambia, omitir `effort` (csharp, go: `Effort`) deja sin cambios el nivel de esfuerzo almacenado. Si cambias el `id` (csharp, go: `ID`) del modelo, un `effort` (csharp, go: `Effort`) omitido se restablece al valor predeterminado del nuevo modelo. Los demás campos de `model` (csharp, go: `Model`) se reemplazan junto con el objeto: proporcionar `model` (csharp, go: `Model`) sin `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) elimina la fijación de geo de inferencia del agente.
* **Los campos de arreglo** (`tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), `skills` (csharp, go: `Skills`)) se reemplazan por completo con el nuevo arreglo. Para borrar un campo de arreglo por completo, pasa `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.NullSlice[[]anthropic.BetaAgentUpdateParamsToolUnion]()`; php: `requestOptions: ['extraBodyParams' => ['mcp_servers' => null]]`) o un arreglo vacío.
* **`multiagent` (csharp, go: `Multiagent`)** se fusiona con el bloque almacenado nivel por nivel cuando la actualización mantiene el tipo `multiagent_20261001`. Una configuración que omitas conserva su valor almacenado, y una lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) que envíes reemplaza la lista almacenada. Cualquier otra actualización que envíe `multiagent` (csharp, go: `Multiagent`) reemplaza el bloque almacenado en su totalidad, y las configuraciones que omita toman sus valores predeterminados. Pasa `"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 borrar todo el bloque. Dentro del bloque, `null` restablece una configuración a su valor predeterminado, por lo que establecer `workflows` (csharp, go: `Workflows`) en `null` activa los flujos de trabajo dinámicos. Consulta [Activar los flujos de trabajo dinámicos](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
* **Los metadatos** se fusionan a nivel de clave. Las claves que proporcionas se agregan o actualizan. Las claves que omites se conservan. Para eliminar una clave específica, establece su valor en `null`.
* **Detección de operaciones sin efecto.** Si la actualización no produce ningún cambio respecto a la versión actual, no se crea una nueva versión y se devuelve la versión existente.
* **Las listas `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de otros agentes no se actualizan.** Los agentes que incluyen este agente en la lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) o `workflows` (csharp, go: `Workflows`) conservan la versión que quedó fijada cuando se crearon o cuando una actualización envió esa lista por última vez, incluso si la referencia omite `version` (csharp, go: `Version`). Para delegar a la nueva versión, [actualiza el agente que lo incluye](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#list-the-subagents) para que la lista haga referencia a la nueva versión.
La siguiente actualización borra la descripción, elimina la clave `team` de `metadata` (csharp, go: `Metadata`) y establece `workflows` (csharp, go: `Workflows`) en `null`, lo que activa los flujos de trabajo 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.
```
El archivo ya no tiene `description` ni la clave `team`, por lo que `ant apply` envía `null` para ellos. Eliminar una configuración dentro de `multiagent` conserva su valor almacenado, por lo que el archivo establece `workflows` en `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 es un map[string]string, así que envía el null para team como opción de la solicitud.
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 los argumentos null, así que pasa los null en 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 del agente
| Operación | Comportamiento |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Actualizar** | Genera una nueva versión del agente cuando la configuración cambia. |
| **Listar versiones** | Devuelve el historial completo de versiones para que puedas hacer seguimiento de los cambios a lo largo del tiempo. |
| **Archivar** | Hace que el agente sea de solo lectura. Las nuevas sesiones no pueden hacer referencia a él, pero las sesiones existentes siguen ejecutándose. |
### Listar versiones
Obtén el historial completo de versiones para hacer seguimiento de cómo ha cambiado un agente a lo largo del tiempo. Los resultados están paginados, y los ejemplos de SDK obtienen todas las páginas automáticamente.
```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
```
### Archivar un agente
Archivar hace que el agente sea de solo lectura y no se puede deshacer. Las sesiones existentes siguen ejecutándose, pero las nuevas sesiones no pueden hacer referencia al agente. La respuesta establece `archived_at` (java, php: `archivedAt`; csharp, go: `ArchivedAt`) en la marca de tiempo del archivado.
```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 pasos
Configura las herramientas disponibles para tu agente.
Adjunta a tu agente experiencia reutilizable basada en el sistema de archivos para flujos de trabajo específicos del dominio.
Crea una sesión para ejecutar tu agente y comenzar a ejecutar tareas.
Tipos de eventos, flags de la CLI del worker autoalojado, tipos de servidores MCP compatibles, límites de velocidad y pautas de marca para Claude Managed Agents.