---
title: Iniciar una sesión
url: https://platform.claude.com/docs/es/managed-agents/sessions
description: Crea una sesión para ejecutar tu agente y comenzar a ejecutar tareas.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

Una sesión es una instancia de agente dentro de un entorno. Cada sesión hace referencia a un [agente](https://platform.claude.com/docs/es/managed-agents/agent-setup) y a un [entorno](https://platform.claude.com/docs/es/managed-agents/environments) (ambos creados por separado), y mantiene el historial de conversación a lo largo de múltiples interacciones. Las sesiones siguen un ciclo de vida de dos pasos: primero [crea la sesión](https://platform.claude.com/docs/es/managed-agents/sessions#creating-a-session) y luego [envía un evento de usuario](https://platform.claude.com/docs/es/managed-agents/sessions#starting-the-session) para comenzar el trabajo. También puedes combinar ambos pasos en una sola llamada con [`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`)](https://platform.claude.com/docs/es/managed-agents/sessions#seed-the-session-with-initial-events).

## Crear una sesión

Una sesión requiere un ID de `agent` y un ID de `environment`. Los agentes son recursos versionados; pasar el ID de `agent` (csharp, go: `Agent`) como una cadena crea la sesión con la versión más reciente del agente.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID"
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id
  )
  ```
</CodeGroup>

Para fijar una sesión a una versión específica del agente, pasa un objeto. Esto te permite controlar exactamente qué versión se ejecuta y escalonar los despliegues de nuevas versiones de forma independiente.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": {"type": "agent", "id": "'"$AGENT_ID"'", "version": 1},
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent:
    type: agent
    id: $AGENT_ID
    version: 1
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  pinned_session = client.beta.sessions.create(
      agent={"type": "agent", "id": agent.id, "version": 1},
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const pinnedSession = await client.beta.sessions.create({
    agent: { type: "agent", id: agent.id, version: 1 },
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var pinnedSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentParams
      {
          Type = BetaManagedAgentsAgentParamsType.Agent,
          ID = agent.ID,
          Version = 1,
      },
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  pinnedSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
  			Type:    anthropic.BetaManagedAgentsAgentParamsTypeAgent,
  			ID:      agent.ID,
  			Version: anthropic.Int(1),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var pinnedSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentParams.builder()
          .type(BetaManagedAgentsAgentParams.Type.AGENT)
          .id(agent.id())
          .version(1)
          .build())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $pinnedSession = $client->beta->sessions->create(
      agent: ['type' => 'agent', 'id' => $agent->id, 'version' => 1],
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  pinned_session = client.beta.sessions.create(
    agent: {type: :agent, id: agent.id, version: 1},
    environment_id: environment.id
  )
  ```
</CodeGroup>

### Inicializar la sesión con eventos iniciales

