Инструменты
Настройте инструменты, доступные вашему агенту.
Claude Managed Agents предоставляет набор встроенных инструментов, которые Claude может использовать автономно в рамках сессии. Вы управляете тем, какие инструменты доступны, указывая их в конфигурации агента.
Claude Managed Agents также поддерживает пользовательские инструменты, определяемые пользователем. Ваше приложение выполняет эти инструменты отдельно и возвращает результаты Claude, который использует их для продолжения задачи. Чтобы предоставить агенту инструменты с сервера MCP, используйте вместо этого коннектор MCP.
Доступные инструменты
Набор инструментов агента включает следующие инструменты. Все они включены по умолчанию, когда вы добавляете набор инструментов в конфигурацию агента.
| Инструмент | Имя | Описание |
|---|---|---|
| Bash | bash | Выполнение команд bash в сеансе оболочки |
| Read | read | Чтение файла из файловой системы песочницы |
| Write | write | Запись файла в файловую систему песочницы |
| Edit | edit | Замена строк в файле |
| Glob | glob | Быстрый поиск файлов по шаблонам glob |
| Grep | grep | Поиск текста с помощью шаблонов регулярных выражений |
| Веб-загрузка | web_fetch | Загрузка содержимого по URL |
| Веб-поиск | web_search | Поиск информации в интернете |
Когда вывод инструмента превышает 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 типизирует каждую запись configs по инструменту. Тип представляет собой объединение с одним членом для каждого встроенного инструмента, различаемым по 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: 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 извлечение важного.
Следующие шаги
Управляйте тем, к каким сайтам могут обращаться веб-инструменты, ограничивайте объём загружаемого содержимого и локализуйте результаты поиска.
Подключайте серверы MCP к своим агентам для доступа к внешним инструментам и источникам данных.
Управляйте тем, когда выполняются инструменты агента и MCP.
Отправляйте события, получайте ответы в режиме потоковой передачи, а также прерывайте или перенаправляйте сеанс во время его выполнения.
Доступность
Claude API
- Статус
- Бета
- API
- Managed Agents
- Бета-заголовок
- Требуется
- Модели
- Все модели
Claude Platform on AWS
- Статус
- Бета
- API
- Managed Agents
- Бета-заголовок
- Требуется
- Модели
- Все модели
Обработка данных
Обзор обработки данныхПрименимые конечные точки
/v1/agents/v1/sessions/v1/environments
Не подпадает под ZDR, за исключением самостоятельно размещаемых Managed Agents. Сессии — это ресурсы с состоянием; их расшифровки хранятся, пока вы их не удалите. Подробнее
Не подпадает под HIPAA. Относится ко всем подфункциям Managed Agents.
Эта страница была полезной?