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

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"}
        ],
    },
)

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

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

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.

# Defina `limit` baixo para que os resultados ocupem mais de uma página.
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# `prev_page` é None na primeira página; `next_page` é None na última.
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# Passe `next_page` de volta como `page` para buscar a próxima página.
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}")

# Passe `prev_page` de volta como `page` para voltar à 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 iteração apenas para frente, o objeto de página também é diretamente iterável.

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.

client.beta.sessions.archive(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.

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