Как настроить tool use в Claude API и безопасно выполнять функции

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

Когда этот подход подходит

Материал рассчитан на серверную интеграцию с Claude API. Перед внедрением проверьте, что нужная функция и модель доступны вашему аккаунту. Интерфейс Console и лимиты могут меняться, поэтому названия полей сверяйте с официальной документацией на дату разработки.

Пошаговая настройка

1. Опишите каждый инструмент: понятное имя, конкретное назначение и JSON Schema входных параметров. Один инструмент должен выполнять одну ясную операцию.
2. Отправьте описание tools вместе с сообщением. В ответе найдите блок tool_use и сохраните его id.
3. До выполнения проверьте типы, диапазоны, права пользователя и принадлежность объекта. Для необратимых действий добавьте подтверждение.
4. Выполните разрешённую функцию своим кодом и отправьте результат назад как tool_result, связав его с tool_use_id.
5. Получите финальный ответ и отдельно запишите технический журнал решения.

Ограничения и применимость

Claude не подтверждает фактическое выполнение операции: это делает ваш backend. Схема ограничивает форму аргументов, но не заменяет авторизацию. Внешний сервис может быть недоступен, поэтому tool_result должен уметь передавать ошибку.

Как проверить результат

Испытайте нормальный вызов, неизвестный идентификатор, чужой объект, слишком большое число и повтор одного tool_use_id. Система должна отклонять запрещённые действия и не выполнять одну операцию дважды.

Чего не делать

• Не выполняйте команду shell, составленную моделью, без allowlist.
• Не доверяйте идентификаторам и суммам только потому, что они прошли схему.
• Не скрывайте от модели ошибку инструмента выдуманным успехом.

Практический вывод

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

Официальная документация: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview