---
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
  zdr:
    eligibility: not-eligible
    note: No es elegible para ZDR, excepto Managed Agents autoalojado. Las sesiones son recursos con estado; las transcripciones persisten hasta que las eliminas.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed): beta
---

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 de ID de 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` (csharp, go: `Speed`), `effort` (csharp, go: `Effort`) e `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`); 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 [Herramientas](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 el SDK. Si aún no has configurado ninguno, el [inicio rápido](https://platform.claude.com/docs/es/managed-agents/quickstart#before-you-begin) cubre la instalación y la configuración del cliente.

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "Coding Assistant",
      "model": "claude-opus-5-5",
      "system": "You are a helpful coding agent.",
      "tools": [{"type": "agent_toolset_20260401"}]
    }'
  ```

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

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

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

    [`ant apply`](https://platform.claude.com/docs/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.
  </CodeGroupItem>

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

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

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

  ```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{},
  	}},
  })
  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().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(),
      ],
  );
  ```

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

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.

<Tip>
  Para usar el [modo rápido](https://platform.claude.com/docs/es/build-with-claude/fast-mode), pasa `model` (csharp, go: `Model`) como un objeto, por ejemplo: `{"id": "claude-opus-5-5", "speed": "fast"}`. El modo rápido en Claude Opus 4.8 está obsoleto. 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 ver los modelos que lo admiten en Claude Managed Agents.
</Tip>

<Tip>
  Para establecer el nivel de esfuerzo del modelo, pasa `model` (csharp, go: `Model`) como un objeto, por ejemplo: `{"id": "claude-opus-5-5", "effort": "high"}`. El campo `effort` (csharp, go: `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.
</Tip>

### 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. La respuesta incluye el valor de `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) en el objeto `model` (csharp, go: `Model`) del agente:

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "Geo-pinned assistant",
      "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
      "system": "You are a helpful assistant."
    }'
  ```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "version": '"$AGENT_VERSION"',
      "system": "You are a helpful coding agent. Always write tests."
    }'
  ```

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

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

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

    Edita el archivo del agente y vuelve a ejecutar `ant apply`. El comando proporciona `version` por ti.
  </CodeGroupItem>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

El ejemplo anterior proporciona `version` (csharp, go: `Version`), por lo que la actualización solo se aplica si el agente sigue en esa versión. Para aplicar una actualización de forma incondicional, omite `version` (csharp, go: `Version`) de la solicitud:

<CodeGroup>
  ```bash cURL
  curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "description": "Writes and reviews code."
    }'
  ```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### 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:

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "description": null,
      "metadata": {"team": null},
      "multiagent": {"type": "multiagent_20261001", "workflows": null}
    }'
  ```

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

    <File filename="code-reviewer.md">
      ```markdown
      ---
      name: Code Reviewer
      model: claude-opus-5-5
      tools:
        - type: agent_toolset_20260401
      metadata:
        owner: docs
      multiagent:
        type: multiagent_20261001
        workflows: null
      ---

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

    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`.
  </CodeGroupItem>

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

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

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

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

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

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

  ```go Go
  // Metadata 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}"
  ```
</CodeGroup>

## 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 el SDK puede obtener todas las páginas por ti.

<CodeGroup>
  ```bash cURL
  curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

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

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

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

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

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

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

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

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

### 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.

<CodeGroup>
  ```bash cURL
  curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

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

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

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

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

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

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

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

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

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

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

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Herramientas" icon="tool" href="https://platform.claude.com/docs/es/managed-agents/tools">
    Configura las herramientas disponibles para tu agente.
  </Card>

  <Card title="Skills" icon="graduation-cap" href="https://platform.claude.com/docs/es/managed-agents/skills">
    Adjunta a tu agente experiencia reutilizable basada en el sistema de archivos para flujos de trabajo específicos del dominio.
  </Card>

  <Card title="Iniciar una sesión" icon="play" href="https://platform.claude.com/docs/es/managed-agents/sessions">
    Crea una sesión para ejecutar tu agente y empezar a ejecutar tareas.
  </Card>

  <Card title="Referencia" icon="book" href="https://platform.claude.com/docs/es/managed-agents/reference">
    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.
  </Card>
</CardGroup>

## Disponibilidad

Estado de Configuraciones de agentes: en beta en todos los modelos.

### Compatibilidad con la API

#### [Managed Agents](https://platform.claude.com/docs/es/managed-agents/overview)

* Disponibilidad: Disponible

| Estado | Plataformas en la nube | Modelos |
| ----- | ----- | ----- |
| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed) | [Todos los modelos](https://platform.claude.com/docs/es/models/overview) |

### Encabezados beta requeridos

[Descripción general de los encabezados beta](https://platform.claude.com/docs/es/api/beta-headers)

Los encabezados beta te permiten acceder a funciones experimentales y nuevas capacidades de los modelos antes de que formen parte de la API estándar.

* `managed-agents-2026-04-01`

### Manejo de datos

[Descripción general del manejo de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention#feature-eligibility)

| Elemento | Retención de datos cero | HIPAA |
| ----- | ----- | ----- |
| Estado | No elegible | No elegible |
| Detalles | No es elegible para ZDR, excepto Managed Agents autoalojado. Las sesiones son recursos con estado; las transcripciones persisten hasta que las eliminas. [Más información](https://platform.claude.com/docs/es/managed-agents/self-hosted-data-and-access#how-long-data-is-kept) | No es elegible para HIPAA. Se aplica a todas las subfunciones de Managed Agents. |

Endpoints aplicables:

* `/v1/agents`
* `/v1/sessions`
* `/v1/environments`
