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. Este exemplo usa rede limited com gerenciadores de pacotes permitidos, para que o sandbox possa acessar os registros de pacotes e os hosts de código. Para permitir que ele acesse outros hosts, adicione-os a allowed_hosts.

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: limited
    allow_package_managers: true

Gerenciadores de pacotes suportados:

Rede

O campo networking controla o acesso de rede de saída do sandbox.

Com a rede limited, allowed_hosts também se aplica às ferramentas web_search e web_fetch, que são executadas nos servidores da Anthropic. Uma chamada web_fetch para uma URL em um host que não corresponde a allowed_hosts retorna um resultado de erro ao agente. web_search omite resultados de hosts que não correspondem a allowed_hosts. allow_package_managers e allow_mcp_servers não adicionam hosts para essas ferramentas. Quando allowed_hosts não lista nenhum host, nenhuma chamada web_fetch ou web_search retorna uma página ou um resultado de pesquisa. Um host que você adiciona a allowed_hosts para essas ferramentas também fica aberto ao sandbox. A rede unrestricted e os ambientes auto-hospedados não limitam essas ferramentas. Para restringi-las ainda mais, defina allowed_domains ou blocked_domains na entrada da ferramenta no conjunto de ferramentas do agente. Consulte Restringir domínios de pesquisa na web e busca na 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

Com a rede limited e nenhum outro campo definido, nenhum host é permitido. Arquivos, memory stores (armazenamentos de memória) e repositórios do GitHub que você anexa à sessão permanecem disponíveis. Quando uma requisição do sandbox na porta 80 ou 443 é recusada porque seu host não é permitido, a resposta é um 403 que nomeia o host bloqueado.

Ao usar a rede limited:

• allowed_hosts especifica os domínios que o sandbox pode acessar. Especifique nomes de host simples ou padrões curinga (como *.example.com). Não inclua um esquema de URL, porta ou caminho. Um nome de host simples corresponde exatamente a esse host: example.com não corresponde a www.example.com. *.example.com corresponde a todos os subdomínios de example.com, mas não ao próprio example.com.
• 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. Enquanto for false, a criação da sessão falha com um erro 400 se o agente declarar um servidor MCP cujo host não esteja em allowed_hosts. O mesmo se aplica a um agente para o qual ele pode delegar. Para corrigir isso, adicione o host a allowed_hosts ou defina allow_mcp_servers como true.
• 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 de registro 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.

Riscos da rede irrestrita

Com a rede unrestricted, o código no sandbox pode enviar requisições a qualquer host na internet, exceto hosts em uma lista de bloqueio de segurança geral. Antes de escolher este modo, considere o que o agente pode fazer com esse acesso:

• O agente pode alterar coisas em sites externos, não apenas lê-las: A ferramenta bash pode enviar qualquer requisição. O agente pode publicar dados, enviar formulários, chamar APIs e executar scripts que alteram dados em sites externos. Mesmo uma requisição que apenas busca uma URL pode alterar dados em alguns sites.
• Nada pausa essas requisições por padrão: A política de permissão padrão do conjunto de ferramentas do agente é always_allow, então os comandos bash são executados sem aprovação.
• Qualquer coisa no sandbox pode sair dele: Isso inclui arquivos, saídas de ferramentas e quaisquer credenciais ou segredos que você coloque no sandbox.
• O conteúdo obtido pode direcionar o agente: Páginas web, respostas de API e outros conteúdos que o agente lê podem conter instruções (injeção de prompt) que alteram o que ele faz em seguida.
• O agente age em seu nome: Suas ações podem violar os termos de serviço de um site ou criar contas e registros nele.
• O comportamento do modelo não é um controle de segurança: O agente pode agir em sites externos de maneiras que você não solicitou, incluindo tentar novamente de uma forma diferente depois que um site bloqueia uma requisição. Use configurações de rede e políticas de permissão para limitar o que ele pode fazer.
• A lista de bloqueio de segurança não é uma lista de permissões: Ela não limita quais outros sites o agente acessa, nem o que o agente faz neles.

Para reduzir esses riscos, use a rede limited com uma lista explícita de hosts. O seguinte valor de networking permite api.example.com, além dos hosts de gerenciadores de pacotes para um agente que instala pacotes:

{
  "type": "limited",
  "allowed_hosts": ["api.example.com"],
  "allow_package_managers": true
}

Um agente que usa apenas as ferramentas web_search e web_fetch não precisa de rede unrestricted se você puder listar os sites de que ele precisa. Com a rede limited, allowed_hosts também se aplica a essas ferramentas (consulte Rede), então liste esses sites em allowed_hosts. Listá-los também em allowed_domains de web_search faz com que ele pesquise nesses sites. Um host que você adiciona a allowed_hosts também fica aberto ao sandbox. Para restringir ainda mais as ferramentas, consulte Restringir domínios de pesquisa na web e busca na web.

Use unrestricted somente quando o agente precisar acessar sites que você não pode listar com antecedência. Nesse caso, mantenha segredos e arquivos confidenciais fora do sandbox e forneça ao agente apenas as credenciais de que a tarefa precisa. Considere definir a política de permissão da ferramenta bash como always_ask ou auto e acompanhar os eventos da sessão.

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
environments = client.beta.environments.list()

# Recuperar um ambiente específico
env = client.beta.environments.retrieve(environment.id)

# Arquivar um ambiente (somente leitura, sessões existentes continuam)
client.beta.environments.archive(environment.id)

# Excluir um ambiente (somente se nenhuma sessão o referenciar)
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