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 sesión

Las sesiones avanzan a través de estos estados. Consulta Iniciar una sesión para ver 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, en medio 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.

Solo tools y mcp_servers del agente pueden cambiar después de que se crea una sesión. Para ejecutar una sesión con valores de model, system o skills distintos a los del agente, usa las anulaciones de configuración del agente al crear la sesión. 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 reemplazar la indicación del sistema efectiva entre turnos 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. Interrumpe la sesión si necesitas actualizar el agente mientras está en ejecución.

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
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
YAML



Recuperar una sesión

ant beta:sessions retrieve --session-id "$SESSION_ID"



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 hora de creación; el valor predeterminado es desc (los más recientes primero). Reutilizar un cursor con un order diferente devuelve un error 400; otros parámetros de consulta, incluidos los filtros y limit, pueden cambiar entre solicitudes paginadas. Para los campos de paginación compartidos entre los endpoints de listado, consulta Paginación.

# --format raw devuelve un envelope de página con sus cursores prev_page y next_page;
# la salida predeterminada auto-pagina y emite solo las sesiones.
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# Pasa el cursor next_page de vuelta como --page para obtener la siguiente página.
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# Pasa el prev_page de esa respuesta como --page para retroceder de la misma forma.



Archivar una sesión

Archiva una sesión para evitar que se envíen nuevos eventos mientras se conserva su historial. Una sesión en estado running no se puede archivar; envía un evento de interrupción si necesitas archivarla de inmediato.

ant beta:sessions archive \
  --session-id "$SESSION_ID"



Eliminar una sesión

Elimina una sesión para quitar permanentemente su registro, eventos y sandbox asociado. Una sesión en estado running no se puede eliminar; envía un evento de interrupción si necesitas eliminarla de inmediato.

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

ant beta:sessions delete \
  --session-id "$SESSION_ID"