Puedes crear una sesión e iniciar su trabajo en una sola llamada. `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) es un arreglo opcional de [eventos](https://platform.claude.com/docs/es/managed-agents/reference#event-types) iniciales que se envían a la sesión al crearla y se procesan en orden. Admite eventos `user.message` y [`user.define_outcome`](https://platform.claude.com/docs/es/managed-agents/define-outcomes), y acepta un máximo de 50 eventos. Una lista no vacía inicia el bucle del agente en la misma llamada: la sesión se crea directamente en el estado `running`, sin ninguna solicitud adicional.

El siguiente ejemplo crea una sesión con un único `user.message` en `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`):

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "initial_events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  initial_events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  seeded_session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      initial_events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  # initial_events no se devuelven en la respuesta de creación; léelos de nuevo
  # desde la lista de eventos de la sesión.
  for event in client.beta.sessions.events.list(seeded_session.id):
      if event.type == "user.message":
          for block in event.content:
              if block.type == "text":
                  print(f"Seeded event: {block.text}")
  ```

  ```typescript TypeScript
  const seededSession = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });

  // initial_events no se devuelven en la respuesta de creación; lista los
  // eventos de la sesión para leer de vuelta el mensaje sembrado.
  for await (const event of client.beta.sessions.events.list(seededSession.id)) {
    if (event.type === "user.message") {
      for (const block of event.content) {
        if (block.type === "text") {
          console.log(`Seeded event: ${block.text}`);
        }
      }
    }
  }
  ```

  ```csharp C#
  var seededSession = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      InitialEvents =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  // los initial_events no se devuelven en la respuesta de creación; léelos de vuelta
  // desde la lista de eventos de la sesión.
  var seededEvents = await client.Beta.Sessions.Events.List(seededSession.ID);
  await foreach (var sessionEvent in seededEvents.Paginate())
  {
      if (sessionEvent.TryPickUserMessage(out var userMessage))
      {
          foreach (var contentBlock in userMessage.Content)
          {
              if (contentBlock.TryPickBetaManagedAgentsTextBlock(out var textBlock))
              {
                  Console.WriteLine($"Seeded event: {textBlock.Text}");
              }
          }
      }
  }
  ```

  ```go Go
  seededSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	InitialEvents: []anthropic.BetaSessionNewParamsInitialEventUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  // initial_events no se devuelven en la respuesta de creación, así que lista los
  // eventos de la sesión para leer el user.message sembrado.
  seededEvents, err := client.Beta.Sessions.Events.List(ctx, seededSession.ID, anthropic.BetaSessionEventListParams{})
  if err != nil {
  	panic(err)
  }
  for _, event := range seededEvents.Data {
  	if event.Type != "user.message" {
  		continue
  	}
  	for _, contentBlock := range event.AsUserMessage().Content {
  		if contentBlock.Type == "text" {
  			fmt.Printf("Seeded event: %s\n", contentBlock.AsText().Text)
  		}
  	}
  }
  ```

  ```java Java
  var seededSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addInitialEvent(BetaManagedAgentsUserMessageEventParams.builder()
          .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
          .addTextContent("List the files in the working directory.")
          .build())
      .build());
  // initial_events no se devuelven en la respuesta de creación; lista los
  // eventos de la sesión para leer el user.message sembrado.
  for (var event : client.beta().sessions().events().list(seededSession.id()).autoPager()) {
      if (event.isUserMessage()) {
          for (var contentBlock : event.asUserMessage().content()) {
              if (contentBlock.isText()) {
                  IO.println("Seeded event: " + contentBlock.asText().text());
              }
          }
      }
  }
  ```

  ```php PHP
  $seededSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      initialEvents: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );

  // los initial_events no se devuelven en la respuesta de creación; léelos de nuevo
  // desde la lista de eventos de la sesión.
  $seededEvents = $client->beta->sessions->events->list($seededSession->id);
  foreach ($seededEvents->getItems() as $event) {
      if ($event->type === 'user.message') {
          echo "Seeded event: {$event->content[0]->text}\n";
      }
  }
  ```

  ```ruby Ruby
  seeded_session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )

  # los initial_events no se devuelven en la respuesta de creación; léelos desde
  # la lista de eventos de la sesión.
  client.beta.sessions.events.list(seeded_session.id).auto_paging_each do |event|
    next unless event.type == :"user.message"
    event.content.each do |block|
      puts "Seeded event: #{block.text}" if block.type == :text
    end
  end
  ```
</CodeGroup>

No se acepta ningún otro tipo de evento. Los eventos que responden a un turno del agente (`user.tool_confirmation`, `user.tool_result` y `user.custom_tool_result`) no se aceptan porque todavía no existe ningún turno del agente, y `user.interrupt` no se acepta porque no hay ningún turno que detener. A diferencia de `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) en un despliegue programado, los `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) de una sesión no aceptan `system.message`.

