Configuração do ambiente em 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 < python-dev.environment.yaml

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 < environment.yaml

name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted

Gerenciadores de pacotes compatíveis:



Rede

O campo networking controla o acesso de rede de saída do sandbox. Ele não afeta as ferramentas web_search ou web_fetch, que são executadas nos servidores da Anthropic; para restringir os sites que essas ferramentas podem acessar, defina allowed_domains ou blocked_domains na entrada da ferramenta no conjunto de ferramentas do agente. Consulte Restringir domínios de busca na web e busca de conteúdo web.

O exemplo a seguir cria um ambiente com rede limited:

ant beta:environments create < environment.yaml

name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true

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ê atualizar um ambiente com frequência, mantenha seu próprio registro das alterações para saber 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 em nuvem incluem runtimes comuns prontos para uso. Consulte Referência de sandbox em nuvem para a lista completa de linguagens, bancos de dados e utilitários pré-instalados.



Próximos passos