Ограничение доменов для веб-поиска и веб-загрузки

Чтобы управлять тем, к каким сайтам могут обращаться веб-инструменты агента, задайте список доменов в записях web_search и web_fetch набора инструментов агента. Каждая из этих записей configs принимает один из двух списков:

• allowed_domains: инструмент может обращаться только к этим хостам.
• blocked_domains: инструмент никогда не может обращаться к этим хостам.

У каждого инструмента свой список, поэтому для web_search и web_fetch можно задать разные ограничения.

Задание списков доменов для агента

В следующем примере создаётся агент, который ограничивает web_search двумя сайтами и блокирует один хост для web_fetch. Также задаются user_location и max_content_tokens, описанные в разделе Настройки. Затем пример выводит массив configs из ответа.

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
---

В облачной среде в сетевом режиме limited список allowed_hosts среды также применяется к web_search и web_fetch. Создание сессии завершается ошибкой 400, если allowed_domains включённого веб-инструмента содержит запись, не входящую в allowed_hosts. То же происходит при обновлении сессии, которое добавляет такую запись. Чтобы исправить это, добавьте хост в allowed_hosts или удалите запись из allowed_domains. Во время выполнения вызов web_fetch для URL на хосте, которому не соответствует allowed_hosts, возвращает результат с ошибкой url_not_allowed. web_search исключает результаты с таких хостов. Два списка сопоставляются по-разному: запись инструмента охватывает свои поддомены, а запись allowed_hosts соответствует ровно одному хосту, если только она не начинается с *.. Например, запись инструмента docs.example.com не входит в allowed_hosts со значением ["example.com"], но входит в ["docs.example.com"] или ["*.example.com"].

В Claude Console задайте разрешённые или заблокированные домены в строках web_search и web_fetch карточки Built-in tools в форме агента. Задайте max_content_tokens и user_location в представлении Raw конфигурации агента.

Настройки

Помимо enabled и permission_policy, записи веб-инструментов принимают следующие настройки:

О том, как SDK типизируют эти записи, см. Типы записей конфигурации в SDK.

Когда домен не разрешён

web_search исключает результаты, которые не разрешены его списком доменов. Вызов web_fetch для URL, не разрешённого его списком доменов, возвращает агенту результат с ошибкой. Событие agent.tool_result имеет is_error: true, а его содержимое указывает код ошибки url_not_allowed.

Правила списков доменов

Эти правила одинаково применяются к allowed_domains и blocked_domains. Запрос, нарушающий одно из них, отклоняется, как описано в разделе Ошибки валидации.

• Один список на запись: задайте в записи либо allowed_domains, либо blocked_domains, но не оба.
• Размер списка: каждый список содержит от 1 до 64 доменов, каждый длиной от 1 до 255 символов.
• Без пустых списков: чтобы не применять ограничений, опустите поле или передайте null.
• Без дубликатов: домен может встречаться в списке только один раз. www.example.com и example.com считаются разными доменами.

Чему соответствует указанный домен

Указанный домен соответствует этому хосту и всем его поддоменам. example.com охватывает docs.example.com, но docs.example.com не охватывает ни example.com, ни api.example.com.

Начальный www. — такой же поддомен, как и любой другой, поэтому www.example.com не охватывает example.com. Чтобы охватить оба варианта, укажите домен без префикса www.

Имена хостов сравниваются без учёта регистра.

Формат домена

Каждый домен — это регистрируемое доменное имя или его поддомен, записанный как простое имя хоста. Он может содержать буквы ASCII, цифры, дефисы, подчёркивания и точки. Один завершающий / игнорируется.

Домен также отклоняется, если он содержит учётные данные или пробельные символы либо если одна из его меток начинается или заканчивается дефисом. localhost и хосты, оканчивающиеся на .localhost, .local, .internal, .localdomain или .invalid, также отклоняются.

Суффиксы пути в доменах для веб-поиска

