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 depois 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 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 distinguir 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. Se o ambiente usar rede limited, defina também networking.allow_package_managers como true; caso contrário, a requisição será rejeitada com um erro 400.

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 suportados:

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. Defina-o como true sempre que o ambiente especificar packages; caso contrário, a requisição será rejeitada com um erro 400, mesmo que os hosts dos registros estejam listados em allowed_hosts.

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 poder 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 em nuvem incluem runtimes de linguagens comuns, bancos de dados e ferramentas de linha de comando prontos para uso. Consulte a Referência de sandbox em nuvem para a lista completa.

Próximos passos