---
title: Restringir domínios de pesquisa na web e web fetch
url: https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions
description: Controle quais sites as ferramentas de pesquisa na web e web fetch de um agente podem acessar, limite o conteúdo buscado e localize os resultados de pesquisa.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  betaHeader: managed-agents-2026-04-01
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed): stable
---

**Suporte da API**: O uso varia conforme o produto.

* **Messages API**: Defina `allowed_domains` ou `blocked_domains` na ferramenta `web_search` ou `web_fetch` na requisição.
* **Managed Agents**: Defina os mesmos campos no conjunto de ferramentas do agente; cada lista contém no máximo 64 domínios.

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](https://platform.claude.com/docs/pt-BR/managed-agents/tools#configuring-the-toolset). Cada uma dessas entradas de `configs` (csharp, go: `Configs`) aceita uma de duas listas:

* **`allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`):** A ferramenta pode acessar apenas esses hosts.
* **`blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`):** 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.

<Note>
  `web_search` e `web_fetch` são executadas nos servidores da Anthropic, não no sandbox. Um ambiente de nuvem com [rede](https://platform.claude.com/docs/pt-BR/managed-agents/environments#networking) `limited` também aplica seu `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) a elas; consulte [Definir listas de domínios em um agente](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#set-domain-lists-on-an-agent). A rede `unrestricted` e os ambientes auto-hospedados não as limitam. As listas por ferramenta restringem ainda mais essas ferramentas.
</Note>

As configurações de pesquisa na web da sua organização na página [**Recursos**](https://platform.claude.com/settings/capabilities) do Claude Console também se aplicam a `web_search` em uma sessão. Se um administrador desabilitar a pesquisa na web, as chamadas `web_search` retornam um resultado de erro ao agente, e a sessão continua. Se a organização restringir os domínios da pesquisa na web, o agente recebe apenas os resultados de pesquisa permitidos tanto pelas restrições de domínio da organização quanto pelas listas por ferramenta do agente.

As configurações de web fetch da sua organização na mesma página também se aplicam a `web_fetch` em uma sessão. Se um administrador desativar o web fetch, as chamadas `web_fetch` retornam um resultado de erro ao agente, e a sessão continua. Se a organização definir domínios permitidos ou bloqueados para o web fetch, uma URL precisa passar pela lista da organização e pelas listas por ferramenta do agente, assim como qualquer URL para a qual um redirecionamento leve. Uma chamada `web_fetch` para uma URL que qualquer uma delas exclua também retorna um resultado de erro ao agente.

## 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` (java, php: `userLocation`; csharp, go: `UserLocation`) e `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`). [Configurações](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#settings) descreve ambos.

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "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
            }
          ]
        }
      ]
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply agent.md
    ```

    <File filename="agent.md">
      ```markdown
      ---
      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
      ---
      ```
    </File>

    [`ant apply`](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/apply) cria o agente e imprime seu ID.
  </CodeGroupItem>

  ```python Python
  client = Anthropic()

  agent = client.beta.agents.create(
      name="Research Agent",
      model="claude-opus-5-5",
      tools=[
          {
              "type": "agent_toolset_20260401",
              "configs": [
                  {
                      "name": "web_search",
                      "allowed_domains": ["docs.example.com", "arxiv.org"],
                      "user_location": {
                          "type": "approximate",
                          "country": "US",
                          "timezone": "America/Los_Angeles",
                      },
                  },
                  {
                      "name": "web_fetch",
                      "blocked_domains": ["ads.example.com"],
                      "max_content_tokens": 50_000,
                  },
              ],
          }
      ],
  )

  for tool in agent.tools:
      if tool.type == "agent_toolset_20260401":
          print(json.dumps([config.to_dict() for config in tool.configs], indent=2))
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const agent = await client.beta.agents.create({
    name: "Research Agent",
    model: "claude-opus-5-5",
    tools: [
      {
        type: "agent_toolset_20260401",
        configs: [
          {
            name: "web_search",
            allowed_domains: ["docs.example.com", "arxiv.org"],
            user_location: {
              type: "approximate",
              country: "US",
              timezone: "America/Los_Angeles"
            }
          },
          {
            name: "web_fetch",
            blocked_domains: ["ads.example.com"],
            max_content_tokens: 50_000
          }
        ]
      }
    ]
  });

  for (const tool of agent.tools) {
    if (tool.type === "agent_toolset_20260401") {
      console.log(JSON.stringify(tool.configs, null, 2));
    }
  }
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Agents;

  AnthropicClient client = new();

  var agent = await client.Beta.Agents.Create(new()
  {
      Name = "Research Agent",
      Model = BetaManagedAgentsModel.ClaudeOpus5_5,
      Tools =
      [
          new BetaManagedAgentsAgentToolset20260401Params
          {
              Configs =
              [
                  new BetaManagedAgentsWebSearchToolConfigParams
                  {
                      AllowedDomains = ["docs.example.com", "arxiv.org"],
                      UserLocation = new()
                      {
                          Country = "US",
                          Timezone = "America/Los_Angeles",
                      },
                  },
                  new BetaManagedAgentsWebFetchToolConfigParams
                  {
                      BlockedDomains = ["ads.example.com"],
                      MaxContentTokens = 50_000,
                  },
              ],
          },
      ],
  });

  JsonSerializerOptions jsonOptions = new() { WriteIndented = true };
  foreach (var tool in agent.Tools)
  {
      if (tool.TryPickBetaManagedAgentsAgentToolset20260401(out var toolset))
      {
          Console.WriteLine(JsonSerializer.Serialize(toolset.Configs, jsonOptions));
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()
  ctx := context.Background()

  agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
  	Name: "Research Agent",
  	Model: anthropic.BetaManagedAgentsModelConfigParams{
  		ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  	},
  	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
  		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
  			Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{
  				{OfWebSearch: &anthropic.BetaManagedAgentsWebSearchToolConfigParams{
  					AllowedDomains: []string{"docs.example.com", "arxiv.org"},
  					UserLocation: anthropic.BetaManagedAgentsUserLocationParam{
  						Country:  anthropic.String("US"),
  						Timezone: anthropic.String("America/Los_Angeles"),
  					},
  				}},
  				{OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{
  					BlockedDomains:   []string{"ads.example.com"},
  					MaxContentTokens: anthropic.Int(50000),
  				}},
  			},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }

  for _, tool := range agent.Tools {
  	switch toolset := tool.AsAny().(type) {
  	case anthropic.BetaManagedAgentsAgentToolset20260401:
  		configs := make([]json.RawMessage, len(toolset.Configs))
  		for i, config := range toolset.Configs {
  			configs[i] = json.RawMessage(config.RawJSON())
  		}
  		output, err := json.MarshalIndent(configs, "", "  ")
  		if err != nil {
  			panic(err)
  		}
  		fmt.Println(string(output))
  	}
  }
  ```

  ```java Java
  import com.anthropic.models.beta.agents.AgentCreateParams;
  import com.anthropic.models.beta.agents.BetaManagedAgentsAgentToolset20260401Params;
  import com.anthropic.models.beta.agents.BetaManagedAgentsModel;
  import com.anthropic.models.beta.agents.BetaManagedAgentsUserLocation;
  import com.anthropic.models.beta.agents.BetaManagedAgentsWebFetchToolConfigParams;
  import com.anthropic.models.beta.agents.BetaManagedAgentsWebSearchToolConfigParams;

  void main() {
      var client = AnthropicOkHttpClient.fromEnv();

      var agent = client.beta().agents().create(AgentCreateParams.builder()
          .name("Research Agent")
          .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
          .addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
              .addConfig(BetaManagedAgentsWebSearchToolConfigParams.builder()
                  .allowedDomains(List.of("docs.example.com", "arxiv.org"))
                  .userLocation(BetaManagedAgentsUserLocation.builder()
                      .country("US")
                      .timezone("America/Los_Angeles")
                      .build())
                  .build())
              .addConfig(BetaManagedAgentsWebFetchToolConfigParams.builder()
                  .blockedDomains(List.of("ads.example.com"))
                  .maxContentTokens(50_000)
                  .build())
              .build())
          .build());

      for (var tool : agent.tools()) {
          if (tool.isAgentToolset20260401()) {
              var configs = tool.asAgentToolset20260401().configs();
              IO.println(ObjectMappers.jsonMapper().valueToTree(configs));
          }
      }
  }
  ```

  ```php PHP
  use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401;
  use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
  use Anthropic\Beta\Agents\BetaManagedAgentsModel;
  use Anthropic\Beta\Agents\BetaManagedAgentsUserLocation;
  use Anthropic\Beta\Agents\BetaManagedAgentsWebFetchToolConfigParams;
  use Anthropic\Beta\Agents\BetaManagedAgentsWebSearchToolConfigParams;
  // ...

  $client = new Client();

  $agent = $client->beta->agents->create(
      name: 'Research Agent',
      model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
      tools: [
          BetaManagedAgentsAgentToolset20260401Params::with(
              configs: [
                  BetaManagedAgentsWebSearchToolConfigParams::with(
                      allowedDomains: ['docs.example.com', 'arxiv.org'],
                      userLocation: BetaManagedAgentsUserLocation::with(
                          country: 'US',
                          timezone: 'America/Los_Angeles',
                      ),
                  ),
                  BetaManagedAgentsWebFetchToolConfigParams::with(
                      blockedDomains: ['ads.example.com'],
                      maxContentTokens: 50_000,
                  ),
              ],
          ),
      ],
  );

  foreach ($agent->tools as $tool) {
      if ($tool instanceof BetaManagedAgentsAgentToolset20260401) {
          echo json_encode($tool->configs, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  agent = client.beta.agents.create(
    name: "Research Agent",
    model: Anthropic::Beta::BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
    tools: [
      {
        type: :agent_toolset_20260401,
        configs: [
          {
            name: :web_search,
            allowed_domains: ["docs.example.com", "arxiv.org"],
            user_location: {type: :approximate, country: "US", timezone: "America/Los_Angeles"}
          },
          {
            name: :web_fetch,
            blocked_domains: ["ads.example.com"],
            max_content_tokens: 50_000
          }
        ]
      }
    ]
  )

  agent.tools.each do |tool|
    if tool.is_a?(Anthropic::Beta::BetaManagedAgentsAgentToolset20260401)
      puts JSON.pretty_generate(tool.configs.map(&:to_h))
    end
  end
  ```
</CodeGroup>

Em um ambiente de nuvem com [rede](https://platform.claude.com/docs/pt-BR/managed-agents/environments#networking) `limited`, o `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) do ambiente também se aplica a `web_search` e `web_fetch`. A criação de uma sessão falha com um erro 400 quando o `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) de uma ferramenta web habilitada tem uma entrada que não está dentro de `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). O mesmo acontece com uma atualização de sessão que adiciona tal entrada. Para corrigir, adicione o host a `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) ou remova a entrada de `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`). Em tempo de execução, uma chamada `web_fetch` para uma URL em um host que `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 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 abrange seus subdomínios, mas uma entrada de `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 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 um `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) de `["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 **Ferramentas integradas** no formulário do agente. Defina `max_content_tokens` e `user_location` na visualização **Bruto** da configuração do agente.

## Configurações

Além de `enabled` (csharp, go: `Enabled`) e `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`), as entradas das ferramentas web aceitam as seguintes configurações:

| Configuração | Aplica-se a | Descrição |
| ----- | ----- | ----- |
| `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) | `web_search`, `web_fetch` | Os únicos hosts que a ferramenta pode acessar. Consulte [Regras da lista de domínios](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#domain-list-rules). |
| `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) | `web_search`, `web_fetch` | Hosts que a ferramenta não pode acessar. Consulte [Regras da lista de domínios](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#domain-list-rules). |
| `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`) | `web_fetch` | Limita a quantidade de conteúdo de página buscado incluído no contexto. Deve ser um inteiro positivo. Consulte [limites de conteúdo](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-fetch-tool#content-limits). |
| `user_location` (java, php: `userLocation`; csharp, go: `UserLocation`) | `web_search` | Localiza os resultados de pesquisa. Um objeto com os mesmos campos do parâmetro [`user_location`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#localization) da Messages API. |

Para os tipos que o SDK usa para essas entradas, consulte [Tipos de entrada de configuração nos SDKs](https://platform.claude.com/docs/pt-BR/managed-agents/tools#config-entry-types-in-the-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` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) e `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`). A API rejeita uma requisição que viola alguma dessas regras, conforme descrito em [Erros de validação](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#validation-errors).

* **No máximo uma lista em uma entrada:** Defina `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) ou `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) 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 de `web_search` também pode incluir um caminho, conforme descrito em [Sufixos de caminho em domínios de pesquisa na web](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#path-suffixes-on-web-search-domains).

| Não aceito | Exemplo | Use em vez disso |
| ----- | ----- | ----- |
| Um esquema | `https://example.com` | `example.com` |
| Uma porta | `example.com:443` | `example.com` |
| Um curinga | `*.example.com` | `example.com` |
| Um caminho em um domínio de `web_fetch` | `example.com/*` | `example.com` |
| Um endereço IP em qualquer forma, seja IPv4, IPv6, entre colchetes ou abreviação numérica | `127.1` | O nome de domínio do site |
| Um domínio de nível superior isolado ou sufixo de registro | `com`, `co.uk`, `gov.uk` | Um domínio completo como `example.co.uk` |
| Um nome de rótulo único | `intranet` | Um domínio completo como `example.co.uk` |
| Caracteres não ASCII, como em um nome de domínio internacionalizado |  | A forma `xn--` (Punycode) |

A API também rejeita um domínio que contenha credenciais ou espaços em branco, ou que tenha um rótulo começando ou terminando com hífen. Ela também rejeita `localhost` e hosts terminados em `.localhost`, `.local`, `.internal`, `.localdomain` ou `.invalid`.

### 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](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup#create-an-agent) ou [atualiza um agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup#update-an-agent). Ela também as valida quando você cria ou atualiza uma sessão que fornece `tools` (csharp, go: `Tools`).

A API rejeita violações de formato e de limite com um erro 400 `invalid_request_error`:

| Violação | Mensagem de erro |
| ----- | ----- |
| Uma entrada define ambas as listas. | Inclui `Only one of allowed_domains or blocked_domains may be set.` |
| Uma lista está vazia. | Inclui `allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null.` |
| Um domínio viola uma regra de formato. | Indica a lista do domínio e a posição baseada em zero, como em `allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com"` |

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

* Um domínio em `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) que o crawler da Anthropic não tem permissão para acessar.
* Um `user_location.country` (java, php: `userLocation.country`; csharp, go: `UserLocation.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` (java, php: `userLocation.timezone`; csharp, go: `UserLocation.Timezone`) que não é um nome de fuso horário IANA válido.

Em um ambiente de nuvem com [rede](https://platform.claude.com/docs/pt-BR/managed-agents/environments#networking) `limited`, a criação e a atualização de sessões também verificam `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) em relação ao `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) do ambiente. Consulte a regra em [Definir listas de domínios em um agente](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#set-domain-lists-on-an-agent).

### 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`](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming). 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](https://platform.claude.com/docs/pt-BR/managed-agents/session-operations#updating-the-agent-configuration).
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](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration), todas as listas de domínios que se aplicam a uma thread são aplicadas ao mesmo tempo. Um agente listado na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) está sujeito a três conjuntos de listas por ferramenta:

