Proteger sua implantação do Managed Agents

Este guia lista as configurações que limitam o que um agente no Claude Managed Agents pode alcançar e fazer, das mais importantes para as menos importantes. Cada seção tem um link para a página que aborda a configuração por completo.

Riscos de segurança e limites do sandbox explica por que essas configurações são importantes e contra o que elas não protegem. Para revisar e monitorar sessões, consulte Revisar e monitorar sessões de agentes.

Escolher onde o agente é executado

O local onde as ferramentas do agente são executadas decide quem protege o sandbox: a Anthropic, com um ambiente em nuvem, ou você, com um sandbox auto-hospedado. Para escolher entre eles e saber o que chega à Anthropic em cada caso, consulte Escolhendo um ambiente de agente.

Se você usa um sandbox auto-hospedado, tenha em mente estes quatro pontos:

• Rede: Limitar a rede se aplica a ambientes em nuvem. Para um sandbox auto-hospedado, defina os limites equivalentes sobre o tráfego dele em seu próprio firewall. Seu firewall não limita os servidores MCP que um agente declara, então revise-os, assim como quaisquer servidores que sua aplicação defina para uma sessão.
• Ferramentas web: As ferramentas web são executadas nos servidores da Anthropic, então seu firewall não as limita. Limite-as com suas listas de domínios. Consulte Restringir a pesquisa na web e a busca na web.
• Credenciais: Credenciais de variável de ambiente ainda não são compatíveis com sandboxes auto-hospedados.
• Isolamento e hardening: Você é responsável por ambos. Consulte o Modelo de segurança.

Nenhuma das opções altera a cobertura de conformidade do Managed Agents nem por quanto tempo ele mantém o histórico de sessões. Consulte Monitorar sessões e revisar a retenção.

Limitar a rede

Defina networking.type como limited e liste apenas os hosts de que o agente precisa em allowed_hosts. Uma requisição de criação de ambiente que omite networking pode receber unrestricted, então defina networking em toda requisição de criação. Consulte Riscos da rede irrestrita.

Arquivos, memory stores e repositórios do GitHub que você anexa permanecem disponíveis para o agente independentemente de allowed_hosts.

Os exemplos desta página usam um agente de suporte. Ele lê o ticket de um cliente, consulta o pedido, lê sua central de ajuda e redige uma resposta. Sua aplicação executa a consulta do pedido, que não precisa de nenhum host, então este ambiente permite um host, a central de ajuda, para web_fetch:

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: support-agent
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - help.example.com

Um ambiente limited tem três configurações de rede:

As configurações allow_package_managers e allow_mcp_servers não adicionam hosts para a pesquisa na web e a busca na web.

Deixe allow_mcp_servers desativado, que é o padrão, e liste o host de cada servidor MCP que você opera ou em que confia em allowed_hosts. Cada host que você lista também fica aberto ao código no sandbox. Com allow_mcp_servers desativado, uma verificação na criação da sessão rejeita a requisição se o host de um servidor MCP não estiver listado. Consulte Fornecer autenticação na criação da sessão. A mesma verificação é executada quando uma atualização de sessão altera mcp_servers.

Ao escolher hosts para allowed_hosts, siga estas duas regras:

• Liste apenas hosts que você opera ou em que confia.
• Evite curingas *. e domínios de hospedagem compartilhada onde qualquer pessoa pode publicar conteúdo.

Se o agente mantiver bash, defina a política de permissão da ferramenta bash conforme descrito em Aprovar ações arriscadas.

Consulte Configuração do ambiente em nuvem para ver todas as configurações de rede.

Manter as credenciais em vaults

Armazene todos os segredos em um vault. Para cada credencial de variável de ambiente, defina o local de injeção apenas como cabeçalhos de requisição e liste apenas os hosts aos quais o segredo se destina. O código no sandbox vê um placeholder em vez do segredo. O Managed Agents o substitui pelo segredo real apenas em requisições HTTPS de saída para os hosts que a credencial permite. Assim, o segredo fica fora do alcance direto do modelo, a menos que um serviço o envie de volta, como um endpoint que ecoa os cabeçalhos da requisição. Se o networking da credencial for unrestricted, o Managed Agents substitui o placeholder pelo segredo real em requisições para qualquer host que o ambiente permita ao sandbox alcançar. Para usar um vault, passe seu ID em vault_ids ao criar a sessão ou a implantação.

O agente de suporte não precisa de nenhuma credencial de vault, porque sua aplicação mantém a chave de API da sua API de pedidos. Se o seu agente tiver uma credencial de vault, consulte Adicionar uma credencial para ver a requisição em todas as linguagens.

Mantenha as chaves fora de prompts do sistema, definições de agentes e mensagens. Não dê ao agente uma chave de API do Claude. Mesmo quando uma chave de API do Claude está em um vault, o código no sandbox pode usá-la para chamar a API do Claude diretamente. Ele pode fazer qualquer coisa que essa chave permita, como iniciar ou excluir sessões, ou usar a pesquisa na web e a busca na web. As configurações de ferramentas, as aprovações e o orçamento do agente não se aplicam a essas chamadas. Em um ambiente limited, o código só pode fazer essas chamadas se allowed_hosts permitir que o sandbox alcance api.anthropic.com.

Obtenha os tokens você mesmo e armazene-os no vault, porque um token que o código no sandbox obtém com um segredo armazenado retorna sem redação.

Mantenha vaults para cargas de trabalho com diferentes níveis de confiança em workspaces separados, porque qualquer chave de API com acesso a um workspace pode referenciar seus vaults. Use chaves de API com escopo para um único workspace.

Consulte Autenticar com vaults para credenciais MCP e rotação.

Restringir a pesquisa na web e a busca na web

Defina allowed_domains em web_fetch com os sites de que o agente precisa. Qualquer URL que o agente busca pode levar dados ao site para o qual aponta, então essa lista é um controle de segurança. Em web_search, defina allowed_domains com os sites dos quais você quer resultados, para que os resultados venham apenas de sites em cuja precisão você confia. A lista não impede que a consulta de pesquisa chegue ao provedor de pesquisa. Os resultados de pesquisa incluem texto das páginas, então a lista também limita de quais sites o texto chega ao agente. Defina allowed_domains em ambas as ferramentas para todos os tipos de ambiente.

Uma lista blocked_domains bloqueia os hosts que você lista e seus subdomínios, e nenhum outro host. O mesmo conteúdo ainda pode chegar ao agente a partir de serviços de arquivamento da web, caches, espelhos ou domínios relacionados que você não listou. Não dependa de blocked_domains para segurança. Use allowed_domains e liste os hosts em que você confia.

Em um ambiente limited, a lista allowed_hosts de Limitar a rede também limita as ferramentas web. Um ambiente unrestricted ou um sandbox auto-hospedado não limita as ferramentas web.

As duas listas fazem a correspondência de hosts de forma diferente:

Se o agente precisa de um site e de todos os seus subdomínios, liste tanto example.com quanto *.example.com em allowed_hosts; caso contrário, liste hosts exatos. Se uma ferramenta lista example.com e allowed_hosts lista apenas *.example.com, a sessão é criada. A verificação na criação da sessão considera example.com como dentro de *.example.com, mas a ferramenta não retorna nada do próprio example.com. Consulte Definir listas de domínios em um agente para ver como as duas listas fazem a correspondência.

A ferramenta web_fetch também abre apenas URLs que já apareceram na sessão:

Em uma sessão multiagente, web_fetch abre uma URL vinda de outro agente apenas se ela chegou a esse agente por meio de uma fonte marcada com Sim. O resultado de uma ferramenta personalizada a partir de uma chamada direta conta como uma fonte marcada com Sim. Isso vale mesmo que o Claude tenha escrito o texto, por exemplo, quando a ferramenta repete sua entrada. Uma URL pode contar mesmo quando escrita sem https://, como example.com/docs. A ferramenta web_fetch nem sempre consegue abrir um link que mostra palavras em vez de sua URL, como "Fale com o suporte". Se o agente precisar buscar uma URL que não apareceu na sessão, envie-a em uma mensagem de usuário.

Essa regra reduz a chance de que um texto injetado construa uma URL que carregue dados privados. Texto de usuário final, resultados de pesquisa, páginas buscadas e resultados de ferramentas personalizadas ainda podem adicionar URLs, então mantenha allowed_domains definido. A Messages API aplica uma regra semelhante com uma lista diferente de fontes. Consulte Validação de URL.

Uma lista de domínios em web_fetch não limita a ferramenta bash. Limite a rede também. Consulte Regras da lista de domínios.

Aprovar ações arriscadas

Defina auto em bash, write, edit e web_fetch, e em ferramentas MCP que apenas leem dados. Use always_ask em uma ferramenta se você não puder desfazer suas alterações fora do sandbox. Use-o também em uma ferramenta que não deve ser executada só porque um texto de usuário final que você repassa pede isso. Uma política de permissão determina se uma chamada de ferramenta é executada, aguarda sua aprovação ou é avaliada pelo servidor.

