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 para o agente subjacente.

Apenas 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 a isso, você ainda pode anexar orientações de 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 um GET da 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 você precisar atualizar o agente enquanto ele está 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



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 de substituição pode ser maior ou menor que o atual, mas deve ser estritamente maior que o custo de lista consumido da sessão, e a remoção é unidirecional: um budget não nulo é aceito apenas em uma sessão que atualmente tem um, então 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 em running não pode ser arquivada; envie um evento de interrupção se você 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 você precisar excluí-la imediatamente.

Memory stores, vaults, skills, environments e agents 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 limitado 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.

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