Configuração do ambiente na nuvem

Os ambientes definem a configuração do sandbox onde seu agente é executado. Você cria um ambiente uma vez e, em seguida, referencia seu ID cada vez que inicia uma sessão. Várias sessões podem compartilhar o mesmo ambiente, mas cada sessão recebe seu próprio sandbox isolado (um contêiner Linux novo).

Esta página aborda ambientes do tipo type: cloud. Para executar sandboxes em sua própria infraestrutura, consulte Sandboxes auto-hospedados.



Criar um ambiente

ant beta:environments create \
  --name "python-dev" \
  --config '{type: cloud, networking: {type: unrestricted}}'

Use um name único e descritivo para que você possa diferenciar os ambientes.



Usar o ambiente em uma sessão

Passe o ID do ambiente como uma string ao criar uma sessão.

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"



Opções de configuração



Pacotes

O campo packages pré-instala pacotes no sandbox antes de o agente iniciar. Os pacotes são instalados por seus respectivos gerenciadores de pacotes e armazenados em cache entre sessões que compartilham o mesmo ambiente. Quando vários gerenciadores de pacotes são especificados, eles são executados em ordem alfabética (apt, cargo, gem, go, npm, pip). Opcionalmente, você pode fixar versões específicas. Pacotes sem versão fixada instalam a versão mais recente.

ant beta:environments create <<'YAML'
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted
YAML

Gerenciadores de pacotes suportados:



Rede

O campo networking controla o acesso de rede de saída do sandbox. Ele não afeta os domínios permitidos para as ferramentas web_search ou web_fetch.

O exemplo a seguir cria um ambiente com rede limited:

ant beta:environments create <<'YAML'
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true
YAML

Ao usar rede limited:

• allowed_hosts especifica os domínios que o sandbox pode acessar. Especifique nomes de host simples ou padrões com curinga (como *.example.com). Não inclua esquema de URL, porta ou caminho.
• allow_mcp_servers permite acesso de saída aos endpoints de servidores MCP configurados no agente, além daqueles listados no array allowed_hosts. O padrão é false.
• allow_package_managers permite acesso de saída a registros públicos de pacotes (como PyPI e npm) além daqueles listados no array allowed_hosts. O padrão é false.



Ciclo de vida do ambiente

• Os ambientes persistem até serem explicitamente arquivados ou excluídos.
• Cada sessão recebe sua própria instância de sandbox, mesmo quando várias sessões referenciam o mesmo ambiente. As sessões não compartilham o estado do sistema de arquivos.
• Os ambientes não são versionados. Se você atualiza um ambiente com frequência, mantenha seu próprio registro das alterações para que possa identificar qual configuração cada sessão usou.



Gerenciar ambientes

# Listar ambientes
ant beta:environments list

# Recuperar um ambiente específico
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

# Arquivar um ambiente (somente leitura, sessões existentes continuam)
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

# Excluir um ambiente (somente se nenhuma sessão o referenciar)
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"



Runtimes pré-instalados

Os sandboxes na nuvem incluem runtimes comuns prontos para uso. Consulte Referência de sandbox na nuvem para a lista completa de linguagens, bancos de dados e utilitários pré-instalados.



Próximos passos