Серверные инструменты

Серверные инструменты исполняет AITUNNEL, не ваш код. Модель решает, вызвать ли инструмент; мы выполняем его и возвращаем результат модели.

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

Чем отличаются

СерверныеПлагиныВаши tools
Кто решает вызватьМодельВсегда один разМодель
Кто исполняетAITUNNELAITUNNELВаше приложение
Сколько раз0–N за запросОдин раз0–N за запрос
Где задаютсямассив toolsмассив pluginsмассив tools
Типaitunnel:…не toolsfunction

Плагин — например оптимизация сообщений (context-compression). Ваши функции — вызов инструментов.

Доступные

К цене инструмента добавляются токены модели: результат инструмента попадает в её промпт.

Как это работает

  1. Кладёте серверный инструмент в tools: { "type": "aitunnel:…", "parameters": { … } }. Параметры необязательны, кроме knowledge_base_ids у поиска по базе знаний.
  2. Модель по промпту решает, звать ли его и с какими аргументами.
  3. AITUNNEL исполняет вызов и отдаёт результат модели.
  4. Модель отвечает. Может вызвать инструмент ещё раз в том же запросе.

Клиент получает один ответ — как на обычный запрос.

curl https://aitunnel.83.141.93.205.nip.io/__api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      { "role": "user", "content": "Какие главные анонсы в ИИ на этой неделе?" }
    ],
    "tools": [{ "type": "aitunnel:web_search" }]
  }'

Несколько инструментов в одном запросе:

JSON
{
  "model": "gpt-5.6-sol",
  "messages": [
    { "role": "user", "content": "Успею ли я вернуть заказ, который получил 10 ноября?" }
  ],
  "tools": [
    {
      "type": "aitunnel:file_search",
      "parameters": { "knowledge_base_ids": ["kb_podderzhka-x7k3p9"] }
    },
    {
      "type": "aitunnel:datetime",
      "parameters": { "timezone": "Europe/Moscow" }
    }
  ],
  "max_tool_calls": 5
}

Список инструментов закрытый: неизвестный тип с префиксом aitunnel: — ошибка 400, а не молча пропущенный инструмент.

Что происходит внутри запроса

AITUNNEL исполняет серверные инструменты сам, в цикле:

  1. AITUNNEL вызывает модель.
  2. Модель вызвала серверный инструмент — AITUNNEL исполняет его, добавляет вызов и результат в диалог и вызывает модель снова.
  3. Модель ответила текстом — это ответ на запрос.
  • Один ответ. Клиент получает один ответ. Вызовов серверных инструментов в нём нет; что было исполнено, говорит usage. Если модель писала текст и перед вызовом инструмента, и после, приходит текст всех её вызовов: в /chat/completions — в content, через пустую строку.
  • Каждый вызов модели оплачивается как отдельный запрос. В истории запросов это отдельные строки; следующие связаны с первым. id ответа — ID первого.
  • Где работает. В /chat/completions, /responses и /messages, с любой моделью, которая умеет вызывать функции.
  • Где не работает. Через адрес для Cursor (/v1/cursor) и с API-ключом, у которого включена защита данных: найденное в файлах ушло бы модели без маскировки. С моделями GigaChat тоже: они не вызывают функции, запрос вернёт ошибку 400.
  • Одна модель. Все вызовы делает модель, ответившая на первый: запасная модель выбирается один раз.

Лимиты вызовов

ПолеГдеПо умолчаниюЧто ограничивает
max_tool_callsверхний уровень запроса, рядом с tools10Вызовы всех серверных инструментов вместе за один запрос: 1–10
max_usesparameters инструментасвоё у каждого инструмента, см. его статьюВызовы этого инструмента за один запрос: 1–10
  • Вызов сверх лимита не исполняется: модель узнаёт, что лимит исчерпан, и отвечает тем, что уже нашла.
  • Повторный вызов с теми же аргументами не исполняется и не оплачивается второй раз: модель получает первый результат.
  • Вызов, который завершился ошибкой, модели сообщается и ничего не стоит; запрос продолжается.
  • tool_choice действует только на первый вызов модели. Дальше модель выбирает сама — иначе принудительный вызов повторялся бы без конца.
  • У веб-поиска свои лимиты — max_uses, max_total_results и свой max_tool_calls: см. веб-поиск.

Вместе с вашими функциями

Серверные инструменты и ваши function-tools можно класть в один массив: серверные исполняем мы, пользовательские — вы, как обычно.

JSON
{
  "model": "gpt-5.6-sol",
  "messages": [{ "role": "user", "content": "Найди новости про Apple и сравни с нашей котировкой" }],
  "tools": [
    { "type": "aitunnel:web_search", "parameters": { "max_results": 3 } },
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "Текущая цена акции по тикеру",
        "parameters": {
          "type": "object",
          "properties": { "ticker": { "type": "string" } },
          "required": ["ticker"]
        }
      }
    }
  ]
}
  • Если модель в одном ответе вызвала и серверный инструмент, и вашу функцию, клиент получает только вызовы своих функций. Серверный вызов в этом ответе не исполняется и не оплачивается.
  • Верните результат функции следующим запросом, с тем же tools: если серверный инструмент модели всё ещё нужен, она вызовет его снова.
  • Свою функцию нельзя называть так же, как серверный инструмент из того же запроса: например datetime, когда в tools есть aitunnel:datetime.

