К содержимому
Блог

Function calling и tool use: как устроить цикл агента

Function calling и tool use: как устроить цикл агента

Function calling нужен, когда модели недостаточно текста и ей надо запросить действие у вашего приложения. Она не читает базу и не отправляет письмо сама. Вместо этого модель возвращает имя инструмента и аргументы, ваше приложение выполняет действие, а затем отдаёт результат обратно. Из таких коротких обменов и складывается агент.

Коротко

  • Инструмент описывают как контракт: назначение, границы применения и схема входа.

  • Результат вызова всегда связывают с конкретным идентификатором, иначе несколько инструментов легко перепутать.

  • Ошибка инструмента тоже результат. Её возвращают модели в структурированном виде и ограничивают число следующих шагов.

  • В Relay шлюз передаёт блок tools Messages без собственного преобразования. Возможность tools видна в каталоге, а протокол для ключа проверяют по usable_protocols.

Что происходит после вызова инструмента?

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

Не путайте модель с исполнителем. Функция списания, запрос в CRM или поиск по закрытым документам происходят в вашем коде. Модель получает лишь описание допустимых действий и текстовый либо структурированный результат.

В Relay для протокола Messages шлюз читает модель, поток и max_tokens; блок tools уходит дальше без собственного преобразования. Полное тело запроса passthrough не остаётся: шлюз подставляет модель маршрута, а настроенный буферизованный маршрут переводит stream в false. Поэтому сначала проверьте возможность tools, затем запросите GET /api/models?allowed_for_key=.... Для Messages у выбранной модели usable_protocols должен содержать anthropic_messages. Формат Messages описан в справочнике Messages API, а совместимый формат находится на странице Chat Completions.

Как выглядит хороший контракт инструмента?

Название не спасёт расплывчатый интерфейс. В определении нужны три вещи: узкое действие, ясные условия выбора и входные поля с ограничениями. Сравните «работа с заказом» с «найти заказ по номеру, когда пользователь уже назвал номер». Во втором случае модели проще решить, нужен ли вызов.

json
{
  "name": "find_order",
  "description": "Находит один заказ по номеру. Вызывай, когда пользователь назвал номер заказа. Не используй для вопросов о правилах доставки.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_number": {
        "type": "string",
        "description": "Номер заказа без пробелов"
      }
    },
    "required": ["order_number"],
    "additionalProperties": false
  }
}

Схема не заменяет проверку на сервере. Поле order_number может быть строкой по JSON Schema и всё равно не принадлежать текущему пользователю. Исполнитель инструмента обязан проверить доступ, формат и допустимость операции до обращения к данным.

Полезное правило: один инструмент делает одно наблюдаемое действие. Не смешивайте поиск, изменение и удаление в одной функции с десятком необязательных полей. Разные операции легче ограничить правами, покрыть тестами и объяснить модели.

Как собрать цикл без путаницы?

Каждый ход начинается с ответа модели. В нативном Messages API она возвращает блок tool_use, когда хочет вызвать инструмент. Ваш код берёт его id, имя и входной объект, вызывает локальный обработчик, сохраняет полный ответ assistant с блоком tool_use в истории, затем добавляет новый пользовательский блок tool_result с тем же идентификатором. Пока модель просит ещё инструменты, цикл повторяется.

text
сообщение пользователя
  → ответ модели с tool_use
  → проверка аргументов и выполнение инструмента
  → полный ответ assistant в истории
  → tool_result с исходным идентификатором
  → следующий ответ модели или финальный текст

В истории это две разные записи. Первая сохраняет блок, который запросил вызов. Вторая возвращает результат с tool_use_id этого блока:

ts
const toolResult = await executeTool(call.name, call.input)

messages.push(
  { role: 'assistant', content: first.content },
  {
    role: 'user',
    content: [{ type: 'tool_result', tool_use_id: call.id, content: JSON.stringify(toolResult) }],
  },
)