O toolset em Dar ao agente o menor conjunto de ferramentas aplica essas políticas.

A política auto permite que o servidor execute uma chamada, a negue ou pause para aprovação. Uma pessoa não consegue aprovar todas as chamadas em uma execução longa, então o servidor verifica cada uma em seu lugar. Combine auto com rede limitada, uma chave com permissões restritas, um orçamento e um alerta para sessões ociosas. auto não é um ponto de verificação humano, então, se uma pessoa precisar revisar as chamadas de uma ferramenta antes de serem executadas, configure always_ask nessa ferramenta.

auto trata o texto em eventos user.message e a descrição em um evento user.define_outcome como sua instrução, incluindo texto de usuário final que você repassa.

Uma sessão pausada aguarda indefinidamente, então uma sessão sem supervisão precisa de um cliente que responda às chamadas pausadas ou interrompa a sessão.

Revise cada chamada pausada antes de permiti-la. Um cliente que permite todas as chamadas sem mostrá-las a uma pessoa é o mesmo que always_allow. Consulte Responder a solicitações de confirmação e Ver como cada chamada foi avaliada.

Dar ao agente o menor conjunto de ferramentas

Defina default_config.enabled como false e habilite apenas as ferramentas de que o agente precisa. O toolset do agente habilita todas as oito ferramentas integradas por padrão.

O agente de suporte precisa de três ferramentas integradas: read e write para seu rascunho, e web_fetch para a central de ajuda. Ele consulta pedidos por meio de uma ferramenta personalizada, lookup_order, que sua aplicação executa. Sua aplicação mantém a chave de API da sua API de pedidos, então o agente não precisa nem de bash nem de uma credencial.

O exemplo a seguir limita web_fetch a help.example.com com allowed_domains. Ele define auto em write e web_fetch, como recomenda Aprovar ações arriscadas. Se o ticket de um cliente levar o agente a usar essas ferramentas, o agente só pode alterar arquivos no sandbox ou abrir páginas da central de ajuda. É por isso que nenhuma das ferramentas precisa de always_ask. O exemplo também define always_ask em default_config, para que uma ferramenta que você habilitar depois sem política própria use always_ask:

ant apply agent.md

---
name: Support Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: false
      permission_policy:
        type: always_ask
    configs:
      - name: read
        enabled: true
        permission_policy:
          type: always_allow
      - name: write
        enabled: true
        permission_policy:
          type: auto
      - name: web_fetch
        enabled: true
        allowed_domains: [help.example.com]
        permission_policy:
          type: auto
  - type: custom
    name: lookup_order
    description: Look up one order by its ID. Returns the status, the items, and the delivery date.
    input_schema:
      type: object
      properties:
        order_id:
          type: string
          description: The order ID from the ticket
      required:
        - order_id
---

Uma atualização de agente substitui todo o array tools, então envie todas as entradas que você quer manter.

Uma atualização de agente alcança apenas novas sessões, então verifique também as implantações, os agentes que listam este agente e as sessões existentes:

• Uma implantação fixa uma versão do agente, então aponte cada implantação para a nova versão.
• Um agente que lista este em subagents.predefined_agents ou workflows.predefined_agents mantém a versão que fixou, então atualize esse agente também.
• Para restringir uma sessão que já existe, atualize as ferramentas dessa sessão. A sessão precisa estar idle, e a atualização substitui todo o array tools. Em uma sessão multiagente, novas listas allowed_domains e blocked_domains nas ferramentas web do agente que a sessão executa também se aplicam a todos os outros agentes. Elas se aplicam a partir do próximo turno de cada agente. As ferramentas habilitadas e as políticas de permissão desses agentes não mudam. Para alterá-las, atualize cada agente e então inicie uma nova sessão.

Limite também os servidores MCP e as ferramentas personalizadas ao que o agente precisa:

• Servidores MCP: Um toolset MCP habilita por padrão todas as ferramentas que o servidor expõe. Defina default_config.enabled como false e habilite ferramentas pelo nome, para que as ferramentas que um servidor adicionar depois permaneçam desativadas. Remova os servidores que o agente não usa. Consulte Conector MCP.
• Ferramentas personalizadas: Sua aplicação as executa, e as políticas de permissão não se aplicam. Valide a entrada de cada chamada em sua aplicação e limite o que a ferramenta pode acessar.

Manter entradas não confiáveis longe de ferramentas poderosas

Verifique quais ferramentas e credenciais um agente possui sempre que ele lê entradas não confiáveis, que são textos que alguém de fora da sua equipe pode escrever. Esta seção usa dois termos:

