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 y luego envía un evento de usuario para comenzar el trabajo. También puedes combinar ambos pasos en una sola llamada con 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 como una cadena crea la sesión con la versión más reciente del agente.

session = client.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 escalonar los despliegues de nuevas versiones de forma independiente.

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

Inicializar la sesión con eventos iniciales

Puedes crear una sesión e iniciar su trabajo en una sola llamada. initial_events es un arreglo opcional de eventos iniciales que se envían a la sesión al crearla y se procesan en orden. Admite eventos user.message y user.define_outcome, 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:

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}")

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 en un despliegue programado, los initial_events de una sesión no aceptan system.message.

Cada evento en initial_events 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 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:

Un evento user.define_outcome en initial_events se acepta en las mismas condiciones que al enviarlo a una sesión existente; consulta Definir resultados.

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 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 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 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 y 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 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 devuelve un error 400 cuando las tools efectivas de la sesión todavía contienen un mcp_toolset que hace referencia a uno de los servidores del agente. Sobrescribe tools en la misma solicitud para eliminar esas entradas mcp_toolset y luego vacía mcp_servers.
• 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 enumerar todas las herramientas que debe tener la sesión. Del mismo modo, una sobrescritura de model reemplaza por completo el objeto model del agente, por lo que el effort propio del agente no se conserva. Para ejecutar la sesión con un nivel de esfuerzo específico, establece effort dentro del objeto model de la sobrescritura. Un nivel que el modelo no admite devuelve un error 400, y una sobrescritura de model sin 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 refleja la configuración con la que se ejecuta la sesión después de aplicar las sobrescrituras. Su id y su 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):

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}")

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

Dado que una sobrescritura de model reemplaza por completo el objeto model del agente, también establece o elimina la fijación de la geografía de inferencia del modelo para la sesión: una sobrescritura que incluye inference_geo 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 en la sobrescritura de model, e imprime el valor devuelto en agent.model de la respuesta:

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}")

Establecer un presupuesto de sesión

Para limitar lo que puede gastar una sesión, pasa el objeto opcional 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. Establece type en limit y asigna a max_list_cost un amount y una currency. 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. Un presupuesto solo se puede adjuntar al crear la sesión: puedes cambiarlo o eliminarlo 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:

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

Consulta Presupuestos de sesión 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 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 para saber cómo crear bóvedas y registrar credenciales.

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

Iniciar la sesión

Crear una sesión sin initial_events 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. Para proporcionar el primer evento en la solicitud de creación, consulta Inicializar la sesión con eventos iniciales. La sesión actúa como una máquina de estados que registra el progreso mientras los eventos impulsan la ejecución real.

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

Consulta Flujo de eventos de la sesión para saber cómo hacer "streaming" (streaming) de las respuestas del agente y gestionar las confirmaciones de herramientas.

Consulta Estados de la sesión para conocer los estados por los que pasa una sesión.

Próximos pasos