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 de conversas ao longo de múltiplas interações. As sessões seguem um ciclo de vida de duas etapas: primeiro crie a sessão para provisionar seu sandbox, depois envie um evento de usuário para iniciar o trabalho.



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 uma string inicia 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 a uma versão específica do agente, passe um objeto. Isso permite que você controle exatamente qual versão é executada e faça o rollout 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



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

Você pode passar agent de três formas: uma string de ID de agente, um objeto de versão fixada (type: "agent") ou um objeto de substituições (overrides). A forma de substituições 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 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 dos campos 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, mcp_servers e skills. Há duas 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 requerem a ferramenta read. Caso contrário, tools: null e tools: [] limpam o campo.
• Definir o campo com um valor: O valor substitui completamente 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.

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 as substituições serem aplicadas. Seu id e version ainda identificam o agente e a versão aos quais as substituições são aplicadas. Isso permite que você rastreie uma sessão de volta ao seu agente base.

# O `agent` da resposta é o snapshot resolvido: cada override substitui esse
# campo apenas para esta sessão, e o recurso de 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



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 provisiona o sandbox do ambiente, 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 acompanha o progresso enquanto os eventos conduzem a execução real.

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 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 os status pelos quais uma sessão passa, e Operações de sessão para recuperar, listar, atualizar, arquivar e excluir sessões.

Para criar sessões automaticamente em um cronograma recorrente, consulte Implantações agendadas.