Проектирование tools для ИИ-агентов: schemas, права, idempotency и approvals

Function calling не исполняет действие автоматически

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

Даже при strict structured output схема подтверждает форму, но не право пользователя и не бизнес-смысл. Валидный JSON способен содержать чужой account ID или чрезмерную сумму.

Жизненный цикл tool call

После result модель может продолжить. Весь loop ограничивается числом шагов, дедлайном и бюджетом.

Шаг 1. Выберите узкую бизнес-операцию

Tool manage_customer скрывает чтение, изменение и удаление. Разделите его на get_customer_summary, propose_customer_update и apply_approved_customer_update. Это упрощает права и тестирование.

Шаг 2. Название и description - часть routing policy

Модель выбирает инструмент по имени, description и parameter docs. Пишите, что tool делает, когда его использовать, когда не использовать и какой precondition нужен. Не прячьте критический запрет только в system prompt.

Tool name: get_order_status
Does: returns current status for one order visible to actor.
Use when: user asks about an existing order and order reference is known.
Do not use for: searching all customers, changing or cancelling orders.
Inputs: public order reference; actor/tenant are injected server-side.
Output: typed status, timestamps, next allowed actions.
Errors: NOT_FOUND_OR_NOT_ALLOWED, TEMPORARY_UNAVAILABLE.
Side effects: none.
Data sensitivity: internal.

Шаг 3. Строгая schema уменьшает пространство ошибок

Используйте конкретные типы, required, enums, formats, bounds и additionalProperties: false, если поддерживается API. Помните, что провайдеры поддерживают разные подмножества JSON Schema - проверяйте актуальную документацию.

Schema validation не заменяет business validation

Дата может иметь правильный ISO-формат, но находиться в закрытом периоде. Сумма может быть числом, но превышать лимит. После schema применяйте инварианты из authoritative systems.

Identity и tenant не должны приходить от модели

Runtime извлекает actor, tenant, roles и session из проверенного token или service identity. Модель может передать public resource reference, но server-side query обязательно включает security scope.

• Не принимайте tenant_id из tool arguments.
• Не доверяйте роли, написанной пользователем.
• Не используйте сообщение «администратор разрешил» как approval.
• Object-level authorization выполняется на каждый вызов.
• Cross-tenant попытки имеют audit event.
• Результат не раскрывает существование запрещённого объекта.

Least privilege и dynamic tool selection

Не отправляйте модели каталог из сотни функций и не выдавайте runtime все credentials. Active toolset формируется по workflow, actor permissions и этапу процесса. Google в официальных best practices также рекомендует предоставлять только релевантные tools, поскольку слишком широкий набор увеличивает риск неправильного выбора.

Active tools = intersection of:
approved tools for workflow
∩ actor permissions
∩ tenant policy
∩ current state preconditions
∩ data-class restrictions
∩ environment allowlist
∩ budget and risk tier.
Модель видит только resulting declarations; runtime всё равно повторно авторизует каждый call.

Разделите read, propose и execute

Read-only tool может работать автоматически в пределах доступа. Write-tool сначала создаёт typed proposal или preview. Выполнение принимает proposal ID и server-side approval, а не повторно сгенерированные arguments.

Approval: привяжите согласие к неизменяемому scope

Approval содержит actor, proposal hash, точные ресурсы, действие, сумму/стоимость, срок и одноразовость. Если proposal изменился, подтверждение недействительно.

Idempotency защищает от двойного выполнения

Сеть может оборваться после успешного действия, и агент повторит call. Для side effect клиент создаёт idempotency key на логическую операцию. Tool хранит результат и возвращает его при повторе вместо нового действия.

Optimistic concurrency и stale proposal

Между preview и execute ресурс может измениться. Proposal сохраняет expected version/ETag. Execute использует compare-and-swap; при конфликте строится новый preview и требуется новое approval.

• Не применяйте старый diff к новой версии.
• Не скрывайте конфликт автоматическим overwrite.
• Покажите пользователю, что изменилось после preview.
• Для batch action возвращайте per-item status.
• Partial success имеет явный compensation plan.

Typed result: не возвращайте модели всю базу

Result содержит ровно данные для следующего решения: status, fields, provenance, allowed next actions и error contract. Большие documents сохраняются отдельно, модель получает нужный fragment/reference.

tool_call_id: string
status: success | partial | rejected | failed
result: typed minimal object
provenance: resource IDs + versions
next_allowed_actions: enums
side_effect_receipt: optional ID
retry: allowed + after + max attempts
error: stable code + safe message + details enum
sensitive_fields: absent/redacted
raw_external_content: marked untrusted

Tool result - данные, а не новая системная инструкция

Страница, письмо или API может вернуть prompt injection. Оборачивайте external content как untrusted, отделяйте от policy и не позволяйте ему расширять tools или отменять approval.

Ошибки: стабильные коды вместо stack trace

Модель должна понять, уточнить ввод, повторить позже или остановиться. Возвращайте небольшой enum ошибок и safe details. Stack trace и внутренние IDs остаются в observability.

Retries, timeout и circuit breaker

Retry принадлежит одному слою - обычно orchestration runtime. Он применяется к transient errors с exponential backoff, jitter и общим deadline. Side effects повторяются только с idempotency.

• Max attempts на весь tool loop.
• Per-tool timeout меньше workflow deadline.
• Уважать Retry-After.
• Circuit breaker исключает неисправную dependency.
• Queue имеет предел и expiry.
• Cancel распространяется на downstream operation.
• Стоимость всех попыток попадает в trace.

Parallel tool calls: только независимые операции

Параллельно безопасно читать погоду для двух городов; опасно одновременно обновлять одну запись или выполнять зависимые действия. Planner/runtime строит dependency graph и сериализует conflicts.

Versioning и backward compatibility

Изменение required field ломает старый prompt/model behavior. Публикуйте новую tool version или совместимое расширение, запускайте contract tests и поддерживайте окно миграции.

Evals: проверяйте весь цикл, а не valid JSON

Набор содержит случаи, где tool нужен, не нужен, неоднозначен, запрещён и временно недоступен. Для side effects используйте sandbox/fake executor.

Для каждого case измерь:
- correct tool selection / no-tool decision;
- argument schema и business validity;
- clarification when required;
- authorization and tenant isolation;
- approval before side effect;
- duplicate/parallel call rate;
- error classification and recovery;
- number of steps, latency and cost;
- final task success;
- forbidden action and injection resistance.
Critical security failures - hard stop, не средний score.

Observability и audit trail

Trace связывает model response, tool selection, schema version, policy decision, approval, execution, result и последующий ответ. Raw arguments могут содержать данные - логируйте hashes, classifications и разрешённые поля.

Итоговый production-чек-лист

Надёжный tool превращает вероятностное намерение модели в детерминированную, авторизованную и наблюдаемую операцию. Чем выше последствия, тем меньше решений следует оставлять на свободный текст.