* Seus próprios `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) e `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`)
* Os de qualquer agente que o chamou
* As listas atuais do agente que a sessão executa

As configurações se combinam da seguinte forma:

| Configuração | Como se combina |
| ----- | ----- |
| `allowed_domains` | A ferramenta pode acessar um host somente se todas as listas o cobrirem. |
| `blocked_domains` | As listas se somam. |
| `max_content_tokens`, `user_location` | Não são combinadas. Uma thread usa o valor de sua própria configuração de ferramenta, se definido. Caso contrário, usa o valor do agente que a chamou e, caso contrário, a configuração atual do agente da sessão. |

Um agente listado pode, portanto, restringir o que uma ferramenta acessa, mas nunca ampliá-lo:

* Um agente listado que define `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) mantém o `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) do agente da sessão e bloqueia esses hosts dentro dele.
* Um agente listado que define seu próprio `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) só pode acessar os hosts cobertos tanto pela sua lista quanto pela lista do agente da sessão.

Uma entrada `{"type": "self"}` na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) não tem configurações web próprias e segue as configurações atuais do agente da sessão.

Se as listas `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) 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` cujo texto inclui `no domain is permitted`. A descrição da ferramenta informa o mesmo ao modelo. Para evitar isso, mantenha o `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) de cada agente listado dentro do `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) do agente da sessão.