• Entrada não confiável: Páginas web, resultados de pesquisa, tickets de suporte, e-mails, arquivos de repositórios, uploads, resultados de servidores MCP e mensagens de usuários finais que você repassa.
• Ferramentas poderosas: bash, write, edit, web_fetch, web_search, ferramentas MCP e ferramentas personalizadas que gravam ou enviam dados, e qualquer ferramenta que use uma credencial.

Um texto em uma entrada não confiável pode instruir o agente a usar uma ferramenta poderosa que ele possui. O agente de suporte lê tickets, então ele alcança sua API de pedidos apenas por meio da ferramenta personalizada lookup_order. Sua aplicação verifica se o pedido pertence ao remetente do ticket.

Em um ambiente em nuvem, ler um arquivo com read também pode carregar arquivos CLAUDE.md e AGENTS.md como instruções. Eles são carregados do diretório do arquivo e de seus diretórios pais, até o diretório de trabalho do sandbox. Arquivos que eles referenciam com @ e um caminho, como @docs/setup.md, também são carregados, até cinco níveis de referência. Uma referência pode apontar para qualquer lugar no sandbox, por exemplo @/etc/hosts. Nenhuma configuração desativa isso, exceto desabilitar read, então trate um repositório, pacote ou arquivo compactado que alguém de fora da sua equipe pode escrever como entrada não confiável.

Quando um agente precisa ler entradas não confiáveis e também agir, este guia recomenda um de três designs:

• Separe a leitura da ação. Em uma sessão multiagente, um agente líder atribui tarefas a um buscador, que lê a web, e a um escritor, que altera arquivos ou registros.
• Dê ao agente uma única ferramenta personalizada restrita. Sua aplicação executa a ferramenta, verifica sua entrada e mantém a credencial. O agente de suporte usa este design, não a separação. Consulte Responder a chamadas de ferramenta que pausam a sessão.
• Mantenha uma pessoa no processo. Use always_ask na ferramenta poderosa para que uma pessoa aprove cada chamada.

A separação usa três agentes:

Os resultados do buscador são construídos a partir de páginas não confiáveis, e o líder pode repassar o texto deles ao escritor. Mantenha auto ou always_ask nas ferramentas do escritor. O buscador ainda pode enviar parte do que lê aos sites em sua lista de web_fetch e ao provedor de pesquisa em suas consultas.

Os agentes em uma sessão multiagente compartilham o sandbox, seus arquivos e as credenciais do vault, então essa separação isola apenas suas ferramentas e conversas. Para uma separação mais forte, use duas sessões com ambientes e vaults separados. Faça sua aplicação repassar apenas campos fixos, como um ID de pedido, entre as duas sessões.

Definir limites e uma forma de parar

Defina um orçamento ao criar cada sessão e decida com antecedência como você vai parar um agente.

Para parar um agente em execução, siga estas etapas:

1. Envie user.interrupt sozinho.
2. Para um agente agendado, pause também a implantação para que nenhuma nova execução agendada seja iniciada. Para encerrar o agendamento permanentemente, arquive a implantação.
3. Se uma chave puder estar exposta, faça a rotação dela no serviço que a emitiu.
4. Se o agente tiver execuções de workflow abertas, envie também uma user.message pedindo que ele as interrompa, porque uma interrupção não encerra nenhuma execução. Consulte Interromper uma sessão com execuções abertas para ver as chamadas de ferramentas a cancelar primeiro.
5. Aguarde a sessão ficar idle. Uma sessão em execução não pode ser arquivada nem excluída.
6. Arquive a sessão para manter seu histórico. Exclua-a quando não precisar mais do histórico.

Uma interrupção não desfaz o que o agente já fez ou enviou. Arquivar um agente não interrompe suas sessões em execução.

O max_list_cost.amount de um orçamento é um número inteiro de centavos de dólar americano escrito como string, então "125" significa $1,25. Consulte Definir um orçamento na criação da sessão.

Você não pode adicionar um orçamento a uma sessão criada sem um. Para alterar ou remover um teto, consulte Retomar uma sessão em seu orçamento. Depois de remover o teto de uma sessão, você não pode definir um novo.

Um orçamento limita os gastos, mas não limita o que o agente faz antes de atingir o teto. Para manter separadas cargas de trabalho com diferentes níveis de confiança, use workspaces separados. Dê a cada carga de trabalho uma chave de API com escopo para um único workspace, porque uma chave que pode alcançar vários workspaces pode agir em qualquer um deles.

Consulte Orçamentos de sessão, Operações de sessão e Implantações agendadas.

Próximos passos