Стриминг

Запрос с серверными инструментами и stream: true стримится по токенам, в формате своего API. Модель вызывается несколько раз, а поток один:

  • текст и рассуждения модели приходят по мере генерации, из каждого её вызова;
  • вызовы серверных инструментов в поток не попадают; вызовы ваших функций приходят как обычно;
  • завершение приходит один раз, в самом конце, с итогами по всем вызовам модели: finish_reason и usage в /chat/completions, response.completed в /responses, message_delta и message_stop в /messages.

Пока работает инструмент, текста нет, но соединение не молчит: приходят SSE-комментарии : aitunnel-progress {…} с тем, что сейчас происходит, и : AITUNNEL PROCESSING. SDK пропускают их сами; при ручном разборе пропускайте строки, которые начинаются с :.

SSE
data: {"id":"chat-034pVpllbQhkEIiJgXZpt1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

: aitunnel-progress {"phase":"server_tools","step":1,"tools":["file_search"]}

: AITUNNEL PROCESSING

data: {"id":"chat-034pVpllbQhkEIiJgXZpt1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Вернуть заказ "},"finish_reason":null}]}

data: {"id":"chat-034pVpllbQhkEIiJgXZpt1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"можно в течение 14 дней."},"finish_reason":null}]}

data: {"id":"chat-034pVpllbQhkEIiJgXZpt1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{...}}

data: [DONE]
  • Ошибка в запросе и ошибка первого вызова модели приходят HTTP-статусом, как без стриминга. Ошибка после начала потока — событием в потоке, см. стриминг.
  • Если клиент закрыл соединение, идущий вызов модели отменяется, а новые не начинаются. Уже сделанные вызовы модели и инструментов оплачиваются.
  • В /responses рассуждения (reasoning) промежуточных вызовов модели приходят в потоке, но в итоговый response.completed не входят: в нём текст всех вызовов и элементы последнего.

Учёт

Платите за то, что модель реально вызвала, а не за сам факт передачи инструмента. Итог — в usage ответа:

JSON
{
  "usage": {
    "prompt_tokens": 2310,
    "completion_tokens": 264,
    "total_tokens": 2574,
    "cost_rub": 0.84,
    "balance": 1249.16,
    "cost_details": {
      "model_rub": 0.74,
      "file_search_rub": 0.1
    },
    "server_tool_use": {
      "tool_calls_requested": 2,
      "tool_calls_executed": 2,
      "file_search_requests": 1,
      "datetime_requests": 1
    },
    "rounds": 2
  }
}
ПолеСмысл
prompt_tokens, completion_tokens, total_tokensТокены всех вызовов модели в сумме. В /responses и /messages — input_tokens и output_tokens
cost_rubСколько списано за запрос целиком: все вызовы модели и инструменты
cost_details.model_rubИз них за токены модели
cost_details.file_search_rubЗа поиск по базам знаний. Поля нет, если поиска не было
cost_details.rerank_rubЗа реранкинг результатов поиска. Поля нет, если реранкинга не было
server_tool_use.tool_calls_requestedСколько раз модель вызвала серверные инструменты
server_tool_use.tool_calls_executedСколько вызовов выполнено. Меньше запрошенных, если сработал лимит, вызов повторился или завершился ошибкой
server_tool_use.file_search_requestsСколько поисковых запросов выполнено: за один вызов модель может задать до 5
server_tool_use.rerank_requestsСколько из них переранжировано
server_tool_use.datetime_requestsСколько раз модель узнала время
server_tool_use.web_search_requestsСколько раз модель искала в сети, когда провайдер это сообщает
roundsСколько раз вызвана модель

Веб-поиск устроен иначе: его выполняет провайдер модели внутри одного её вызова, поэтому цикл, max_tool_calls и max_uses из этой статьи, rounds и cost_details к нему не относятся. У запроса только с веб-поиском в usage — server_tool_use.web_search_requests и cost_rub; его лимиты и цены — в статье веб-поиск.

Ошибки

Что не такСообщение
Неизвестный тип aitunnel:…«Неизвестный серверный инструмент: aitunnel:search. Доступны: aitunnel:web_search, aitunnel:file_search, aitunnel:datetime.»
Инструмент указан дважды«Серверный инструмент aitunnel:datetime указан дважды.»
Неверные параметрыЧто не так с полем, например «Укажите часовой пояс в формате IANA, например Europe/Moscow»; поля перечислены в error.metadata.fields
База знаний не вашего аккаунта или её нет«База знаний «kb_…» не найдена. Проверьте knowledge_base_ids в запросе и в пресете, если запрос идёт через пресет.»
Ваша функция названа как серверный инструмент из запроса: file_search, datetime«Имя функции datetime занято серверным инструментом aitunnel:datetime.»
max_tool_calls не целое от 1 до 10«Поле max_tool_calls должно быть целым числом от 1 до 10.»
Запрос через адрес для Cursor (/v1/cursor)«Инструмент aitunnel:file_search в этом методе недоступен.»
У API-ключа включена защита данных«Инструмент aitunnel:file_search не работает с ключом, у которого включено скрытие чувствительных данных.»

Ошибки параметров каждого инструмента — в его статье: веб-поиск, поиск по базе знаний, дата и время.

См. также