Iniciar uma sessão

Uma sessão é uma instância de agente dentro de um ambiente. Cada sessão referencia um agente e um ambiente (ambos criados separadamente) e mantém o histórico da conversa ao longo de múltiplas interações. As sessões seguem um ciclo de vida de duas etapas: primeiro crie a sessão, depois envie um evento de usuário para iniciar o trabalho. Você também pode combinar as duas etapas em uma única chamada com initial_events.

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 de agent como string cria 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 em uma versão específica do agente, passe um objeto. Isso permite controlar exatamente qual versão é executada e escalonar a implantação de novas versões de forma independente.

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

Inicializar a sessão com eventos iniciais

Você pode criar uma sessão e iniciar seu trabalho em uma única chamada. initial_events é um array opcional de eventos iniciais a serem enviados à sessão na criação, processados em ordem. Ele suporta eventos user.message e user.define_outcome e aceita no máximo 50 eventos. Uma lista não vazia inicia o loop do agente na mesma chamada: a sessão é criada diretamente no status running, sem nenhuma requisição adicional.

O exemplo a seguir cria uma sessão com um único user.message em initial_events:

seeded_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
# initial_events não são ecoados na resposta de criação; leia-os de volta
# a partir da lista de eventos da sessão.
for event in client.beta.sessions.events.list(seeded_session.id):
    if event.type == "user.message":
        for block in event.content:
            if block.type == "text":
                print(f"Seeded event: {block.text}")

Nenhum outro tipo de evento é aceito. Eventos que respondem a um turno do agente (user.tool_confirmation, user.tool_result e user.custom_tool_result) não são aceitos porque ainda não existe nenhum turno do agente, e user.interrupt não é aceito porque não há turno a ser interrompido. Diferentemente de initial_events em uma implantação agendada, os initial_events de uma sessão não aceitam system.message.

Cada evento em initial_events é validado e persistido antes que a resposta de criação seja retornada, na ordem da lista, com um ID atribuído pelo servidor, exatamente como se você o tivesse enviado ao endpoint de envio de eventos imediatamente após a criação. As regras de conteúdo por evento também são as mesmas desse endpoint. Uma lista vazia equivale a omitir o campo. A validação é tudo ou nada: se qualquer evento falhar na validação, toda a requisição é rejeitada e nenhuma sessão é criada.

A requisição de criação é rejeitada nos seguintes casos:

Um evento user.define_outcome em initial_events é aceito nas mesmas condições que o envio de um para uma sessão existente; consulte Definir resultados.

Substituir a configuração do agente para uma sessão

Você pode passar agent de três formas: uma string de ID do agente, um objeto de versão fixada (type: "agent") ou um objeto de substituições. A forma de substituições altera partes da configuração do agente para uma única sessão. Use-a para testar um modelo diferente ou conceder uma ferramenta extra em uma sessão sem versionar o agente. Para a forma de substituições, defina type como agent_with_overrides e passe o id do agente e, opcionalmente, uma version (omita version para usar a versão mais recente do agente). Em seguida, inclua qualquer um de model, system, tools, mcp_servers ou skills com os valores que a sessão deve usar.

Cada campo substituível segue as mesmas três regras:

• Omitir o campo: A sessão herda o valor da versão do agente que ela referencia.
• Definir o campo como null, ou como um array vazio para campos de lista: A sessão é executada com esse campo limpo. Essa regra se aplica integralmente a system e skills. Há três exceções:
  • model nunca pode ser limpo. Uma sessão sempre precisa de um modelo, então model: null retorna um erro 400 agent_model_required.
  • Limpar tools retorna um erro 400 quando o skills efetivo da sessão não está vazio, porque skills exigem a ferramenta read. Caso contrário, tools: null e tools: [] limpam o campo.
  • Limpar mcp_servers retorna um erro 400 quando o tools efetivo da sessão ainda contém um mcp_toolset que referencia um dos servidores do agente. Substitua tools na mesma requisição para remover essas entradas mcp_toolset e, em seguida, limpe mcp_servers.
• Definir o campo com um valor: O valor substitui integralmente o valor do agente. As substituições nunca são mescladas com a configuração do agente, então uma substituição de tools deve listar todas as ferramentas que a sessão deve ter. Da mesma forma, uma substituição de model substitui integralmente o objeto model do agente, então o effort próprio do agente não é mantido. Para executar a sessão em um nível de esforço específico, defina effort dentro do objeto model da substituição. Um nível que o modelo não suporta retorna um erro 400, e uma substituição de model sem effort é executada no nível de esforço padrão desse modelo.

