Restringir domínios de pesquisa na web e busca na web

Para controlar quais sites as ferramentas web do agente podem acessar, defina uma lista de domínios nas entradas web_search e web_fetch do conjunto de ferramentas do agente. Cada uma dessas entradas de configs aceita uma de duas listas:

• allowed_domains: A ferramenta pode acessar apenas esses hosts.
• blocked_domains: A ferramenta nunca pode acessar esses hosts.

Cada ferramenta tem sua própria lista, então web_search e web_fetch podem ter restrições diferentes.

Definir listas de domínios em um agente

O exemplo a seguir cria um agente que limita web_search a dois sites e bloqueia um host para web_fetch. Ele também define user_location e max_content_tokens, descritos em Configurações. Em seguida, o exemplo imprime o array configs da resposta.

ant apply agent.md

---
name: Research Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - type: web_search
        name: web_search
        allowed_domains: [docs.example.com, arxiv.org]
        user_location:
          type: approximate
          country: US
          timezone: America/Los_Angeles
      - type: web_fetch
        name: web_fetch
        blocked_domains: [ads.example.com]
        max_content_tokens: 50000
---

Em um ambiente de nuvem com rede limited, os allowed_hosts do ambiente também se aplicam a web_search e web_fetch. A criação de uma sessão falha com um erro 400 quando os allowed_domains de uma ferramenta web habilitada têm uma entrada que não está dentro de allowed_hosts. O mesmo acontece com uma atualização de sessão que adiciona tal entrada. Para corrigir, adicione o host a allowed_hosts ou remova a entrada de allowed_domains. Em tempo de execução, uma chamada web_fetch para uma URL em um host que allowed_hosts não corresponde retorna um resultado de erro url_not_allowed. web_search omite resultados desses hosts. As duas listas fazem a correspondência de forma diferente: a entrada de uma ferramenta cobre seus subdomínios, mas uma entrada de allowed_hosts corresponde a um único host exato, a menos que comece com *.. Por exemplo, a entrada de ferramenta docs.example.com não está dentro de allowed_hosts igual a ["example.com"], mas está dentro de ["docs.example.com"] ou ["*.example.com"].

No Claude Console, defina domínios permitidos ou bloqueados nas linhas web_search e web_fetch do cartão Built-in tools no formulário do agente. Defina max_content_tokens e user_location na visualização Raw da configuração do agente.

Configurações

Além de enabled e permission_policy, as entradas das ferramentas web aceitam as seguintes configurações:

Para saber como os SDKs tipam essas entradas, consulte Tipos de entrada de configuração nos SDKs.

Quando um domínio não é permitido

web_search omite resultados que sua lista de domínios não permite. Uma chamada web_fetch para uma URL que sua lista de domínios não permite retorna um resultado de erro ao agente. O evento agent.tool_result tem is_error: true, e seu conteúdo indica o código de erro url_not_allowed.

Regras da lista de domínios

Estas regras se aplicam igualmente a allowed_domains e blocked_domains. Uma requisição que viole alguma delas é rejeitada, conforme descrito em Erros de validação.

• Uma lista por entrada: Defina allowed_domains ou blocked_domains em uma entrada, não ambos.
• Tamanho da lista: Cada lista contém de 1 a 64 domínios, cada um com 1 a 255 caracteres.
• Sem listas vazias: Para não aplicar nenhuma restrição, omita o campo ou envie null.
• Sem duplicatas: Um domínio pode aparecer apenas uma vez em uma lista. www.example.com e example.com contam como domínios diferentes.

A que um domínio listado corresponde

Um domínio listado corresponde a esse host e a todos os seus subdomínios. example.com cobre docs.example.com, mas docs.example.com não cobre example.com nem api.example.com.

Um www. inicial é um subdomínio como qualquer outro, então www.example.com não cobre example.com. Liste o domínio simples para cobrir ambos.

Os nomes de host são comparados sem diferenciar maiúsculas de minúsculas.

Formato do domínio

Cada domínio é um nome de domínio registrável, ou um subdomínio de um, escrito como um nome de host simples. Ele pode conter letras ASCII, dígitos, hifens, sublinhados e pontos. Uma única / final é ignorada.

