Tool schema — это контракт между моделью и приложением. Она объясняет модели, какой инструмент существует, зачем он нужен и какие аргументы нужно передать, чтобы backend мог выполнить действие безопасно и предсказуемо.
Обычно tool schema включает название функции, короткое описание, список параметров, типы данных, обязательные поля, допустимые значения, формат дат, ограничения длины и запрет на лишние поля. Чем яснее schema, тем меньше модель угадывает и тем проще валидировать вызов.
Важно понимать: schema помогает модели сформировать структурированный tool call, но не заменяет backend-проверку. Приложение всё равно должно проверить права доступа, диапазоны значений, id объектов, allowlist действий, rate limits и отсутствие секретов.
Плохая tool schema часто ломает агента. Если описание слишком общее, поля названы неоднозначно, обязательные параметры не указаны или tool принимает “любой текст”, модель будет вызывать инструмент не вовремя, передавать неполные аргументы или пытаться сделать опасное действие.
Примеры
- Инструмент create_crm_task принимает title, due_date, assignee_id и deal_id. В schema указано, что due_date должен быть в формате YYYY-MM-DD, а deal_id обязателен.
- Для send_email schema разрешает создать только черновик письма, а поле send_now отсутствует, чтобы агент не отправлял письма без approval.
- Инструмент search_knowledge_base принимает query, product и max_results. Если product не передан, backend возвращает ошибку валидации.
- В schema для refund_order поле amount ограничено положительным числом, а само действие разрешено только после проверки прав и human approval.
- Если schema описывает поле как “data”, модель будет угадывать формат. Лучше явно задать поля: customer_id, period_start, period_end и report_type.
Где используется
- Подключить API, CRM, базу знаний или webhook к AI-агенту.
- Сделать tool calling предсказуемым и проверяемым.
- Ограничить модель только разрешенными аргументами и действиями.
- Получать валидный JSON вместо произвольного текста.
- Разделить безопасные действия, черновики и действия с human approval.
- Писать тесты на tool calls и регрессию агентного поведения.
- Документировать контракт между LLM, orchestration layer и backend.
Связанные термины
Частые вопросы
Что такое tool schema простыми словами?
Это описание инструмента для модели: как он называется, что делает и какие данные нужно передать. По этой схеме модель формирует вызов функции или API.
Tool schema и JSON Schema — это одно и то же?
Не совсем. Tool schema часто использует JSON Schema-подобное описание параметров, но включает ещё название инструмента, назначение и правила использования в агенте.
Зачем нужна backend-валидация, если schema уже задана?
Модель может ошибиться или пользователь может попытаться обойти правила. Backend должен независимо проверить типы, права, id объектов, лимиты и безопасность действия.
Что делает tool schema хорошей?
Короткое назначение, понятные имена полей, строгие типы, обязательные параметры, enum вместо свободного текста, ограничения длины и запрет лишних полей.
Какие данные нельзя класть в tool schema?
Нельзя помещать API-ключи, пароли, внутренние секреты и приватные правила доступа. Schema должна описывать контракт, а не раскрывать чувствительные данные.
