Инструменты

Claude Managed Agents предоставляет набор встроенных инструментов, которые Claude может использовать автономно в рамках сессии. Вы контролируете, какие инструменты доступны, указывая их в конфигурации агента.

Claude Managed Agents также поддерживает пользовательские инструменты, определяемые пользователем. Ваше приложение выполняет эти инструменты отдельно и возвращает результаты Claude, который использует их для продолжения задачи. Чтобы предоставить агенту инструменты с сервера MCP, используйте вместо этого коннектор MCP.



Доступные инструменты

Набор инструментов агента включает следующие инструменты. Все они включены по умолчанию, когда вы добавляете набор инструментов в конфигурацию агента. Каждая запись в массиве configs идентифицируется по своему полю name с использованием значений из столбца «Имя» и принимает необязательное поле type с тем же значением. Записи web_search и web_fetch принимают дополнительные настройки; см. Ограничение доменов для веб-поиска и веб-загрузки.

Когда вывод инструмента превышает 100 000 символов (около 25 000 токенов), он автоматически записывается в файл в песочнице. Модель получает усечённый предварительный просмотр с путём к файлу и может прочитать полное содержимое оттуда.



Настройка набора инструментов

Включите полный набор инструментов с помощью agent_toolset_20260401 при создании агента. Используйте массив configs, чтобы отключить определённые инструменты или переопределить их настройки. Каждая запись конфигурации также может задавать permission_policy, который определяет, одобряются ли вызовы инструмента автоматически или требуют подтверждения. См. Политики разрешений для доступных типов политик.

Записи конфигурации для web_search и web_fetch также принимают фильтры доменов и другие веб-настройки; см. Ограничение доменов для веб-поиска и веб-загрузки.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML



Отключение определённых инструментов

Чтобы отключить инструмент, установите enabled: false в его записи конфигурации в объекте набора инструментов массива tools вашего агента:

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}



Включение только определённых инструментов

Объект default_config задаёт базовую конфигурацию для каждого инструмента в наборе, а записи configs для отдельных инструментов переопределяют её. Чтобы начать с отключённого состояния и включить только то, что вам нужно, установите default_config.enabled в false:

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}



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

Чтобы контролировать, к каким сайтам могут обращаться веб-инструменты агента, задайте allowed_domains (инструмент может обращаться только к этим хостам) или blocked_domains (инструмент никогда не может обращаться к этим хостам) в записях web_search и web_fetch массива configs набора инструментов. Каждый инструмент имеет собственный список, поэтому web_search и web_fetch могут иметь разные ограничения. Указанный домен охватывает этот хост и все его поддомены. Во время выполнения вызов web_fetch для URL, который не разрешён его списками, возвращает агенту результат с ошибкой (is_error: true в событии agent.tool_result, с содержимым, указывающим код ошибки url_not_allowed), а web_search исключает результаты, которые не разрешены его списками.

Следующий набор инструментов ограничивает web_search двумя сайтами и локализует его результаты, а также блокирует один хост для web_fetch, ограничивая при этом объём загруженного содержимого, попадающего в контекст:

{
  "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
    }
  ]
}

Следующий запрос создаёт агента с этим набором инструментов и выводит массив configs из ответа:

ant beta:agents create --transform tools.0.configs <<'YAML'
name: Research Agent
model: claude-opus-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
YAML

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

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



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

