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 e configurações web por ferramenta, como filtros de domínio, 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. Os valores atualizados de allowed_domains e blocked_domains se aplicam ao restante da sessão.

Somente tools e mcp_servers do agente podem mudar 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. A configuração de modelo do agente, incluindo sua fixação de inference_geo, também não pode mudar no meio da sessão: defina a fixação ao salvar o agente, ou defina-a ou remova-a para uma única sessão com uma substituição de model ao criá-la. O campo system configurado do agente é fixo durante toda a vida da sessão. Em modelos que oferecem suporte, você ainda pode acrescentar orientações em nível de sistema no meio da sessão 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 GET da sessão, modifique o array e envie-o de volta com POST.

A sessão deve estar idle para atualizar o agente. Para atualizar o agente enquanto a sessão está em execução, envie um evento user.interrupt sozinho e aguarde a sessão ficar idle.

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

Atualizando o orçamento da sessão

Uma sessão criada com um orçamento aceita dois tipos de atualização de orçamento: substituir o limite por um novo max_list_cost e removê-lo definindo budget como null. Ambos retomam automaticamente o trabalho que foi pausado quando a sessão atingiu seu limite. Um limite substituto pode ser maior ou menor que o atual, mas deve ser estritamente maior que o custo de lista consumido pela sessão, e a remoção é irreversível: um budget não nulo é aceito apenas em uma sessão que atualmente possui um, portanto você não pode readicionar um orçamento removido nem adicionar um a uma sessão criada sem ele. Consulte Orçamentos de sessão para exemplos de requisição, os comportamentos de erro e o que conta para o custo de lista.

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, assim como alterar um filtro created_at de forma que ele exclua a posição do cursor. Outros parâmetros de consulta, incluindo os filtros restantes 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 pagina automaticamente 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 do mesmo jeito.

Arquivando uma sessão

Arquive uma sessão para impedir que novos eventos sejam enviados, preservando seu histórico. Uma sessão running não pode ser arquivada; para arquivá-la, envie um evento user.interrupt sozinho e aguarde a sessão ficar idle.

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 running não pode ser excluída; para excluí-la, envie um evento user.interrupt sozinho e aguarde a sessão ficar idle.

Armazenamentos de memória, cofres, skills, ambientes e agentes são recursos independentes e não são afetados pela exclusão da sessão. Arquivos que você enviou por meio da Files API também não são afetados, mas arquivos que a própria sessão produziu têm escopo restrito a ela e são excluídos permanentemente junto com seu sistema de arquivos. Baixe tudo o que você precisa manter antes de excluir a sessão. Um arquivo de saída gravado no final do último turno pode levar alguns segundos após a sessão ficar idle para aparecer na lista de arquivos da sessão, portanto verifique primeiro se os arquivos que você espera estão listados.

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