Claude Platform Docs
Managed AgentsConfigurar ambiente do agente

Configuração do ambiente em nuvem

Personalize sandboxes em nuvem para suas sessões.

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. Para escolher entre os dois, consulte Escolhendo um ambiente de agente.

Criar um ambiente

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

ant apply cria o ambiente a partir de environment.yaml, imprime seu ID e o registra em claude-lock.json. Faça commit de claude-lock.json para que o próximo ant apply atualize este ambiente em vez de tentar criá-lo novamente.

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 (consulte Iniciar uma sessão).

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Opções de configuração

Pacotes

O campo packages instala pacotes no sandbox antes de o agente usá-lo. Os gerenciadores de pacotes são executados em ordem alfabética (apt, cargo, gem, go, npm, pip). Você pode fixar versões específicas. Se o ambiente usar rede limited, defina também allow_package_managers em networking como true; caso contrário, a API rejeita a requisição com um erro 400.

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

CampoGerenciador de pacotesExemplo
aptPacotes do sistema (apt-get)"graphviz"
cargoRust (cargo)"hyperfine@1.18.0"
gemRuby (gem)"rails:7.1.0"
goMódulos Go"golang.org/x/tools/cmd/goimports@latest"
npmNode.js (npm)"express@4.18.0"
pipPython (pip)"sqlalchemy==2.0.30"

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 web fetch.

ModoDescrição
limitedRestringe o acesso de rede do sandbox aos hosts em allowed_hosts. Defina allow_package_managers e allow_mcp_servers como true para permitir acesso adicional. Use este modo, a menos que o agente precise acessar sites que você não pode listar com antecedência.
unrestrictedAcesso de rede de saída completo, exceto por uma lista de bloqueio de segurança geral. Antes de usá-lo, leia Riscos da rede irrestrita.

O exemplo a seguir cria um ambiente com rede limited:

ant apply environment.yaml
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 hosts 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 de pacotes públicos 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 API rejeita a requisição com um erro 400, mesmo que allowed_hosts liste os hosts de registro.

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.

EcossistemaHosts
Hospedagem de códigogithub.com, api.github.com, codeload.github.com, raw.githubusercontent.com, objects.githubusercontent.com, release-assets.githubusercontent.com, gitlab.com, bitbucket.org
Node.jsregistry.npmjs.org, registry.yarnpkg.com, nodejs.org
Pythonpypi.org, files.pythonhosted.org
Rustcrates.io, index.crates.io, static.crates.io, static.rust-lang.org
Goproxy.golang.org, sum.golang.org
Javarepo1.maven.org, repo.maven.apache.org, services.gradle.org, plugins.gradle.org, plugins-artifacts.gradle.org
Rubyrubygems.org, index.rubygems.org
PHPpackagist.org, repo.packagist.org
Ubuntu (apt)archive.ubuntu.com, security.ubuntu.com, ppa.launchpad.net
Contêineresregistry-1.docker.io, auth.docker.io, production.cloudflare.docker.com, download.docker.com, ghcr.io

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 da web, respostas de API e outros conteúdos que o agente lê podem conter instruções (injeção de prompt) que mudam 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), portanto 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 web fetch.

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é que você os arquive ou exclua.
  • 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, sem novas sessões)
client.beta.environments.archive(environment.id)

# Excluir um ambiente
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. Consulte a Referência de sandbox em nuvem para a lista completa.

Próximos passos

Pacotes pré-instalados, bancos de dados e utilitários disponíveis em sandboxes em nuvem.

Crie uma sessão para executar seu agente e começar a executar tarefas.

Disponibilidade

Sandboxes na nuvem
Os requisitos de disponibilidade de Sandboxes na nuvem são os mesmos em todas as plataformas compatíveis.
Status
Beta
API
  • Managed Agents
Cabeçalho beta
Requer
Modelos
  • Todos os modelos

Endpoints aplicáveis

  • /v1/agents
  • /v1/sessions
  • /v1/environments
Retenção zero de dadosNão elegível

Não é elegível para ZDR, exceto o Managed Agents auto-hospedado. Sessões são recursos com estado; as transcrições persistem até que você as exclua. Saiba mais

HIPAANão elegível

Não é elegível para HIPAA. Aplica-se a todos os sub-recursos do Managed Agents.

Esta página foi útil?