Iniciar uma sessão

Crie uma sessão para executar seu agente e começar a executar tarefas.

Uma sessão é uma instância de agente em execução dentro de um ambiente. Cada sessão faz referência a um agente e um ambiente (ambos criados separadamente) e mantém o histórico de conversas em múltiplas interações.

Todas as solicitações da API Managed Agents requerem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

Criando uma sessão

Uma sessão requer um ID de agent e um ID de environment. Agentes são recursos versionados; passar o ID do agent como uma string inicia a sessão com a versão mais recente do agente.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Para fixar uma sessão a uma versão específica do agente, passe um objeto. Isso permite que você controle exatamente qual versão é executada e prepare implementações de novas versões de forma independente.

O agente define como Claude se comporta dentro da sessão, incluindo o modelo, prompt do sistema, ferramentas e servidores MCP. Consulte Configuração do agente para obter detalhes.

Autenticação MCP através de cofres

Se seu agente usa ferramentas MCP que requerem autenticação, passe vault_ids na criação da sessão para fazer referência a um cofre contendo credenciais OAuth armazenadas. Anthropic gerencia a atualização de tokens em seu nome. Consulte Autenticar com cofres para saber como criar cofres e registrar credenciais.

Iniciando a sessão

Criar uma sessão provisiona o ambiente e o agente, mas não inicia nenhum trabalho. Para delegar uma tarefa, envie eventos para a sessão usando um evento de usuário. A sessão atua como uma máquina de estados que rastreia o progresso enquanto os eventos impulsionam a execução real.

Consulte Eventos e streaming para saber como transmitir as respostas do agente e lidar com confirmações de ferramentas.

Status das sessões

As sessões progridem através destes status:

Status	Descrição
`idle`	O agente está aguardando entrada, incluindo mensagens de usuário ou confirmações de ferramentas. As sessões começam em `idle`.
`running`	O agente está executando ativamente
`rescheduling`	Erro transitório ocorreu, tentando novamente automaticamente
`terminated`	A sessão terminou devido a um erro irrecuperável

Outras operações de sessão

Recuperando uma sessão

Listando sessões

Arquivando uma sessão

Arquive uma sessão para impedir que novos eventos sejam enviados enquanto preserva seu histórico:

Deletando uma sessão

Delete uma sessão para remover permanentemente seu registro, eventos e contêiner associado. Uma sessão running não pode ser deletada; envie um evento de interrupção se precisar deletá-la imediatamente.

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

Was this page helpful?

ConstruirDelegar trabalho ao seu agente

Iniciar uma sessão

Crie uma sessão para executar seu agente e começar a executar tarefas.

Todas as solicitações da API Managed Agents requerem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

Criando uma sessão

Uma sessão requer um ID de agent e um ID de environment. Agentes são recursos versionados; passar o ID do agent como uma string inicia a sessão com a versão mais recente do agente.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

O agente define como Claude se comporta dentro da sessão, incluindo o modelo, prompt do sistema, ferramentas e servidores MCP. Consulte Configuração do agente para obter detalhes.

Autenticação MCP através de cofres

Iniciando a sessão

Consulte Eventos e streaming para saber como transmitir as respostas do agente e lidar com confirmações de ferramentas.

Status das sessões

As sessões progridem através destes status:

Status	Descrição
`idle`	O agente está aguardando entrada, incluindo mensagens de usuário ou confirmações de ferramentas. As sessões começam em `idle`.
`running`	O agente está executando ativamente
`rescheduling`	Erro transitório ocorreu, tentando novamente automaticamente
`terminated`	A sessão terminou devido a um erro irrecuperável

Outras operações de sessão

Recuperando uma sessão

Listando sessões

Arquivando uma sessão

Arquive uma sessão para impedir que novos eventos sejam enviados enquanto preserva seu histórico:

Deletando uma sessão

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

Was this page helpful?

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)