Серверные инструменты
Серверные инструменты исполняет AITUNNEL, не ваш код. Модель решает, вызвать ли инструмент; мы выполняем его и возвращаем результат модели.
Префикс типа — aitunnel:. Доступны три: веб-поиск, поиск по базе знаний и дата и время. У каждого своя статья с параметрами и ценой; здесь — обзор и то, что у инструментов общее.
Чем отличаются
| Серверные | Плагины | Ваши tools | |
|---|---|---|---|
| Кто решает вызвать | Модель | Всегда один раз | Модель |
| Кто исполняет | AITUNNEL | AITUNNEL | Ваше приложение |
| Сколько раз | 0–N за запрос | Один раз | 0–N за запрос |
| Где задаются | массив tools | массив plugins | массив tools |
| Тип | aitunnel:… | не tools | function |
Плагин — например оптимизация сообщений (context-compression). Ваши функции — вызов инструментов.
Доступные
aitunnel:web_searchВеб-поискАктуальная информация из сети. Цена — по тарифу поискового движка.aitunnel:file_searchПоиск по базе знанийПоиск по файлам, которые вы загрузили в базу знаний. 0,1 ₽ за поисковый запрос.aitunnel:datetimeДата и времяТекущие дата и время в нужном часовом поясе. Бесплатно.К цене инструмента добавляются токены модели: результат инструмента попадает в её промпт.
Как это работает
- Кладёте серверный инструмент в
tools:{ "type": "aitunnel:…", "parameters": { … } }. Параметры необязательны, кромеknowledge_base_idsу поиска по базе знаний. - Модель по промпту решает, звать ли его и с какими аргументами.
- AITUNNEL исполняет вызов и отдаёт результат модели.
- Модель отвечает. Может вызвать инструмент ещё раз в том же запросе.
Клиент получает один ответ — как на обычный запрос.
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" }]
}'Несколько инструментов в одном запросе:
{
"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 исполняет серверные инструменты сам, в цикле:
- AITUNNEL вызывает модель.
- Модель вызвала серверный инструмент — AITUNNEL исполняет его, добавляет вызов и результат в диалог и вызывает модель снова.
- Модель ответила текстом — это ответ на запрос.
- Один ответ. Клиент получает один ответ. Вызовов серверных инструментов в нём нет; что было исполнено, говорит
usage. Если модель писала текст и перед вызовом инструмента, и после, приходит текст всех её вызовов: в/chat/completions— вcontent, через пустую строку. - Каждый вызов модели оплачивается как отдельный запрос. В истории запросов это отдельные строки; следующие связаны с первым.
idответа — ID первого. - Где работает. В
/chat/completions,/responsesи/messages, с любой моделью, которая умеет вызывать функции. - Где не работает. Через адрес для Cursor (
/v1/cursor) и с API-ключом, у которого включена защита данных: найденное в файлах ушло бы модели без маскировки. С моделями GigaChat тоже: они не вызывают функции, запрос вернёт ошибку400. - Одна модель. Все вызовы делает модель, ответившая на первый: запасная модель выбирается один раз.
Лимиты вызовов
| Поле | Где | По умолчанию | Что ограничивает |
|---|---|---|---|
max_tool_calls | верхний уровень запроса, рядом с tools | 10 | Вызовы всех серверных инструментов вместе за один запрос: 1–10 |
max_uses | parameters инструмента | своё у каждого инструмента, см. его статью | Вызовы этого инструмента за один запрос: 1–10 |
- Вызов сверх лимита не исполняется: модель узнаёт, что лимит исчерпан, и отвечает тем, что уже нашла.
- Повторный вызов с теми же аргументами не исполняется и не оплачивается второй раз: модель получает первый результат.
- Вызов, который завершился ошибкой, модели сообщается и ничего не стоит; запрос продолжается.
tool_choiceдействует только на первый вызов модели. Дальше модель выбирает сама — иначе принудительный вызов повторялся бы без конца.- У веб-поиска свои лимиты —
max_uses,max_total_resultsи свойmax_tool_calls: см. веб-поиск.
Вместе с вашими функциями
Серверные инструменты и ваши function-tools можно класть в один массив: серверные исполняем мы, пользовательские — вы, как обычно.
{
"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 пропускают их сами; при ручном разборе пропускайте строки, которые начинаются с :.
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 ответа:
{
"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 не работает с ключом, у которого включено скрытие чувствительных данных.» |
Ошибки параметров каждого инструмента — в его статье: веб-поиск, поиск по базе знаний, дата и время.
См. также
- Веб-поиск —
aitunnel:web_search: движки, фильтры доменов, цитаты и цены - Поиск по базе знаний —
aitunnel:file_search: параметры, цена и ошибки - Дата и время —
aitunnel:datetime: часовой пояс и что получает модель - Вызов инструментов — ваши собственные функции