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# 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: trueant 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# 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: trueGerenciadores de pacotes suportados:
| Campo | Gerenciador de pacotes | Exemplo |
|---|---|---|
apt | Pacotes do sistema (apt-get) | "graphviz" |
cargo | Rust (cargo) | "hyperfine@1.18.0" |
gem | Ruby (gem) | "rails:7.1.0" |
go | Módulos Go | "golang.org/x/tools/cmd/goimports@latest" |
npm | Node.js (npm) | "express@4.18.0" |
pip | Python (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.
| Modo | Descrição |
|---|---|
limited | Restringe 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. |
unrestricted | Acesso 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# 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: trueCom 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_hostsespecifica 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.comnão corresponde awww.example.com.*.example.comcorresponde a todos os subdomínios deexample.com, mas não ao próprioexample.com.allow_mcp_serverspermite acesso de saída aos endpoints de servidores MCP configurados no agente, além daqueles listados no arrayallowed_hosts. O padrão éfalse. Enquanto forfalse, a criação da sessão falha com um erro 400 se o agente declarar um servidor MCP cujo host não esteja emallowed_hosts. O mesmo se aplica a um agente para o qual ele pode delegar. Para corrigir isso, adicione o host aallowed_hostsou definaallow_mcp_serverscomotrue.allow_package_managerspermite acesso de saída a um conjunto de registros de pacotes públicos e hosts de código além daqueles listados no arrayallowed_hosts. Consulte Hosts de gerenciadores de pacotes para ver a lista. O padrão éfalse. Defina-o comotruesempre que o ambiente especificarpackages. Caso contrário, a API rejeita a requisição com um erro 400, mesmo queallowed_hostsliste 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.
| Ecossistema | Hosts |
|---|---|
| Hospedagem de código | github.com, api.github.com, codeload.github.com, raw.githubusercontent.com, objects.githubusercontent.com, release-assets.githubusercontent.com, gitlab.com, bitbucket.org |
| Node.js | registry.npmjs.org, registry.yarnpkg.com, nodejs.org |
| Python | pypi.org, files.pythonhosted.org |
| Rust | crates.io, index.crates.io, static.crates.io, static.rust-lang.org |
| Go | proxy.golang.org, sum.golang.org |
| Java | repo1.maven.org, repo.maven.apache.org, services.gradle.org, plugins.gradle.org, plugins-artifacts.gradle.org |
| Ruby | rubygems.org, index.rubygems.org |
| PHP | packagist.org, repo.packagist.org |
| Ubuntu (apt) | archive.ubuntu.com, security.ubuntu.com, ppa.launchpad.net |
| Contêineres | registry-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
bashpode 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 comandosbashsã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
Claude API
- Status
- Beta
- API
- Managed Agents
- Cabeçalho beta
- Requer
- Modelos
- Todos os modelos
Claude Platform on AWS
- Status
- Beta
- API
- Managed Agents
- Cabeçalho beta
- Requer
- Modelos
- Todos os modelos
Claude Models on Google Cloud (Anthropic managed)
- Status
- Beta
- API
- Managed Agents
- Cabeçalho beta
- Requer
- Modelos
- Todos os modelos
Tratamento de dados
Visão geral do tratamento de dadosEndpoints aplicáveis
/v1/agents/v1/sessions/v1/environments
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
Não é elegível para HIPAA. Aplica-se a todos os sub-recursos do Managed Agents.
Esta página foi útil?