As substituições se aplicam apenas à sessão que você cria. Elas não modificam o recurso do agente nem criam uma nova versão do agente, então outras sessões que referenciam o mesmo agente não são afetadas.

Na resposta, o objeto agent reflete a configuração com a qual a sessão é executada após a aplicação das substituições. Seu id e sua version ainda identificam o agente e a versão aos quais as substituições são aplicadas. Isso permite rastrear uma sessão até seu agente base.

O exemplo a seguir inicia uma sessão que substitui o modelo e limpa o prompt do sistema:

override_session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "model": {"id": "claude-sonnet-5-5"},
        "system": None,  # clear the agent's system prompt for this session
    },
    environment_id=environment.id,
)
# O agente da resposta é o snapshot resolvido com os overrides aplicados.
print(f"Model: {override_session.agent.model.id}")
print(f"System: {override_session.agent.system}")

Fixar a geografia de inferência para uma sessão

Como uma substituição de model substitui integralmente o objeto model do agente, ela também define ou limpa a fixação de "inference geo" (geografia de inferência) do modelo para a sessão (consulte geografia de inferência): uma substituição que inclui inference_geo fixa a geografia que atende às requisições de modelo da sessão, e uma que o omite limpa a fixação do agente, de modo que a sessão segue o default_inference_geo do workspace. O valor substituído é validado em relação ao allowed_inference_geos do workspace quando a sessão é criada.

O exemplo a seguir inicia uma sessão a partir de um agente cujo modelo não tem fixação de geografia, fixa as requisições de modelo da sessão na inferência dos EUA incluindo inference_geo na substituição de model e imprime o valor retornado em agent.model na resposta:

session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        # Substitui o `model` do agente por completo: reafirme `id`, adicione `inference_geo` para fixar.
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
    },
    environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")

Definir um orçamento para a sessão

Para limitar quanto uma sessão pode gastar, passe o objeto opcional budget ao criá-la. Um orçamento é um teto rígido sobre o custo de tabela da sessão: a plataforma precifica tudo o que a sessão consome pelas tarifas públicas de tabela, e a sessão para de emitir novas requisições de modelo assim que esse total acumulado atinge max_list_cost. Defina type como limit e forneça a max_list_cost um amount e uma currency. amount é um número inteiro de centavos de dólar americano escrito como string, como "125" para $1,25. A API recebe uma string em vez de um número para que nenhum arredondamento de ponto flutuante seja aplicado. USD é a única moeda atualmente suportada. Quando a sessão atinge o limite, ela pausa e fica ociosa com o motivo de parada budget_reached. O limite é aplicado entre requisições de modelo, então a requisição que o ultrapassa termina primeiro e o custo de tabela final da sessão pode ficar uma fração acima do limite. Um orçamento só pode ser anexado na criação: você pode alterá-lo ou removê-lo depois, mas não pode adicionar um a uma sessão criada sem ele.

O exemplo a seguir cria uma sessão com um orçamento de $1,25:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

Consulte Orçamentos de sessão para saber como a aplicação funciona, o que conta para o custo de tabela e como os orçamentos se comportam em sessões multiagente.

Autenticação MCP por meio de vaults

Se o seu agente usa ferramentas MCP que exigem autenticação, passe vault_ids na criação da sessão para referenciar um vault contendo credenciais OAuth armazenadas. A Anthropic gerencia a renovação de tokens em seu nome. Consulte Autenticar com vaults para saber como criar vaults e registrar credenciais.

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

Iniciando a sessão

Criar uma sessão sem initial_events registra a sessão, mas não inicia nenhum trabalho; o sandbox do ambiente começa a ser provisionado assim que a sessão é criada, então a primeira chamada de ferramenta não precisa esperar por ele. Para delegar uma tarefa, envie eventos para a sessão usando um evento de usuário. Para fornecer o primeiro evento na própria requisição de criação, consulte Inicializar a sessão com eventos iniciais. A sessão atua como uma máquina de estados que acompanha o progresso, enquanto os eventos conduzem a execução propriamente dita.

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

Consulte Fluxo de eventos da sessão para saber como fazer streaming das respostas do agente e lidar com confirmações de ferramentas.

Consulte Status da sessão para conhecer os status pelos quais uma sessão passa.

Próximos passos