Iniciar una sesión

Una sesión es una instancia de agente dentro de un entorno. Cada sesión hace referencia a un agente y a un entorno (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 para aprovisionar su sandbox, luego envía un evento de usuario para comenzar el trabajo.



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 como una cadena inicia la sesión con la versión más reciente del agente.

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

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 preparar despliegues de nuevas versiones de forma independiente.

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



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

Puedes pasar agent de tres formas: una cadena con el ID del agente, un objeto de versión fija (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 o conceder 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 del agente y opcionalmente una version (omite version para usar la versión más reciente del agente). Luego incluye cualquiera de model, system, tools, mcp_servers o skills con los valores que la sesión debe usar.

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 campos de lista: La sesión se ejecuta con ese campo vacío. Esta regla se aplica por completo a system, mcp_servers y skills. Hay dos 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 el valor efectivo de skills de la sesión no está vacío, porque las skills requieren la herramienta read. De lo contrario, tools: null y tools: [] vacían el campo.
• 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 debe listar todas las herramientas que la sesión debe tener.

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 refleja la configuración con la que se ejecuta la sesión después de aplicar las sobrescrituras. Su id y 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 `agent` de la respuesta es el snapshot resuelto: cada override reemplaza ese
# campo solo para esta sesión, y el recurso de agente conserva su id y versión.
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML



Autenticación de MCP mediante vaults

Si tu agente usa herramientas MCP que requieren autenticación, pasa vault_ids al crear la sesión para hacer referencia a un vault que contenga credenciales OAuth almacenadas. Anthropic gestiona la actualización de tokens en tu nombre. Consulta Autenticar con vaults para saber cómo crear vaults y registrar credenciales.

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



Iniciar la sesión

Crear una sesión aprovisiona el sandbox del entorno pero no inicia ningún trabajo. Para delegar una tarea, envía eventos a la sesión usando un evento de usuario. La sesión actúa como una máquina de estados que rastrea el progreso mientras los eventos impulsan la ejecución real.

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

Consulta Flujo de eventos de sesión para saber cómo hacer streaming de las respuestas del agente y manejar las confirmaciones de herramientas.

Consulta Estados de sesión para conocer los estados por los que pasa una sesión, y Operaciones de sesión para recuperar, listar, actualizar, archivar y eliminar sesiones.

Para crear sesiones automáticamente según un calendario recurrente, consulta Despliegues programados.