Cada evento en `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) se valida y se persiste antes de que se devuelva la respuesta de creación, en el orden de la lista, con un ID asignado por el servidor, exactamente como si lo hubieras publicado en el endpoint de [envío de eventos](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#send-events) inmediatamente después de la creación. Las reglas de contenido por evento también son las mismas que en ese endpoint. Una lista vacía equivale a omitir el campo. La validación es de todo o nada: si algún evento no supera la validación, se rechaza toda la solicitud y no se crea ninguna sesión.

La solicitud de creación se rechaza en los siguientes casos:

| Condición                                                                                                                                                           | Estado |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Más de un evento `user.define_outcome`                                                                                                                              | 400    |
| Un evento `user.define_outcome` sin `rubric`                                                                                                                        | 400    |
| Más de 100 [bloques de contenido `document`](https://platform.claude.com/docs/es/build-with-claude/files#document-blocks) provenientes de archivos en toda la lista | 400    |
| Un cuerpo de solicitud de más de 32 MB                                                                                                                              | 413    |

Un evento `user.define_outcome` en `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) se acepta en las mismas condiciones que al enviarlo a una sesión existente; consulta [Definir resultados](https://platform.claude.com/docs/es/managed-agents/define-outcomes).

### Sobrescribir la configuración del agente para una sesión

Puedes pasar `agent` (csharp, go: `Agent`) de tres formas: una cadena con el ID del agente, un objeto de versión fijada (`type: "agent"`) o un objeto de sobrescrituras. La forma de sobrescrituras cambia partes de la configuración del agente para una sola sesión. Úsala para probar un modelo diferente u otorgar una herramienta adicional en una sesión sin versionar el agente. Para la forma de sobrescrituras, establece `type` en `agent_with_overrides` y pasa el `id` (csharp, go: `ID`) del agente y, opcionalmente, una `version` (csharp, go: `Version`) (omite `version` (csharp, go: `Version`) para usar la versión más reciente del agente). Luego incluye cualquiera de `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) o `skills` (csharp, go: `Skills`) con los valores que debe usar la sesión.

Cada campo sobrescribible sigue las mismas tres reglas:

* **Omitir el campo:** La sesión hereda el valor de la versión del agente a la que hace referencia.

* **Establecer el campo en `null`, o en un arreglo vacío para los campos de lista:** La sesión se ejecuta con ese campo vacío. Esta regla se aplica por completo a `system` (csharp, go: `System`; ruby: `system_`) y `skills` (csharp, go: `Skills`). Hay tres excepciones:

  * `model` nunca se puede vaciar. Una sesión siempre necesita un modelo, por lo que `model: null` devuelve un error 400 `agent_model_required`.
  * Vaciar `tools` devuelve un error 400 cuando las `skills` (csharp, go: `Skills`) efectivas de la sesión no están vacías, porque las skills requieren la herramienta `read`. De lo contrario, `tools: null` y `tools: []` vacían el campo.
  * Vaciar `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) devuelve un error 400 cuando las `tools` (csharp, go: `Tools`) efectivas de la sesión todavía contienen un `mcp_toolset` que hace referencia a uno de los servidores del agente. Sobrescribe `tools` (csharp, go: `Tools`) en la misma solicitud para eliminar esas entradas `mcp_toolset` y luego vacía `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).

* **Establecer el campo en un valor:** El valor reemplaza por completo el valor del agente. Las sobrescrituras nunca se combinan con la configuración del agente, por lo que una sobrescritura de `tools` (csharp, go: `Tools`) debe enumerar todas las herramientas que debe tener la sesión. Del mismo modo, 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. Un nivel que el modelo no admite devuelve un error 400, y una sobrescritura de `model` (csharp, go: `Model`) sin `effort` (csharp, go: `Effort`) se ejecuta con el nivel de esfuerzo predeterminado de ese modelo.

Las sobrescrituras se aplican solo a la sesión que creas. No modifican el recurso del agente ni crean una nueva versión del agente, por lo que otras sesiones que hacen referencia al mismo agente no se ven afectadas.

En la respuesta, el objeto `agent` (csharp, go: `Agent`) refleja la configuración con la que se ejecuta la sesión después de aplicar las sobrescrituras. Su `id` (csharp, go: `ID`) y su `version` (csharp, go: `Version`) siguen identificando el agente y la versión a los que se aplican las sobrescrituras. Esto te permite rastrear una sesión hasta su agente base.

El siguiente ejemplo inicia una sesión que sobrescribe el modelo y vacía la "system prompt" (indicación del sistema):

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-sonnet-5-5"},
        "system": null
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # The response's `agent` is the resolved snapshot: each override replaces that
  # field for this session only, and the agent resource keeps its id and version.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-sonnet-5-5
    system: null
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  override_session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          "model": {"id": "claude-sonnet-5-5"},
          "system": None,  # clear the agent's system prompt for this session
      },
      environment_id=environment.id,
  )
  # El agente de la respuesta es el snapshot resuelto con las anulaciones aplicadas.
  print(f"Model: {override_session.agent.model.id}")
  print(f"System: {override_session.agent.system}")
  ```

  ```typescript TypeScript
  const overrideSession = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      model: { id: "claude-sonnet-5-5" },
      system: null // clear the agent's system prompt for this session
    },
    environment_id: environment.id
  });
  // El agente de la respuesta es el snapshot resuelto con las anulaciones aplicadas.
  console.log(`Model: ${overrideSession.agent.model.id}`);
  console.log(`System: ${overrideSession.agent.system}`);
  ```

  ```csharp C#
  var overrideSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeSonnet5_5,
          },
          System = null, // clear the agent's system prompt for this session
      },
      EnvironmentID = environment.ID,
  });
  // El agente de la respuesta es el snapshot resuelto con las anulaciones aplicadas.
  Console.WriteLine($"Model: {overrideSession.Agent.Model.ID.Raw()}");
  Console.WriteLine($"System: {overrideSession.Agent.System ?? "null"}");
  ```

  ```go Go
  overrideSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID: anthropic.BetaManagedAgentsModelClaudeSonnet5_5,
  			},
  			// Borra la indicación del sistema del agente para esta sesión.
  			System: param.Null[string](),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  // El agente de la respuesta es el snapshot resuelto con las anulaciones aplicadas.
  fmt.Printf("Model: %s\n", overrideSession.Agent.Model.ID)
  fmt.Printf("System: %q\n", overrideSession.Agent.System)
  ```

  ```java Java
  var overrideSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_SONNET_5_5)
              .build())
          .system((String) null) // clear the agent's system prompt for this session
          .build())
      .environmentId(environment.id())
      .build());
  // El agente de la respuesta es el snapshot resuelto con las anulaciones aplicadas.
  IO.println("Model: " + overrideSession.agent().model().id());
  IO.println("System: " + overrideSession.agent().system().orElse("null"));
  ```

  ```php PHP
  $overrides = BetaManagedAgentsAgentWithOverridesParams::with(
      id: $agent->id,
      type: 'agent_with_overrides',
      model: ['id' => 'claude-sonnet-5-5'],
  );
  // Borra la indicación del sistema de esta sesión. El acceso por array es esencial aquí:
  // create() elimina los null de los arrays sin procesar y ::with() trata los argumentos null como omitidos.
  $overrides['system'] = null;

  $overrideSession = $client->beta->sessions->create(
      agent: $overrides,
      environmentID: $environment->id,
  );
  // El agente de la respuesta es el snapshot resuelto con las anulaciones aplicadas.
  echo "Model: {$overrideSession->agent->model->id}\n";
  echo 'System: ' . ($overrideSession->agent->system ?? 'null') . "\n";
  ```

  ```ruby Ruby
  # La anulación de la indicación del sistema es `system_` (guion bajo final) porque
  # `system` a secas es Kernel#system de Ruby. Establecerlo en nil borra la indicación.
  override_session = client.beta.sessions.create(
    agent: Anthropic::Beta::BetaManagedAgentsAgentWithOverridesParams.new(
      type: :agent_with_overrides,
      id: agent.id,
      model: {id: "claude-sonnet-5-5"},
      system_: nil
    ),
    environment_id: environment.id
  )
  # El agente de la respuesta es la instantánea resuelta con las anulaciones aplicadas.
  puts "Model: #{override_session.agent.model.id}"
  puts "System: #{override_session.agent.system_.inspect}"
  ```