Домен для web_search может содержать суффикс пути, например example.com/blog. Путь не может содержать пробелы, ?, # или любой из символов $ , | ^ !.

Для web_search также предпочтительнее использовать простые имена хостов. Поисковый провайдер сопоставляет суффиксы пути как шаблоны URL, а не как строгие правила для хостов.

Ошибки валидации

API проверяет эти настройки, когда вы создаёте агента или обновляете агента. Он также проверяет их, когда вы создаёте или обновляете сессию, в которой передаётся tools.

Нарушения формата и ограничений отклоняются с ошибкой 400 invalid_request_error:

В тех же запросах API также отклоняет три настройки, зависящие от провайдеров поиска и загрузки:

• Домен в allowed_domains, к которому поисковому роботу Anthropic запрещён доступ.
• Значение user_location.country, которое не поддерживает поисковый провайдер. Сообщение заканчивается на user_location.country: not a country the search provider supports.
• Значение user_location.timezone, которое не является допустимым именем IANA.

В облачной среде в сетевом режиме limited при создании и обновлении сессии также проверяется соответствие allowed_domains списку allowed_hosts среды. См. правило в разделе Задание списков доменов для агента.

Когда принятая настройка перестаёт быть допустимой

Сессия повторно проверяет конфигурацию при первой инициализации инструмента. Если ранее принятая настройка к этому моменту перестала быть допустимой, сессия отправляет событие session.error. Затем она возвращается в состояние idle без повторных попыток.

Чтобы продолжить сессию:

1. Исправьте настройку, обновив инструменты сессии.
2. Также обновите агента, чтобы новые сессии запускались с исправленной конфигурацией.
3. Отправьте новое сообщение user.message.

Мультиагентные сессии и сессии, ориентированные на результат

В мультиагентной сессии все списки доменов, применимые к потоку, действуют одновременно. Агент из «roster» (состава) координатора ограничен тремя наборами списков:

• Собственными allowed_domains и blocked_domains
• Списками любого агента, который его вызвал
• Текущими списками координатора

Настройки объединяются следующим образом:

Таким образом, агент из состава может сузить круг доступных инструменту ресурсов, но никогда не может его расширить:

• Агент из состава, задающий blocked_domains, сохраняет allowed_domains координатора и блокирует указанные хосты в его пределах.
• Агент из состава, задающий собственные allowed_domains, может обращаться только к хостам, которые охвачены и его списком, и списком координатора.

Запись состава {"type": "self"} не имеет собственных веб-настроек и следует текущим настройкам координатора.

Если объединённые списки allowed_domains не имеют общих доменов, инструмент остаётся доступным этому агенту, но каждый вызов завершается ошибкой. Каждый вызов возвращает ошибку url_not_allowed, сообщающую, что ни один домен не разрешён. Описание инструмента сообщает модели то же самое. Чтобы избежать этого, держите allowed_domains каждого агента из состава в пределах списка координатора.

Оценщик в сессиях, ориентированных на результат, работает без web_search и web_fetch независимо от этих настроек.

Изменение списков во время сессии

Вы можете изменить списки в сессии в состоянии ожидания, обновив её инструменты. Новые списки действуют до конца сессии.

В мультиагентной сессии каждый поток применяет новые списки со своего следующего хода. Обновление не изменяет собственные списки агента из состава. Они остаются такими, какими их задало определение агента при создании сессии.

Отличия от инструментов Messages API

Эти настройки используют те же поля allowed_domains и blocked_domains, что и фильтрация доменов в серверных инструментах Messages API. Managed Agents отличается в четырёх аспектах:

• Каждый список ограничен 64 доменами.
• Домены, указанные для web_fetch, не могут содержать путь.
• Домены должны быть в ASCII. Messages API принимает записи в Unicode, хотя и не рекомендует их использовать.
• max_uses, citations и cache_control недоступны в наборе инструментов.

Следующие шаги