Проектирование tool-use интерфейсов: как создавать эффективные инструменты для агентов

Принципы именования и документации

LLM принимает решение о вызове инструмента на основе его описания. Именование и документация — это API для модели, и к ним нужно относиться с тем же вниманием, что и к API для людей.

Правила именования инструментов:

• Используйте глагол + существительное: get_user_orders, search_products, create_ticket
• Избегайте технических аббревиатур без расшифровки: fetch_crm_opp хуже, чем get_crm_opportunity
• Будьте специфичны: calculate_revenue_by_period лучше, чем calculate_revenue

Документация инструмента должна содержать: что делает инструмент (одна чёткая фраза), когда его следует использовать (и когда не следует), описание каждого параметра с типом и допустимыми значениями, возможные ошибки и их значение.

Пример хорошей документации:

"""search_knowledge_base(query: str, top_k: int = 5) -> list[dict]
Ищет релевантные документы в базе знаний компании по семантическому сходству.
Используй, когда нужно найти информацию о политиках, процедурах или продуктах.
НЕ используй для поиска данных о конкретных клиентах или транзакциях.
query: поисковый запрос на естественном языке
top_k: количество возвращаемых документов (1-20, по умолчанию 5)
Возвращает: список словарей с полями 'content', 'source', 'relevance_score'
"""

Типизация и валидация входных данных

Строгая типизация входных параметров инструментов — обязательное требование для production-систем. Используйте Pydantic-модели или JSON Schema для валидации перед выполнением инструмента.

Преимущества строгой типизации:

1. LLM получает точную схему ожидаемых параметров из JSON Schema, что снижает ошибки вызова
2. Некорректные вызовы перехватываются до выполнения бизнес-логики
3. Автоматически генерируется документация для промпта

Пример с Pydantic:

from pydantic import BaseModel, Field, validator

from typing import Literal

class QueryOrdersInput(BaseModel):

    start_date: str = Field(..., description="Начальная дата в формате YYYY-MM-DD")

    end_date: str = Field(..., description="Конечная дата в формате YYYY-MM-DD")

    status: Literal["pending", "completed", "cancelled"] | None = None

    limit: int = Field(default=100, ge=1, le=1000)

Автоматическая генерация JSON Schema из Pydantic-модели напрямую используется OpenAI и Anthropic API для определения параметров инструмента — не нужно дублировать схему вручную.

Обработка ошибок и возвращаемые значения

Инструмент должен всегда возвращать структурированный результат, даже при ошибке. Агент, получивший необработанное исключение Python, не знает, как продолжить задачу.

Рекомендуемый паттерн возвращаемого значения:

{

  "success": true/false,

  "data": {...},  // при успехе

  "error": {  // при ошибке

    "code": "NOT_FOUND",

    "message": "Заказ с ID 12345 не найден",

    "suggestion": "Проверьте правильность ID или используйте search_orders для поиска по параметрам"

  }

}

Поле suggestion в объекте ошибки — недооценённый механизм: оно подсказывает агенту, какое действие предпринять дальше, и снижает количество итераций на восстановление после ошибки.

Различайте типы ошибок: recoverable (неверные параметры, объект не найден — агент должен скорректировать запрос) и non-recoverable (нет доступа, внешний сервис недоступен — агент должен сообщить пользователю).

Принцип единственной ответственности

Каждый инструмент должен делать ровно одно дело. Агрегированные инструменты вида get_customer_profile_with_orders_and_tickets трудно документировать, а модель использует их непредсказуемо.

Признаки того, что инструмент нужно разбить:

• Более трёх обязательных параметров
• Описание содержит слова «и», «или», «также»
• Разные вызывающие сценарии используют разные подмножества параметров

Признаки того, что инструменты нужно объединить:

• Один инструмент почти всегда вызывается сразу после другого
• Оба инструмента обращаются к одному источнику данных

Оптимальное количество инструментов для агента: 5–15. При меньшем количестве агент не может эффективно выполнять задачи; при большем количестве модель начинает путаться в выборе.

Идемпотентность и побочные эффекты

Разделите инструменты на read-only и write операции и явно обозначьте это в документации. Агент должен знать, что вызов create_order имеет необратимые последствия, а get_order — нет.

Для write-операций рекомендуется паттерн preview + confirm: сначала инструмент-предварительный просмотр (preview_create_order), который возвращает, что будет создано, и только потом инструмент подтверждения (confirm_create_order).

Всегда делайте write-инструменты идемпотентными там, где это возможно: повторный вызов с теми же параметрами не должен создавать дубликаты. Используйте idempotency key, передаваемый агентом.

Заключение

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