</CodeGroup>

#### Fijar la geografía de inferencia para una sesión

Dado que una sobrescritura de `model` (csharp, go: `Model`) reemplaza por completo el objeto `model` (csharp, go: `Model`) del agente, también establece o elimina la fijación de la [geografía de inferencia](https://platform.claude.com/docs/es/manage-claude/data-residency) del modelo para la sesión: una sobrescritura que incluye `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) fija la geografía que atiende las solicitudes al modelo de la sesión, y una que lo omite elimina la fijación del agente, de modo que la sesión sigue el `default_inference_geo` del espacio de trabajo. El valor sobrescrito se valida contra los `allowed_inference_geos` del espacio de trabajo cuando se crea la sesión.

El siguiente ejemplo inicia una sesión a partir de un agente cuyo modelo no tiene una geografía fijada, fija las solicitudes al modelo de la sesión a la inferencia en EE. UU. incluyendo `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) en la sobrescritura de `model` (csharp, go: `Model`), e imprime el valor devuelto en `agent.model` (csharp, go: `Agent.Model`) de la respuesta:

<CodeGroup>
  ```bash cURL
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"}
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-opus-5-5
      inference_geo: us
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          # Reemplaza el `model` del agente por completo: vuelve a indicar `id`, agrega `inference_geo` para fijar.
          "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
      },
      environment_id=environment.id,
  )
  print(f"Inference geo: {session.agent.model.inference_geo}")
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      // Reemplaza el `model` del agente por completo: vuelve a indicar `id`, agrega `inference_geo` para fijar.
      model: { id: "claude-opus-5-5", inference_geo: "us" }
    },
    environment_id: environment.id
  });
  console.log(`Inference geo: ${session.agent.model.inference_geo}`);
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          // Reemplaza el `model` del agente por completo: vuelve a indicar `id`, añade `inference_geo` para fijar.
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeOpus5_5,
              InferenceGeo = "us",
          },
      },
      EnvironmentID = environment.ID,
  });
  Console.WriteLine($"Inference geo: {session.Agent.Model.InferenceGeo}");
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			// Reemplaza el `model` del agente por completo: repite `id`, añade `inference_geo` para fijar.
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID:           anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  				InferenceGeo: anthropic.String("us"),
  			},
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  fmt.Printf("Inference geo: %s\n", session.Agent.Model.InferenceGeo)
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          // Reemplaza el `model` del agente por completo: vuelve a indicar `id`, añade `inference_geo` para fijar.
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
              .inferenceGeo("us")
              .build())
          .build())
      .environmentId(environment.id())
      .build());
  IO.println("Inference geo: " + session.agent().model().inferenceGeo().orElseThrow());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: BetaManagedAgentsAgentWithOverridesParams::with(
          id: $agent->id,
          type: 'agent_with_overrides',
          // Reemplaza el `model` del agente por completo: vuelve a indicar `id`, agrega `inference_geo` para fijar.
          model: BetaManagedAgentsModelConfigParams::with(
              id: 'claude-opus-5-5',
              inferenceGeo: 'us',
          ),
      ),
      environmentID: $environment->id,
  );
  echo "Inference geo: {$session->agent->model->inferenceGeo}\n";
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: {
      type: :agent_with_overrides,
      id: agent.id,
      # Reemplaza el `model` del agente por completo: vuelve a indicar `id`, agrega `inference_geo` para fijar.
      model: {id: "claude-opus-5-5", inference_geo: "us"}
    },
    environment_id: environment.id
  )
  puts "Inference geo: #{session.agent.model.inference_geo}"
  ```
</CodeGroup>

<Tip>
  El agente define cómo se comporta Claude dentro de la sesión, incluidos el modelo, la indicación del sistema, las herramientas y los servidores MCP. Consulta [Define tu agente](https://platform.claude.com/docs/es/managed-agents/agent-setup) para obtener más detalles.
</Tip>

### Establecer un presupuesto de sesión

Para limitar lo que puede gastar una sesión, pasa el objeto opcional `budget` (csharp, go: `Budget`) al crearla. Un presupuesto es un límite estricto sobre el costo de lista de la sesión: la plataforma calcula el precio de todo lo que consume la sesión según las tarifas de lista públicas, y la sesión deja de emitir nuevas solicitudes al modelo una vez que ese total acumulado alcanza `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`). Establece `type` (csharp, go: `Type`) en `limit` y asigna a `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) un `amount` (csharp, go: `Amount`) y una `currency` (csharp, go: `Currency`). `amount` (csharp, go: `Amount`) es un número entero de centavos de dólar estadounidense escrito como cadena, como `"125"` para $1.25. La API acepta una cadena en lugar de un número para que nunca se aplique redondeo de punto flotante. `USD` es la única moneda admitida actualmente. Cuando la sesión alcanza el límite, se pausa y queda inactiva con el motivo de detención `budget_reached`. El límite se aplica entre solicitudes al modelo, por lo que la solicitud que lo supera termina primero y el costo de lista final de la sesión puede quedar [ligeramente por encima del límite](https://platform.claude.com/docs/es/managed-agents/budgets#when-a-session-reaches-its-budget). Un presupuesto solo se puede adjuntar al crear la sesión: puedes [cambiarlo o eliminarlo](https://platform.claude.com/docs/es/managed-agents/session-operations#updating-the-session-budget) más adelante, pero no puedes agregar uno a una sesión creada sin él.

El siguiente ejemplo crea una sesión con un presupuesto de $1.25:

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "budget": {
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"}
      }
    }'
  ```

  ```bash CLI
  # Mantén el monto entre comillas para que se envíe como cadena, no como número.
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID" \
    --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}'
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      budget={
          "type": "limit",
          "max_list_cost": {"amount": "125", "currency": "USD"},
      },
  )
  print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: { amount: "125", currency: "USD" }
    }
  });
  console.log(session.id, session.budget?.max_list_cost.amount); // sesn_01... 125
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Budget = new()
      {
          Type = BetaManagedAgentsBudgetLimitType.Limit,
          MaxListCost = new() { Amount = "125", Currency = BetaCurrency.Usd },
      },
  });
  Console.WriteLine($"{session.ID} {session.Budget?.MaxListCost.Amount}");  // sesn_01... 125
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
  		Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
  		MaxListCost: anthropic.BetaMonetaryAmountParam{
  			Amount:   "125",
  			Currency: anthropic.BetaCurrencyUsd,
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(session.ID, session.Budget.MaxListCost.Amount) // sesn_01... 125
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .budget(BetaManagedAgentsBudgetLimit.builder()
          .type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
          .maxListCost(BetaMonetaryAmount.builder()
              .amount("125")
              .currency(BetaCurrency.USD)
              .build())
          .build())
      .build());
  IO.println(session.id() + " " + session.budget().orElseThrow().maxListCost().amount());  // sesn_01... 125
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      budget: [
          'type' => 'limit',
          'max_list_cost' => ['amount' => '125', 'currency' => 'USD'],
      ],
  );
  echo "{$session->id} {$session->budget->maxListCost->amount}\n"; // sesn_01... 125
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: {amount: "125", currency: "USD"}
    }
  )
  puts "#{session.id} #{session.budget.max_list_cost.amount}" # sesn_01... 125
  ```
</CodeGroup>

Consulta [Presupuestos de sesión](https://platform.claude.com/docs/es/managed-agents/budgets) para saber cómo funciona la aplicación del límite, qué cuenta para el costo de lista y cómo se comportan los presupuestos en sesiones multiagente.

## Autenticación de MCP mediante bóvedas

Si tu agente usa herramientas MCP que requieren autenticación, pasa `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) al crear la sesión para hacer referencia a una bóveda que contenga credenciales OAuth almacenadas. Anthropic gestiona la renovación de tokens en tu nombre. Consulta [Autenticarse con bóvedas](https://platform.claude.com/docs/es/managed-agents/vaults) para saber cómo crear bóvedas y registrar credenciales.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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 '{
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "vault_ids": ["'"$VAULT_ID"'"]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  vault_ids:
    - $VAULT_ID
  YAML
  ```

  ```python Python
  vault_session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      vault_ids=[vault.id],
  )
  ```

  ```typescript TypeScript
  const vaultSession = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  });
  ```

  ```csharp C#
  var vaultSession = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      VaultIds = [vault.ID],
  });
  ```

  ```go Go
  vaultSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	VaultIDs:      []string{vault.ID},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var vaultSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addVaultId(vault.id())
      .build());
  ```

  ```php PHP
  $vaultSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      vaultIDs: [$vault->id],
  );
  ```

  ```ruby Ruby
  vault_session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  )
  ```
</CodeGroup>

## Iniciar la sesión

Crear una sesión sin `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) registra la sesión, pero no inicia ningún trabajo; el sandbox del entorno comienza a aprovisionarse en cuanto se crea la sesión, por lo que la primera llamada a una herramienta no tiene que esperarlo. Para delegar una tarea, envía eventos a la sesión usando un [evento de usuario](https://platform.claude.com/docs/es/managed-agents/reference#event-types). Para proporcionar el primer evento en la solicitud de creación, consulta [Inicializar la sesión con eventos iniciales](https://platform.claude.com/docs/es/managed-agents/sessions#seed-the-session-with-initial-events). La sesión actúa como una máquina de estados que registra el progreso mientras los eventos impulsan la ejecución real.

<CodeGroup>
  ```bash cURL
  curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
    -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 '{
      "events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions:events send \
    --session-id "$SESSION_ID" <<'YAML'
  events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  client.beta.sessions.events.send(
      session.id,
      events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  await client.beta.sessions.events.send(session.id, {
    events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });
  ```

  ```csharp C#
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  ```

  ```go Go
  if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  }); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().sessions().events().send(
      session.id(),
      EventSendParams.builder()
          .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
              .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
              .addTextContent("List the files in the working directory.")
              .build())
          .build());
  ```

  ```php PHP
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );
  ```

  ```ruby Ruby
  client.beta.sessions.events.send_(
    session.id,
    events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )
  ```
</CodeGroup>

Consulta [Flujo de eventos de la sesión](https://platform.claude.com/docs/es/managed-agents/events-and-streaming) para saber cómo hacer "streaming" (streaming) de las respuestas del agente y gestionar las confirmaciones de herramientas.

Consulta [Estados de la sesión](https://platform.claude.com/docs/es/managed-agents/session-operations#session-statuses) para conocer los estados por los que pasa una sesión.

## Próximos pasos

<CardGroup cols={3}>
  <Card title="Operaciones de sesión" icon="settings" href="https://platform.claude.com/docs/es/managed-agents/session-operations">
    Recupera, enumera, actualiza, archiva y elimina sesiones de Claude Managed Agents.
  </Card>

  <Card title="Flujo de eventos de la sesión" icon="lightning" href="https://platform.claude.com/docs/es/managed-agents/events-and-streaming">
    Envía eventos, haz streaming de respuestas e interrumpe o redirige tu sesión a mitad de la ejecución.
  </Card>

  <Card title="Despliegues programados" icon="arrows-clockwise" href="https://platform.claude.com/docs/es/managed-agents/scheduled-deployments">
    Crea y gestiona despliegues con la API de Claude: ejecuta un agente según una programación cron recurrente e inspecciona su historial de ejecuciones.
  </Card>
</CardGroup>