Инструменты

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, чтобы продолжить.

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

В мультиагентной сессии все списки доменов, применимые к потоку, применяются одновременно: агент в составе (roster) координатора связан своими собственными 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, не могут включать путь.
• Домены должны быть в ASCII: используйте форму xn-- (Punycode) для интернационализированных доменных имён. Messages API принимает записи в Unicode, хотя и не рекомендует их.
• 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 извлечение того, что важно.

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