Инструменты

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

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

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

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

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

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

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

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

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
---

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

Чтобы отключить инструмент, задайте 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 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
---

В 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. Чтобы охватить оба варианта, укажите домен без www..

• 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 без повторных попыток. Чтобы продолжить:

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

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

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

• собственными allowed_domains и blocked_domains;
• списками всех агентов, которые его вызвали;
• текущими списками координатора.

Как сочетаются эти списки:

• «Allowlists» (списки разрешённых доменов) сводятся к доменам, которые охвачены всеми ими одновременно, а «blocklists» (списки заблокированных доменов) суммируются. Поэтому агент из состава может сузить круг доступных инструменту ресурсов, но не расширить его. Например, агент из состава, задавший blocked_domains, сохраняет allowed_domains координатора и блокирует указанные хосты внутри этого списка. Агент из состава, задавший собственный allowed_domains, может обращаться только к хостам, которые охвачены и его списком, и списком координатора.
• Если у объединённых списков разрешённых доменов нет ни одного общего домена, инструмент остаётся доступным агенту, но каждый вызов завершается ошибкой url_not_allowed с сообщением о том, что ни один домен не разрешён. Описание инструмента также сообщает об этом модели. Чтобы этого избежать, следите, чтобы список разрешённых доменов каждого агента из состава не выходил за пределы списка координатора.
• max_content_tokens и user_location не объединяются. Поток использует значение из собственной конфигурации инструмента, если оно задано. Если нет — значение агента, который его вызвал, а если нет и его — значение из текущей конфигурации координатора.
• У записи состава {"type": "self"} нет собственных веб-настроек, и она следует текущим настройкам координатора.
• «Grader» (оценщик) в сессиях, ориентированных на результат, работает без 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 определяет, когда и как их вызывать. Модель никогда ничего не выполняет самостоятельно. Она формирует структурированный запрос, ваш код выполняет операцию, и результат возвращается в диалог. О том, как получать вызовы пользовательских инструментов и возвращать результаты во время сессии, см. в разделе Поток событий сессии.

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

ant apply agent.md

---
name: Weather Agent
model: claude-opus-5-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). Так выбор инструмента остаётся однозначным по мере роста библиотеки.
• Возвращайте в ответах инструментов только действительно значимую информацию. Возвращайте семантические, стабильные идентификаторы (например, slug или UUID), а не непрозрачные внутренние ссылки. Включайте только те поля, которые нужны Claude для выбора следующего шага. Раздутые ответы расходуют контекст и мешают Claude выделить главное.

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