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 condensar 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 do agent como uma string cria a sessão com a versão mais recente do agente.

ant 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 que você controle exatamente qual versão é executada e faça rollouts graduais de novas versões de forma independente.

ant beta:sessions create <<YAML
agent:
  type: agent
  id: $AGENT_ID
  version: 1
environment_id: $ENVIRONMENT_ID
YAML

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_ID=$(ant beta:sessions create \
  --transform id --raw-output <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML
)

# initial_events não são ecoados na resposta de criação; liste os eventos
# da sessão para ver a mensagem semeada.
echo "Seeded event: $(ant beta:sessions:events list \
  --session-id "$SEEDED_SESSION_ID" \
  --format raw \
  --transform 'data.#(type=="user.message").content.0.text' --raw-output)"

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 retorne, 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 é equivalente a omitir o campo. A validação é tudo ou nada: se qualquer evento falhar na validação, a requisição inteira é 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 sob as mesmas condições que o envio de um a uma sessão existente; consulte Definir resultados.

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

Você pode passar agent em três formas: uma string de ID do agente, um objeto de versão fixada (type: "agent") ou um objeto de sobrescritas (overrides). A forma de sobrescritas altera partes da configuração do agente para uma única sessão. Use-a para experimentar um modelo diferente ou conceder uma ferramenta extra em uma sessão sem versionar o agente. Para a forma de sobrescritas, 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 sobrescreví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. Esta 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, portanto 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 requerem 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. Sobrescreva tools na mesma requisição para remover essas entradas mcp_toolset e, então, limpe mcp_servers.
• Definir o campo com um valor: O valor substitui integralmente o valor do agente. Sobrescritas nunca são mescladas com a configuração do agente, portanto uma sobrescrita de tools deve listar todas as ferramentas que a sessão deve ter. Há uma exceção:
  • Um nível de effort dentro de uma sobrescrita de model por sessão não é aplicado e, como a sobrescrita substitui integralmente o objeto model do agente, o effort do próprio agente também não é mantido: uma sessão criada com uma sobrescrita de model é executada no nível de esforço padrão do modelo. Para executar em um nível de esforço específico, defina effort no agente e não sobrescreva model para essa sessão.

As sobrescritas se aplicam apenas à sessão que você cria. Elas não modificam o recurso do agente nem criam uma nova versão do agente, portanto 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 sobrescritas. Seus id e version ainda identificam o agente e a versão aos quais as sobrescritas são aplicadas. Isso permite rastrear uma sessão até seu agente base.

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

# O `agent` da resposta é o snapshot resolvido: cada override substitui esse
# campo apenas para esta sessão, e o recurso do agente mantém seu id e versão.
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML

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

Como uma sobrescrita de model substitui integralmente o objeto model do agente, ela também define ou limpa a fixação de inference_geo do modelo para a sessão: uma sobrescrita 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 sobrescrito é 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 nos EUA ao incluir inference_geo na sobrescrita de model e imprime o valor ecoado no agent.model da resposta:

# Substitui o `model` do agente por completo: repita `id`, adicione `inference_geo` para fixar.
session=$(ant beta:sessions create <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-opus-5
    inference_geo: us
environment_id: $ENVIRONMENT_ID
YAML
)
echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"

Definir um orçamento para a sessão

Para limitar o que uma sessão pode gastar, passe o objeto opcional budget ao criá-la. Um orçamento é um teto rígido sobre o custo de lista da sessão: a plataforma precifica tudo o que a sessão consome pelas tarifas públicas de lista, e a sessão para de emitir novas requisições de modelo quando 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 escrito como string, como "2500" para $25,00; 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 teto, ela pausa e fica ociosa com o motivo de parada budget_reached. O teto é aplicado entre requisições de modelo, portanto a requisição que o ultrapassa termina primeiro e o custo de lista final da sessão pode ficar uma fração acima do teto. 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 $25,00; a resposta ecoa o budget no recurso da sessão:

curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF

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

Autenticação MCP por meio de vaults

Se seu agente usa ferramentas MCP que requerem 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.

ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
  - $VAULT_ID
YAML

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, de modo que a primeira chamada de ferramenta não precisa esperar por ele. Para delegar uma tarefa, envie eventos à sessão usando um evento de usuário. Para fornecer o primeiro evento na 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.

ant beta:sessions:events send \
  --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML

Consulte Stream 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