Инструменты

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

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

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

Набор инструментов агента включает следующие инструменты. Все они включены по умолчанию, когда вы добавляете набор инструментов в конфигурацию агента.

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

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

Включите полный набор инструментов с помощью agent_toolset_20260401 при создании агента. Используйте массив configs, чтобы отключить определённые инструменты или переопределить их настройки. Каждая запись идентифицируется своим name, который принимает значение из столбца «Имя» в разделе Доступные инструменты. Запись также принимает необязательное поле type с тем же значением.

Каждая запись конфигурации также может задавать permission_policy. Политика определяет, выполняются ли вызовы инструмента без подтверждения, требуют подтверждения или оцениваются сервером индивидуально. Доступные типы политик см. в разделе Политики разрешений.

В следующем примере включается набор инструментов и отключается 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 в его записи configs:

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

Ограничение веб-поиска и веб-загрузки

Записи web_search и web_fetch также принимают списки доменов, ограничение на объём загружаемого содержимого и местоположение для поиска. См. Ограничение доменов для веб-поиска и веб-загрузки.

Типы записей конфигурации в SDK

В SDK для Python, TypeScript, Go, Java, C#, Ruby и PHP каждая запись configs типизирована для конкретного инструмента. Тип представляет собой «union» (объединение) с одним членом для каждого встроенного инструмента, различаемое по type.

В Go, Java, C# и PHP вы создаёте записи из типизированных значений, а не из простых словарей или хэшей. В этих SDK типом элемента configs является само объединение, поэтому создавайте каждую запись из типа члена, соответствующего инструменту.

Вы можете опустить type при создании записи, поскольку сервер выводит его из name. Ответы всегда включают его. Эта типизация не меняет JSON, в который сериализуется запись. Запрос, записи которого задают только name, enabled и permission_policy, действителен как с type, так и без него.

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

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

Claude не запускает пользовательский инструмент самостоятельно. Он формирует структурированный запрос, ваш код выполняет операцию, и вы возвращаете результат в сессию.

В следующем примере создаётся агент со встроенным набором инструментов и одним пользовательским инструментом get_weather:

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

Имя пользовательского инструмента не может начинаться с mcp__ или ant__ или совпадать с именем встроенного инструмента агента. Запрос, нарушающий это правило, возвращает ошибку 400. Агент, у которого уже есть пользовательский инструмент с именем, начинающимся с ant__, принимает обновление только в том случае, если обновление отправляет tools без этого имени, поэтому переименуйте или удалите инструмент в следующем обновлении. Новая сессия отклоняется с ошибкой 400, если такой инструмент есть у её агента (после применения любых переопределений), у агента в списке predefined_agents в subagents или у агента в списке predefined_agents в workflows. Уже существующие сессии это не затрагивает.

Агент вызывает свои пользовательские инструменты во время сессии. О том, как получать вызовы и возвращать результаты, см. Поток событий сессии.

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

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

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

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