Iniciar una sesión

Una sesión es una instancia de agente en ejecución dentro de un entorno. Cada sesión hace referencia a un agente y un entorno (ambos creados por separado), y mantiene el historial de conversación en múltiples interacciones.

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.

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

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

Autenticación MCP a través de bóvedas

Si tu agente utiliza herramientas MCP que requieren autenticación, pasa vault_ids en la creación de la sesión para hacer referencia a una bóveda que contiene credenciales OAuth almacenadas. Anthropic gestiona la renovación de tokens en tu nombre. Consulta Autenticar 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 aprovisiona el entorno y el agente 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.

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

Consulta Eventos y transmisión para saber cómo transmitir las respuestas del agente y manejar las confirmaciones de herramientas.

Estados de la sesión

Las sesiones avanzan a través de estos estados:

Otras operaciones de sesión

Recuperar una sesión

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

Listar sesiones

for session in client.beta.sessions.list():
    print(f"{session.id}: {session.status}")

Archivar una sesión

Archiva una sesión para evitar que se envíen nuevos eventos mientras se preserva su historial:

client.beta.sessions.archive(session.id)

Eliminar una sesión

Elimina una sesión para eliminar permanentemente su registro, eventos y contenedor asociado. Una sesión running no puede ser eliminada; envía un evento de interrupción si necesitas eliminarla inmediatamente.

Los archivos, almacenes de memoria, entornos y agentes son recursos independientes y no se ven afectados por la eliminación de la sesión.

client.beta.sessions.delete(session.id)