• Задавайте в записи либо allowed_domains, либо blocked_domains, но не оба. Запись, задающая оба, отклоняется.
• Каждый список содержит от 1 до 64 доменов, каждый длиной от 1 до 255 символов. Пустой список отклоняется: чтобы не применять ограничений, опустите поле или отправьте null.
• Каждый домен — это регистрируемое доменное имя или его поддомен, записанный как простое имя хоста: ASCII-буквы, цифры, дефисы, подчёркивания и точки, без схемы, порта, учётных данных, подстановочных знаков или пробелов, без меток, начинающихся или заканчивающихся дефисом, и без пути, кроме необязательного суффикса пути для web_search, описанного далее в этом списке. Используйте example.com, а не https://example.com, example.com:443 или *.example.com. Имена хостов сравниваются без учёта регистра, а одиночный завершающий / игнорируется.
• Указанный домен соответствует этому хосту и его поддоменам: example.com охватывает docs.example.com, но docs.example.com не охватывает example.com или api.example.com. Начальный www. — это такой же поддомен, как и любой другой, поэтому www.example.com не охватывает example.com; укажите домен без префикса, чтобы охватить оба.
• IP-адреса не принимаются ни в какой форме, будь то IPv4, IPv6, в квадратных скобках или в числовой сокращённой записи, такой как 127.1. Вместо этого укажите доменное имя сайта.
• Домен верхнего уровня или суффикс реестра без остальной части, такой как com, co.uk или gov.uk, отклоняется, как и имя из одной метки, такое как intranet. Укажите полный домен, например example.co.uk.
• localhost и хосты, оканчивающиеся на .localhost, .local, .internal, .localdomain или .invalid, отклоняются.
• Используйте форму xn-- (Punycode) для интернационализированных доменных имён; домен, содержащий символы, отличные от ASCII, отклоняется.
• Домен для web_fetch не может включать путь: используйте example.com, а не example.com/*. Домен для web_search может содержать суффикс пути, например example.com/blog, в котором путь не может содержать пробелы, ?, # или любой из символов $ , | ^ !. Предпочитайте простые имена хостов и для web_search, поскольку поставщик поиска сопоставляет суффиксы путей как шаблоны URL, а не как строгие правила хостов.
• Дублирующиеся домены в списке отклоняются. www.example.com и example.com считаются разными доменами; см. приведённое выше правило сопоставления, чтобы понять, что охватывает каждый из них.



Когда проверяются настройки

Нарушения формата и ограничений отклоняются с ошибкой 400 invalid_request_error при создании агента или обновлении агента, а также при создании или обновлении сессии, которая передаёт tools. Например, сообщение для записи, задающей оба списка, включает Only one of allowed_domains or blocked_domains may be set., а сообщение для пустого списка включает allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null. Сообщение для домена, нарушающего правило формата, указывает его список и позицию (с нуля), например allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com".

Те же запросы также отклоняют три настройки, зависящие от поставщиков поиска и загрузки: домен в allowed_domains, к которому краулеру Anthropic не разрешён доступ, user_location.country, который не поддерживается поставщиком поиска (сообщение заканчивается на user_location.country: not a country the search provider supports), и user_location.timezone, который не является допустимым именем IANA. Сессия повторно проверяет конфигурацию при первой инициализации инструмента; если настройка, принятая ранее, на этот момент больше не действительна, сессия генерирует событие session.error и возвращается в состояние idle без повторных попыток. Исправьте настройку, обновив инструменты сессии, обновите также агента, чтобы новые сессии начинались с исправленной конфигурацией, затем отправьте новое user.message, чтобы продолжить.



Мультиагентные сессии, результаты и обновления в ходе сессии

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

• Списки разрешённых доменов объединяются до доменов, которые охватываются всеми ими, а списки заблокированных доменов складываются, поэтому агент из состава может сузить то, к чему обращается инструмент, но никогда не расширить. Например, агент из состава, задающий blocked_domains, сохраняет allowed_domains координатора и блокирует эти хосты внутри него, а агент из состава, задающий собственные allowed_domains, может обращаться только к хостам, которые охватываются и его списком, и списком координатора.
• Если объединённые списки разрешённых доменов не имеют общих доменов, инструмент остаётся доступным этому агенту, но каждый вызов завершается ошибкой url_not_allowed, указывающей, что ни один домен не разрешён, и описание инструмента сообщает об этом модели. Чтобы избежать этого, держите список разрешённых доменов каждого агента из состава внутри списка координатора.
• max_content_tokens и user_location не объединяются: поток использует значение из собственной конфигурации инструмента, если оно задано, иначе — из агента, который его вызвал, иначе — из текущей конфигурации координатора.
• Запись состава {"type": "self"} не имеет собственных веб-настроек и следует текущим настройкам координатора.
• Оценщик в сессиях, ориентированных на результат, работает без web_search и web_fetch, независимо от этих настроек.
• Вы можете изменить списки в простаивающей сессии, обновив её инструменты. Новые списки применяются к оставшейся части сессии; в мультиагентной сессии каждый поток применяет их со своего следующего хода, тогда как собственные списки агента из состава остаются такими, какими их задало определение агента при создании сессии.



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

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

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



Пользовательские инструменты

Помимо встроенных инструментов, вы можете определять пользовательские инструменты. Пользовательские инструменты аналогичны определяемым пользователем клиентским инструментам в Messages API.

Каждый пользовательский инструмент определяет контракт: вы указываете, какие операции доступны и что они возвращают, а Claude определяет, когда и как их вызывать. Модель никогда ничего не выполняет самостоятельно. Она выдаёт структурированный запрос, ваш код выполняет операцию, и результат возвращается в разговор. См. Поток событий сессии, чтобы узнать, как получать вызовы пользовательских инструментов и возвращать результаты во время сессии.

Если ваши сессии выполняются в самостоятельно размещённой песочнице, рабочий процесс среды может обслуживать пользовательские инструменты из вашей песочницы, включая инструменты, оборачивающие сервер MCP внутри вашей сети.

ant beta:agents create < agent.yaml

name: Weather Agent
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
  - type: custom
    name: get_weather
    description: Get current weather for a location
    input_schema:
      type: object
      properties:
        location:
          type: string
          description: City name
      required:
        - location

После того как вы определили пользовательские инструменты для агента, агент вызывает их во время сессии.



Рекомендации по определению пользовательских инструментов

• Предоставляйте максимально подробные описания. Это, безусловно, самый важный фактор производительности инструмента. Ваши описания должны объяснять, что делает инструмент и когда его использовать (а когда нет). Объясните, что означает каждый параметр и как он влияет на поведение инструмента. Укажите любые важные оговорки или ограничения. Чем больше контекста вы можете дать Claude о ваших инструментах, тем лучше он определяет, когда и как их использовать. Стремитесь к трём-четырём предложениям для каждого описания инструмента, больше — если инструмент сложный.
• Объединяйте связанные операции в меньшее количество инструментов. Вместо создания отдельного инструмента для каждого действия (create_pr, review_pr, merge_pr) сгруппируйте их в один инструмент с параметром action. Меньшее количество более функциональных инструментов снижает неоднозначность выбора и облегчает Claude навигацию по вашему набору инструментов.
• Используйте осмысленные пространства имён в именах инструментов. Когда ваши инструменты охватывают несколько сервисов или ресурсов, добавляйте к именам префикс ресурса (например, db_query или storage_read). Это делает выбор инструмента однозначным по мере роста вашей библиотеки.
• Проектируйте ответы инструментов так, чтобы они возвращали только значимую информацию. Возвращайте семантические, стабильные идентификаторы (например, слаги или UUID), а не непрозрачные внутренние ссылки, и включайте только те поля, которые нужны Claude для определения следующего шага. Раздутые ответы расходуют контекст и затрудняют Claude извлечение того, что важно.



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