---
title: Limitare i domini di ricerca web e web fetch
url: https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions
description: Controlla quali siti possono raggiungere gli strumenti di ricerca web e web fetch di un agente, limita il contenuto recuperato e localizza i risultati di ricerca.
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
---

**Supporto API**: L’utilizzo varia in base al prodotto.

* **Messages API**: Imposta `allowed_domains` o `blocked_domains` sullo strumento `web_search` o `web_fetch` nella richiesta.
* **Managed Agents**: Imposta gli stessi campi nel toolset dell’agente; ogni elenco contiene al massimo 64 domini.

Per controllare quali siti possono raggiungere gli strumenti web dell’agente, imposta un elenco di domini sulle voci `web_search` e `web_fetch` del [toolset dell’agente](https://platform.claude.com/docs/it/managed-agents/tools#configuring-the-toolset). Ciascuna di queste voci `configs` (csharp, go: `Configs`) accetta uno di due elenchi:

* **`allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`):** Lo strumento può raggiungere solo questi host.
* **`blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`):** Lo strumento non può mai raggiungere questi host.

Ogni strumento ha il proprio elenco, quindi `web_search` e `web_fetch` possono avere restrizioni diverse.

<Note>
  `web_search` e `web_fetch` vengono eseguiti sui server di Anthropic, non nella sandbox. Un ambiente cloud con [rete](https://platform.claude.com/docs/it/managed-agents/environments#networking) `limited` applica anche a essi il proprio `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`); consulta [Impostare elenchi di domini su un agente](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#set-domain-lists-on-an-agent). Il networking `unrestricted` e gli ambienti self-hosted non li limitano. Gli elenchi per singolo strumento limitano ulteriormente questi strumenti.
</Note>

Anche le impostazioni di ricerca web della tua organizzazione nella pagina [**Funzionalità**](https://platform.claude.com/settings/capabilities) della Claude Console si applicano a `web_search` in una sessione. Se un amministratore disabilita la ricerca web, le chiamate `web_search` restituiscono un risultato di errore all’agente e la sessione continua. Se l’organizzazione limita i domini di ricerca web, l’agente riceve solo i risultati di ricerca consentiti sia dalle restrizioni di dominio dell’organizzazione sia dagli elenchi per singolo strumento dell’agente.

Anche le impostazioni di web fetch della tua organizzazione nella stessa pagina si applicano a `web_fetch` in una sessione. Se un amministratore disattiva web fetch, le chiamate `web_fetch` restituiscono un risultato di errore all’agente e la sessione continua. Se l’organizzazione imposta domini consentiti o bloccati per web fetch, un URL deve superare l’elenco dell’organizzazione e gli elenchi per singolo strumento dell’agente, così come qualsiasi URL a cui porta un reindirizzamento. Anche una chiamata `web_fetch` per un URL escluso da uno qualsiasi di essi restituisce un risultato di errore all’agente.

## Impostare elenchi di domini su un agente

L’esempio seguente crea un agente che limita `web_search` a due siti e blocca un host per `web_fetch`. Imposta inoltre `user_location` (java, php: `userLocation`; csharp, go: `UserLocation`) e `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`). [Impostazioni](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#settings) li descrive entrambi.

<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/it/cli-sdks-libraries/cli/apply) crea l’agente e ne stampa l’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>

In un ambiente cloud con [rete](https://platform.claude.com/docs/it/managed-agents/environments#networking) `limited`, anche l’`allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) dell’ambiente si applica a `web_search` e `web_fetch`. La creazione di una sessione fallisce con un errore 400 quando l’`allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) di uno strumento web abilitato contiene una voce che non rientra in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Lo stesso vale per un aggiornamento della sessione che aggiunge una voce di questo tipo. Per risolvere, aggiungi l’host a `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) oppure rimuovi la voce da `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`). In fase di esecuzione, una chiamata `web_fetch` per un URL su un host che non corrisponde a `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) restituisce un risultato di errore `url_not_allowed`. `web_search` omette i risultati provenienti da tali host. I due elenchi effettuano la corrispondenza in modo diverso: la voce di uno strumento copre i suoi sottodomini, mentre una voce di `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) corrisponde a un unico host esatto, a meno che non inizi con `*.`. Ad esempio, la voce dello strumento `docs.example.com` non rientra in un `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) pari a `["example.com"]`, ma rientra in `["docs.example.com"]` o `["*.example.com"]`.

Nella Claude Console, imposta i domini consentiti o bloccati dalle righe `web_search` e `web_fetch` della scheda **Strumenti integrati** nel modulo dell’agente. Imposta `max_content_tokens` e `user_location` nella vista **Non elaborato** della configurazione dell’agente.

## Impostazioni

Oltre a `enabled` (csharp, go: `Enabled`) e `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`), le voci degli strumenti web accettano le seguenti impostazioni:

| Impostazione | Si applica a | Descrizione |
| ----- | ----- | ----- |
| `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) | `web_search`, `web_fetch` | Gli unici host che lo strumento può raggiungere. Consulta [Regole degli elenchi di domini](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#domain-list-rules). |
| `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) | `web_search`, `web_fetch` | Host che lo strumento non può raggiungere. Consulta [Regole degli elenchi di domini](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#domain-list-rules). |
| `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`) | `web_fetch` | Limita la quantità di contenuto delle pagine recuperate incluso nel contesto. Deve essere un numero intero positivo. Consulta i [limiti di contenuto](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-fetch-tool#content-limits). |
| `user_location` (java, php: `userLocation`; csharp, go: `UserLocation`) | `web_search` | Localizza i risultati di ricerca. Un oggetto con gli stessi campi del parametro [`user_location`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#localization) della Messages API. |

Per i tipi che l’SDK usa per queste voci, consulta [Tipi delle voci di configurazione negli SDK](https://platform.claude.com/docs/it/managed-agents/tools#config-entry-types-in-the-sdks).

## Quando un dominio non è consentito

`web_search` omette i risultati che il suo elenco di domini non consente. Una chiamata `web_fetch` per un URL che il suo elenco di domini non consente restituisce un risultato di errore all’agente. L’evento `agent.tool_result` ha `is_error: true` e il suo contenuto indica il codice di errore `url_not_allowed`.

## Regole degli elenchi di domini

Queste regole si applicano allo stesso modo a `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) e `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`). L’API rifiuta una richiesta che viola una qualsiasi di queste regole, come descritto in [Errori di convalida](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#validation-errors).

* **Al massimo un elenco per voce:** Imposta su una voce `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) oppure `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`), non entrambi.
* **Dimensione dell’elenco:** Ogni elenco contiene da 1 a 64 domini, ciascuno da 1 a 255 caratteri.
* **Nessun elenco vuoto:** Per non applicare alcuna restrizione, ometti il campo o invia `null`.
* **Nessun duplicato:** Un dominio può comparire una sola volta in un elenco. `www.example.com` e `example.com` contano come domini diversi.

### A cosa corrisponde un dominio elencato

Un dominio elencato corrisponde a quell’host e a tutti i suoi sottodomini. `example.com` copre `docs.example.com`, ma `docs.example.com` non copre `example.com` né `api.example.com`.

Un `www.` iniziale è un sottodominio come qualsiasi altro, quindi `www.example.com` non copre `example.com`. Elenca il dominio semplice per coprirli entrambi.

I nomi host vengono confrontati senza distinzione tra maiuscole e minuscole.

### Formato del dominio

Ogni dominio è un nome di dominio registrabile, o un suo sottodominio, scritto come semplice nome host. Può contenere lettere ASCII, cifre, trattini, trattini bassi e punti. Una singola `/` finale viene ignorata. Un dominio di `web_search` può anche includere un percorso, come descritto in [Suffissi di percorso sui domini di ricerca web](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#path-suffixes-on-web-search-domains).

| Non accettato | Esempio | Usa invece |
| ----- | ----- | ----- |
| Uno schema | `https://example.com` | `example.com` |
| Una porta | `example.com:443` | `example.com` |
| Un wildcard | `*.example.com` | `example.com` |
| Un percorso su un dominio `web_fetch` | `example.com/*` | `example.com` |
| Un indirizzo IP in qualsiasi forma, che sia IPv4, IPv6, tra parentesi quadre o in forma numerica abbreviata | `127.1` | Il nome di dominio del sito |
| Un dominio di primo livello semplice o un suffisso di registro | `com`, `co.uk`, `gov.uk` | Un dominio completo come `example.co.uk` |
| Un nome a etichetta singola | `intranet` | Un dominio completo come `example.co.uk` |
| Caratteri non ASCII, come in un nome di dominio internazionalizzato |  | La forma `xn--` (Punycode) |

L’API rifiuta anche un dominio che contiene credenziali o spazi, oppure che ha un’etichetta che inizia o termina con un trattino. Rifiuta anche `localhost` e gli host che terminano con `.localhost`, `.local`, `.internal`, `.localdomain` o `.invalid`.

### Suffissi di percorso sui domini di ricerca web

Un dominio `web_search` può includere un suffisso di percorso, come `example.com/blog`. Il percorso non può contenere spazi, `?`, `#` o uno qualsiasi dei caratteri `$ , | ^ !`.

Preferisci nomi host semplici anche per `web_search`. Il provider di ricerca confronta i suffissi di percorso come pattern URL anziché come regole rigide sugli host.

## Errori di convalida

L’API convalida queste impostazioni quando [crei un agente](https://platform.claude.com/docs/it/managed-agents/agent-setup#create-an-agent) o [aggiorni un agente](https://platform.claude.com/docs/it/managed-agents/agent-setup#update-an-agent). Le convalida anche quando crei o aggiorni una sessione che fornisce `tools` (csharp, go: `Tools`).

L’API rifiuta le violazioni di formato e di limiti con un errore 400 `invalid_request_error`:

| Violazione | Messaggio di errore |
| ----- | ----- |
| Una voce imposta entrambi gli elenchi. | Include `Only one of allowed_domains or blocked_domains may be set.` |
| Un elenco è vuoto. | Include `allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null.` |
| Un dominio viola una regola di formato. | Indica l’elenco del dominio e la posizione a partire da zero, come in `allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com"` |

Nelle stesse richieste, l’API rifiuta anche tre impostazioni che dipendono dai provider di ricerca e recupero:

* Un dominio in `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) a cui il crawler di Anthropic non è autorizzato ad accedere.
* Un `user_location.country` (java, php: `userLocation.country`; csharp, go: `UserLocation.Country`) che il provider di ricerca non supporta. Il messaggio termina con `user_location.country: not a country the search provider supports`.
* Un `user_location.timezone` (java, php: `userLocation.timezone`; csharp, go: `UserLocation.Timezone`) che non è un nome di fuso orario IANA valido.

In un ambiente cloud con [rete](https://platform.claude.com/docs/it/managed-agents/environments#networking) `limited`, la creazione e l’aggiornamento della sessione verificano anche `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) rispetto all’`allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) dell’ambiente. Consulta la regola in [Impostare elenchi di domini su un agente](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#set-domain-lists-on-an-agent).

### Quando un’impostazione accettata non è più valida

La sessione verifica nuovamente la configurazione quando inizializza lo strumento per la prima volta. Se un’impostazione accettata in precedenza non è più valida in quel momento, la sessione emette un evento [`session.error`](https://platform.claude.com/docs/it/managed-agents/events-and-streaming). Torna quindi a `idle` senza riprovare.

Per continuare la sessione:

1. Correggi l’impostazione [aggiornando gli strumenti della sessione](https://platform.claude.com/docs/it/managed-agents/session-operations#updating-the-agent-configuration).
2. Aggiorna anche l’agente, in modo che le nuove sessioni inizino con la configurazione corretta.
3. Invia un nuovo `user.message`.

## Sessioni multiagente e orientate agli esiti

In una [sessione multiagente](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration), ogni elenco di domini che si applica a un thread viene applicato contemporaneamente. Un agente elencato nell’elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) è vincolato da tre insiemi di elenchi per singolo strumento:

* I propri `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) e `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`)
* Quelli di qualsiasi agente che lo ha chiamato
* Gli elenchi correnti dell’agente eseguito dalla sessione

