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

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: python-dev
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

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.

session = client.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 apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
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 apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
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 um conjunto de registros públicos de pacotes e hosts de código além daqueles listados no array allowed_hosts. Consulte Hosts de gerenciadores de pacotes para ver a lista. 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.

Hosts de gerenciadores de pacotes

Quando allow_package_managers é true, o sandbox pode acessar os seguintes hosts, além daqueles em allowed_hosts. A Anthropic mantém esta lista e pode alterá-la.

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

# List environments
environments = client.beta.environments.list()

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(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