Operaciones de sesión

Una vez que existe una sesión, usa estas operaciones para leerla, actualizarla, archivarla o eliminarla. Consulta Iniciar una sesión para crear una sesión y enviarle trabajo.

Estados de la sesión

Las sesiones avanzan a través de estos estados. Consulta Iniciar una sesión para conocer el ciclo de vida de la sesión.

Actualizar la configuración del agente

Puedes actualizar agent.tools y agent.mcp_servers de una sesión, incluidas las políticas de permisos y la configuración web por herramienta, como los filtros de dominio, a mitad de la sesión sin crear una nueva versión del agente. Las actualizaciones son locales a la sesión y no se propagan de vuelta al agente subyacente. Los valores actualizados de allowed_domains y blocked_domains se aplican durante el resto de la sesión.

Solo tools y mcp_servers del agente pueden cambiar después de crear una sesión. Para ejecutar una sesión con valores de model, system o skills distintos de los del agente, usa anulaciones de la configuración del agente al crear la sesión. La configuración del modelo del agente, incluida su fijación de inference_geo, tampoco puede cambiar a mitad de la sesión: establece la fijación al guardar el agente, o establécela o elimínala para una sola sesión con una anulación de model al crearla. El campo system configurado del agente es fijo durante toda la vida de la sesión. En los modelos que lo admiten, aún puedes agregar orientación a nivel de sistema a mitad de la sesión enviando un evento system.message.

La semántica de una actualización de tools o mcp_servers es de reemplazo completo: el arreglo proporcionado es el nuevo valor. Para conservar las entradas existentes, haz un GET de la sesión, modifica el arreglo y envíalo de vuelta con POST.

La sesión debe estar en idle para actualizar el agente. Para actualizar el agente mientras la sesión se está ejecutando, envía un evento user.interrupt por sí solo y espera a que la sesión pase a idle. Si hay una ejecución de flujo de trabajo abierta, ya sea en ejecución o en pausa, la actualización devuelve un error 400, incluso cuando la sesión está en idle. Una interrupción no finaliza una ejecución, por lo que la actualización sigue fallando después de interrumpir la sesión. Envía un user.message que le pida al agente detener sus ejecuciones, o espera hasta que todas las ejecuciones hayan finalizado.

client.beta.sessions.update(
    session.id,
    agent={
        "tools": [
            {"type": "agent_toolset_20260401"},
            {"type": "mcp_toolset", "mcp_server_name": "linear"},
        ],
        "mcp_servers": [
            {"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}
        ],
    },
)

Actualizar el presupuesto de la sesión

Una sesión creada con un presupuesto acepta dos tipos de actualización del presupuesto: reemplazar el límite con un nuevo max_list_cost, y eliminarlo pasando budget=None. Ambas reanudan automáticamente el trabajo que se pausó cuando la sesión alcanzó su límite. Un límite de reemplazo puede ser mayor o menor que el actual, pero debe ser estrictamente mayor que el costo de lista consumido por la sesión, y la eliminación es irreversible: un budget no nulo solo se acepta en una sesión que actualmente tiene uno, por lo que no puedes volver a agregar un presupuesto eliminado ni agregar uno a una sesión creada sin él. Consulta Presupuestos de sesión para ver ejemplos de solicitudes, los comportamientos de error y qué cuenta para el costo de lista.

Recuperar una sesión

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

Listar sesiones

Los resultados de GET /v1/sessions están paginados. Usa el parámetro de consulta limit para controlar el tamaño de la página. Cada respuesta incluye un cursor next_page; pásalo como el parámetro page en la siguiente solicitud para obtener la página siguiente. next_page es null cuando no hay más resultados.

Para retroceder una página, pasa prev_page como el parámetro page. prev_page es null cuando estás en la primera página.

Un cursor page es opaco y codifica el order de la solicitud que lo produjo. El parámetro de consulta order establece la dirección de ordenamiento de los resultados, asc o desc por fecha de creación; el valor predeterminado es desc (los más recientes primero). Reutilizar un cursor con un order diferente devuelve un error 400, al igual que cambiar un filtro created_at de modo que excluya la posición del cursor. Otros parámetros de consulta, incluidos los filtros restantes y limit, pueden cambiar entre solicitudes paginadas. Para conocer los campos de paginación compartidos entre los endpoints de listado, consulta Paginación.

# Establece `limit` bajo para que los resultados abarquen más de una página.
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# `prev_page` es None en la primera página; `next_page` es None en la última.
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# Pasa `next_page` de vuelta como `page` para obtener la página siguiente.
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")

# Pasa `prev_page` de vuelta como `page` para volver a la página anterior.
previous_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=second_page.prev_page
)
for listed_session in previous_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# Para iteración solo hacia adelante, el objeto de página también es directamente iterable.

Archivar una sesión

Archiva una sesión para impedir que se envíen nuevos eventos mientras se conserva su historial. Una sesión en running no se puede archivar; para archivarla, envía un evento user.interrupt por sí solo y espera a que la sesión pase a idle. Si hay una ejecución de flujo de trabajo abierta, archivar podría devolver un error 400, incluso cuando la sesión está en idle, o podría tener éxito y finalizar la ejecución. Antes de archivar, envía un user.message que le pida al agente detener sus ejecuciones, o espera hasta que cada ejecución haya finalizado. Luego archiva la sesión una vez que esté en idle.

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

Eliminar una sesión

Elimina una sesión para borrar permanentemente su registro, sus eventos y el sandbox asociado. Una sesión en running no se puede eliminar; para eliminarla, envía un evento user.interrupt por sí solo y espera a que la sesión pase a idle. Si hay una ejecución de flujo de trabajo abierta, eliminar podría devolver un error 400, incluso cuando la sesión está en idle, o podría tener éxito. Después de una eliminación exitosa, ningún evento workflow_run informa el final de las ejecuciones de la sesión. Antes de eliminar, envía un user.message que le pida al agente detener sus ejecuciones, o espera hasta que cada ejecución haya finalizado. Luego elimina la sesión una vez que esté en idle.

Los almacenes de memoria, las bóvedas, las skills, los entornos y los agentes son recursos independientes y no se ven afectados por la eliminación de la sesión. Los archivos que subiste a través de la Files API tampoco se ven afectados, pero los archivos que la propia sesión produjo están limitados a ella y se eliminan permanentemente junto con su sistema de archivos. Descarga todo lo que necesites conservar antes de eliminar la sesión. Un archivo de salida escrito al final del último turno puede tardar unos segundos después de que la sesión pase a idle en aparecer en la lista de archivos de la sesión, así que primero verifica que los archivos que esperas aparezcan en la lista.

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