Le impostazioni si combinano come segue:

| Impostazione | Come si combina |
| ----- | ----- |
| `allowed_domains` | Lo strumento può raggiungere un host solo se ogni elenco lo copre. |
| `blocked_domains` | Gli elenchi si sommano. |
| `max_content_tokens`, `user_location` | Non combinate. Un thread usa il valore della propria configurazione dello strumento, se impostato. Altrimenti usa il valore dell’agente che lo ha chiamato e, in mancanza di questo, la configurazione corrente dell’agente della sessione. |

Un agente elencato può quindi restringere ciò che uno strumento raggiunge, ma mai ampliarlo:

* Un agente elencato che imposta `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) mantiene gli `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) dell’agente della sessione e blocca quegli host al loro interno.
* Un agente elencato che imposta i propri `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) può raggiungere solo gli host che sia il suo elenco sia l’elenco dell’agente della sessione coprono.

Una voce `{"type": "self"}` nell’elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`) non ha impostazioni web proprie e segue le impostazioni correnti dell’agente della sessione.

Se gli elenchi `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) combinati non hanno alcun dominio in comune, lo strumento rimane disponibile per quell’agente, ma ogni chiamata fallisce. Ogni chiamata restituisce un errore `url_not_allowed` il cui testo include `no domain is permitted`. La descrizione dello strumento comunica lo stesso al modello. Per evitarlo, mantieni gli `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) di ciascun agente elencato all’interno degli `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) dell’agente della sessione.

Il grader nelle [sessioni orientate agli esiti](https://platform.claude.com/docs/it/managed-agents/define-outcomes) viene eseguito senza `web_search` e `web_fetch`, indipendentemente da queste impostazioni.

## Modificare gli elenchi durante la sessione

Puoi modificare gli elenchi su una sessione inattiva [aggiornandone gli strumenti](https://platform.claude.com/docs/it/managed-agents/session-operations#updating-the-agent-configuration). I nuovi elenchi si applicano al resto della sessione.

In una sessione multiagente, ogni thread applica i nuovi elenchi a partire dal turno successivo. Per un agente elencato nell’elenco `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) di `subagents` (csharp, go: `Subagents`), l’aggiornamento non modifica gli elenchi propri dell’agente. Questi restano come li ha impostati la definizione dell’agente al momento della creazione della sessione.