O avaliador em [sessões orientadas a resultados](https://platform.claude.com/docs/pt-BR/managed-agents/define-outcomes) é 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](https://platform.claude.com/docs/pt-BR/managed-agents/session-operations#updating-the-agent-configuration). 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. Para um agente listado na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), a atualização não altera as listas próprias do agente. 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` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) e `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) da [filtragem de domínios](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#domain-filtering) nas ferramentas de servidor da Messages API. O Managed Agents difere de quatro maneiras:

* Cada lista é [limitada a 64 domínios](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#domain-list-rules).
* Domínios listados para `web_fetch` [não podem incluir um caminho](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#domain-format).
* Domínios [devem ser ASCII](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#domain-format). A Messages API aceita entradas Unicode, embora não as recomende.
* `max_uses` (java, php: `maxUses`; csharp, go: `MaxUses`), `citations` (csharp, go: `Citations`) e `cache_control` (java, php: `cacheControl`; csharp, go: `CacheControl`) não estão disponíveis no conjunto de ferramentas.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Ferramentas" icon="tool" href="https://platform.claude.com/docs/pt-BR/managed-agents/tools">
    Veja as ferramentas integradas, habilite-as ou desabilite-as e defina ferramentas personalizadas.
  </Card>

  <Card title="Políticas de permissão" icon="lock" href="https://platform.claude.com/docs/pt-BR/managed-agents/permission-policies">
    Controle quando as ferramentas do agente e de MCP são executadas.
  </Card>

  <Card title="Configuração do ambiente em nuvem" icon="settings" href="https://platform.claude.com/docs/pt-BR/managed-agents/environments">
    Controle o acesso de rede de saída do próprio sandbox.
  </Card>

  <Card title="Orquestração multiagente" icon="sitemap" href="https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration">
    Coordene vários agentes em uma única sessão.
  </Card>
</CardGroup>

## Disponibilidade

Restrições de domínio na web estão disponíveis ou em beta, conforme a API.

### Suporte da API

#### [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages)

* Disponibilidade: Disponível
* Uso: Defina `allowed_domains` ou `blocked_domains` na ferramenta `web_search` ou `web_fetch` na requisição.

| Status | Plataformas de nuvem |
| ----- | ----- |
| Disponível | Claude API, [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed) |

#### [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview)

* Disponibilidade: Disponível
* Uso: Defina os mesmos campos nas entradas `web_search` e `web_fetch` do conjunto de ferramentas do agente. Diferentemente da Messages API, cada lista contém no máximo 64 domínios ASCII, e os domínios de `web_fetch` não podem incluir um caminho.

| Status | Plataformas de nuvem | Modelos |
| ----- | ----- | ----- |
| Beta | Todas as plataformas compatíveis | [Todos os modelos](https://platform.claude.com/docs/pt-BR/models/overview) |

### Cabeçalhos beta obrigatórios

[Visão geral dos cabeçalhos beta](https://platform.claude.com/docs/pt-BR/api/beta-headers)

Os cabeçalhos beta permitem que você acesse recursos experimentais e novas capacidades de modelos antes que eles se tornem parte da API padrão.

| Cabeçalho | APIs |
| ----- | ----- |
| `managed-agents-2026-04-01` | [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview) |