Если модель запросила несколько независимых действий, их можно выполнять конкурентно. Но результаты возвращайте с исходными идентификаторами и только после завершения всех запланированных вызовов этого хода. Порядок в массиве не должен быть единственным способом сопоставить вызов и ответ.

Для Chat Completions та же логика выглядит иначе: вызовы лежат в tool_calls, а ответ исполнителя передают сообщением с ролью tool. На уровне приложения цикл остаётся прежним. Различается оболочка JSON, а не ответственность клиента.

Что возвращать при ошибке?

Исключение из функции не даёт модели полезного контекста. Верните контролируемый результат: код ошибки, короткое объяснение и, если это безопасно, следующий допустимый шаг. Например, «заказ не найден по указанному номеру» полезнее, чем трассировка базы данных. Внутренние адреса, SQL, токены и содержание чужих записей в tool_result не попадают.

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

Повторять инструмент бесконечно нельзя. Задайте предел шагов на одну пользовательскую задачу, распознавайте повтор одинаковых аргументов и завершайте диалог понятным сообщением, если дальнейшее действие не меняет состояние. Общие меры для опасных инструментов собраны в статье о безопасности function calling.

Когда нужен выбор инструмента, а когда запрет?

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

Режим не отменяет проверку результата. Даже при жёсткой схеме бизнес-правило может не пройти: сумма не сходится, статус нельзя изменить или поле конфликтует с текущим состоянием. В таком случае верните понятную причину, разрешите ограниченное число исправлений и проверьте объект ещё раз. В проверке должны участвовать и форма объекта, и правила приложения.

Что логировать у агента?

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

Отдельно полезно считать число шагов и долю задач, завершившихся без ручного вмешательства. Эти показатели не говорят, что агент «умный», зато показывают конкретное место поломки: выбор инструмента, проверку доступа, внешний сервис или инструкцию пользователю. Для многошаговой логики пригодится разбор паттернов агентов.

С чего начать без большого фреймворка?

Возьмите один безопасный инструмент только для чтения. Опишите один обязательный параметр, напишите проверку прав и журналирование. Затем соберите десять реальных вопросов, где вызов нужен, не нужен или должен получить отказ. Посмотрите на результаты вручную. Лишь после этого добавляйте второй инструмент и параллельное выполнение.

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

Как проверить набор инструментов до запуска?

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

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

Отдельно проверяйте версии схем. Изменение обязательного поля ломает старого клиента не хуже смены HTTP API. Держите обратную совместимость или публикуйте новую функцию под другим именем, пока все потребители не перешли. В журнале фиксируйте версию инструмента рядом с его именем, иначе старый инцидент будет трудно воспроизвести.

Как не превратить агента в дорогой цикл?

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

Не назначайте повтор на любой сбой по умолчанию. У каждой ошибки должен быть владелец: модель уточняет неполный запрос, клиент ждёт кратковременную сетевую проблему, а пользователь подтверждает необратимое действие. Лимит шагов и лимит размера результата работают вместе. Первый останавливает цикл, второй не даёт одному удачному поиску занять весь контекст.

Как сохранить действие безопасным при повторе?

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

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

Для чтения полезна другая защита: ограничение выборки. Поиск клиентов, документов или заказов должен работать в области прав текущего пользователя ещё до того, как результат попадёт в ответ инструмента. Условие в описании функции помогает модели, но контроль доступа держит обработчик. Так же поступают с лимитом записей и полями ответа.

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

Модель сама выполняет функцию?

Нет. Она возвращает запрос на вызов с именем и аргументами. Код вашего приложения решает, разрешён ли вызов, исполняет его и отправляет результат модели. Поэтому права доступа, лимиты и аудит остаются задачей приложения, а не параметра в промпте.

Можно ли выполнять несколько вызовов одновременно?

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

Что делать, если инструмент постоянно возвращает ошибку?

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

Создать аккаунт

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.