## Differenze rispetto agli strumenti della Messages API

Queste impostazioni usano gli stessi campi `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) e `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) del [filtraggio dei domini](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#domain-filtering) sugli strumenti server della Messages API. Managed Agents differisce in quattro modi:

* Ogni elenco è [limitato a 64 domini](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#domain-list-rules).
* I domini elencati per `web_fetch` [non possono includere un percorso](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#domain-format).
* I domini [devono essere ASCII](https://platform.claude.com/docs/it/managed-agents/tools-web-restrictions#domain-format). La Messages API accetta voci Unicode, anche se ne sconsiglia l’uso.
* `max_uses` (java, php: `maxUses`; csharp, go: `MaxUses`), `citations` (csharp, go: `Citations`) e `cache_control` (java, php: `cacheControl`; csharp, go: `CacheControl`) non sono disponibili nel toolset.

## Passaggi successivi

<CardGroup cols={2}>
  <Card title="Strumenti" icon="tool" href="https://platform.claude.com/docs/it/managed-agents/tools">
    Scopri gli strumenti integrati, abilitali o disabilitali e definisci strumenti personalizzati.
  </Card>

  <Card title="Policy di autorizzazione" icon="lock" href="https://platform.claude.com/docs/it/managed-agents/permission-policies">
    Controlla quando vengono eseguiti gli strumenti dell’agente e MCP.
  </Card>

  <Card title="Configurazione dell’ambiente cloud" icon="settings" href="https://platform.claude.com/docs/it/managed-agents/environments">
    Controlla l’accesso di rete in uscita della sandbox stessa.
  </Card>

  <Card title="Orchestrazione multiagente" icon="sitemap" href="https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration">
    Coordina più agenti all’interno di una singola sessione.
  </Card>
</CardGroup>

## Disponibilità

La funzionalità Restrizioni dei domini web è disponibile o in beta, a seconda dell’API.

### Supporto API

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

* Disponibilità: Disponibile
* Utilizzo: Imposta `allowed_domains` o `blocked_domains` sullo strumento `web_search` o `web_fetch` nella richiesta.

| Stato | Piattaforme cloud |
| ----- | ----- |
| Disponibile | Claude API, [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed) |

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

* Disponibilità: Disponibile
* Utilizzo: Imposta gli stessi campi nelle voci `web_search` e `web_fetch` del toolset dell’agente. A differenza della Messages API, ogni elenco contiene al massimo 64 domini ASCII e i domini di `web_fetch` non possono includere un percorso.

| Stato | Piattaforme cloud | Modelli |
| ----- | ----- | ----- |
| Beta | Tutte le piattaforme supportate | [Tutti i modelli](https://platform.claude.com/docs/it/models/overview) |

### Header beta richiesti

[Panoramica degli header beta](https://platform.claude.com/docs/it/api/beta-headers)

Gli header beta consentono di accedere a funzionalità sperimentali e a nuove capacità dei modelli prima che entrino a far parte dell’API standard.

| Header | API |
| ----- | ----- |
| `managed-agents-2026-04-01` | [Managed Agents](https://platform.claude.com/docs/it/managed-agents/overview) |