Um domínio também é rejeitado se contiver credenciais ou espaços em branco, ou se um de seus rótulos começar ou terminar com hífen. localhost e hosts terminados em .localhost, .local, .internal, .localdomain ou .invalid também são rejeitados.

Sufixos de caminho em domínios de pesquisa na web

Um domínio de web_search pode ter um sufixo de caminho, como example.com/blog. O caminho não pode conter espaços, ?, # ou qualquer um dos caracteres $ , | ^ !.

Prefira nomes de host simples também para web_search. O provedor de pesquisa corresponde sufixos de caminho como padrões de URL, e não como regras estritas de host.

Erros de validação

A API valida essas configurações quando você cria um agente ou atualiza um agente. Ela também as valida quando você cria ou atualiza uma sessão que fornece tools.

Violações de formato e de limite são rejeitadas com um erro 400 invalid_request_error:

Nas mesmas requisições, a API também rejeita três configurações que dependem dos provedores de pesquisa e busca:

• Um domínio em allowed_domains que o crawler da Anthropic não tem permissão para acessar.
• Um user_location.country que o provedor de pesquisa não suporta. A mensagem termina em user_location.country: not a country the search provider supports.
• Um user_location.timezone que não é um nome IANA válido.

Em um ambiente de nuvem com rede limited, a criação e a atualização de sessões também verificam allowed_domains em relação aos allowed_hosts do ambiente. Consulte a regra em Definir listas de domínios em um agente.

Quando uma configuração aceita deixa de ser válida

A sessão verifica a configuração novamente quando inicializa a ferramenta pela primeira vez. Se uma configuração aceita anteriormente não for mais válida nesse momento, a sessão emite um evento session.error. Em seguida, ela retorna a idle sem tentar novamente.

Para continuar a sessão:

1. Corrija a configuração atualizando as ferramentas da sessão.
2. Atualize também o agente, para que novas sessões comecem com a configuração corrigida.
3. Envie uma nova user.message.

Sessões multiagente e orientadas a resultados

Em uma sessão multiagente, todas as listas de domínios que se aplicam a uma thread são aplicadas ao mesmo tempo. Um agente na lista (roster) do coordenador está sujeito a três conjuntos de listas:

• Seus próprios allowed_domains e blocked_domains
• Os de qualquer agente que o chamou
• As listas atuais do coordenador

As configurações se combinam da seguinte forma:

Portanto, um agente do roster pode restringir o que uma ferramenta acessa, mas nunca ampliá-lo:

• Um agente do roster que define blocked_domains mantém os allowed_domains do coordenador e bloqueia esses hosts dentro deles.
• Um agente do roster que define seus próprios allowed_domains pode acessar apenas os hosts cobertos tanto por sua lista quanto pela lista do coordenador.

Uma entrada de roster {"type": "self"} não tem configurações web próprias e segue as configurações atuais do coordenador.

Se as listas allowed_domains combinadas não tiverem nenhum domínio em comum, a ferramenta permanece disponível para esse agente, mas todas as chamadas falham. Cada chamada retorna um erro url_not_allowed informando que nenhum domínio é permitido. A descrição da ferramenta informa o mesmo ao modelo. Para evitar isso, mantenha os allowed_domains de cada agente do roster dentro dos do coordenador.

O avaliador em sessões orientadas a resultados é executado sem web_search e web_fetch, independentemente dessas configurações.

Alterar as listas no meio da sessão

Você pode alterar as listas em uma sessão ociosa atualizando suas ferramentas. As novas listas se aplicam ao restante da sessão.

Em uma sessão multiagente, cada thread aplica as novas listas a partir de seu próximo turno. A atualização não altera as listas próprias de um agente do roster. Elas permanecem como a definição do agente as estabeleceu quando a sessão foi criada.

Diferenças em relação às ferramentas da Messages API

Essas configurações usam os mesmos campos allowed_domains e blocked_domains da filtragem de domínios nas ferramentas de servidor da Messages API. O Managed Agents difere de quatro maneiras:

• Cada lista é limitada a 64 domínios.
• Domínios listados para web_fetch não podem incluir um caminho.
• Domínios devem ser ASCII. A Messages API aceita entradas Unicode, embora não as recomende.
• max_uses, citations e cache_control não estão disponíveis no conjunto de ferramentas.

Próximos passos