Operações de sessão

Depois que uma sessão existe, use estas operações para lê-la, atualizá-la, arquivá-la ou excluí-la. Consulte Iniciar uma sessão para criar uma sessão e enviar trabalho a ela.



Status de sessão

As sessões progridem por estes status. Consulte Iniciar uma sessão para o ciclo de vida da sessão.



Atualizando a configuração do agente

Você pode atualizar agent.tools e agent.mcp_servers de uma sessão, incluindo políticas de permissão, no meio da sessão sem criar uma nova versão do agente. As atualizações são locais à sessão e não se propagam de volta ao agente subjacente.

Apenas tools e mcp_servers do agente podem ser alterados depois que uma sessão é criada. Para executar uma sessão com valores de model, system ou skills diferentes dos do agente, use substituições de configuração do agente ao criar a sessão. O campo system configurado do agente é fixo durante toda a vida útil da sessão. Em modelos que oferecem suporte a isso, você ainda pode substituir o prompt do sistema efetivo entre turnos enviando um evento system.message.

A semântica de uma atualização de tools ou mcp_servers é de substituição completa: o array fornecido é o novo valor. Para preservar entradas existentes, faça um GET na sessão, modifique o array e envie-o de volta com POST.

A sessão deve estar em idle para atualizar o agente. Interrompa a sessão se precisar atualizar o agente enquanto ela estiver em execução.

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



Recuperando uma sessão

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



Listando sessões

Os resultados de GET /v1/sessions são paginados. Use o parâmetro de consulta limit para controlar o tamanho da página. Cada resposta inclui um cursor next_page; passe-o como o parâmetro page na próxima requisição para buscar a página seguinte. next_page é null quando não há mais resultados.

Para voltar uma página, passe prev_page como o parâmetro page. prev_page é null quando você está na primeira página.

Um cursor page é opaco e codifica o order da requisição que o produziu. O parâmetro de consulta order define a direção de ordenação dos resultados, asc ou desc por data de criação; o padrão é desc (mais recentes primeiro). Reutilizar um cursor com um order diferente retorna um erro 400; outros parâmetros de consulta, incluindo filtros e limit, podem mudar entre requisições paginadas. Para os campos de paginação compartilhados entre endpoints de listagem, consulte Paginação.

# --format raw retorna um envelope de página com seus cursores prev_page e next_page;
# a saída padrão faz paginação automática e emite apenas as sessões.
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# Passe o cursor next_page de volta como --page para buscar a próxima 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}'
# Passe o prev_page dessa resposta como --page para voltar da mesma forma.



Arquivando uma sessão

Arquive uma sessão para impedir que novos eventos sejam enviados, preservando seu histórico. Uma sessão em running não pode ser arquivada; envie um evento de interrupção se precisar arquivá-la imediatamente.

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



Excluindo uma sessão

Exclua uma sessão para remover permanentemente seu registro, eventos e sandbox associado. Uma sessão em running não pode ser excluída; envie um evento de interrupção se precisar excluí-la imediatamente.

Arquivos, armazenamentos de memória, vaults, skills, ambientes e agentes são recursos independentes e não são afetados pela exclusão da sessão.

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