Вызов функций (tools)

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

Как устроен цикл

1. В запрос вместе с сообщениями передаётся описание доступных функций.
2. Модель отвечает не текстом, а списком вызовов: имя функции и аргументы.
3. Приложение выполняет вызов своими силами и получает результат.
4. Результат отправляется следующим запросом, и модель отвечает уже с учётом данных.

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

Описание функций

Функции перечисляются в поле tools. У каждой есть имя, описание и схема аргументов в формате JSON Schema. По описанию модель понимает, когда функция уместна, поэтому формулировать его стоит внятно.

curlpythonnode.js
curl "https://api.proxyapi.ru/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <КЛЮЧ>" \
    -d '{
        "model": "google/gemini-2.5-flash",
        "messages": [
            {"role": "user", "content": "Какая погода в Иркутске?"}
        ],
        "tools": [{
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Текущая погода в городе",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string", "description": "Название города"}
                    },
                    "required": ["city"]
                }
            }
        }]
    }'

Ответ с вызовом

Если модель решила воспользоваться функцией, поле content приходит пустым, а finish_reason равен tool_calls. Сами вызовы лежат в массиве tool_calls:

{
    "choices": [{
        "message": {
            "role": "assistant",
            "content": null,
            "tool_calls": [{
                "id": "call_a1b2c3",
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "arguments": "{\"city\": \"Иркутск\"}"
                }
            }]
        },
        "finish_reason": "tool_calls"
    }]
}

Возврат результата

Результат отправляется следующим запросом. В messages добавляются два сообщения: ответ модели с вызовом — как есть, и результат в роли tool с тем же идентификатором tool_call_id.

{
    "model": "google/gemini-2.5-flash",
    "messages": [
        {"role": "user", "content": "Какая погода в Иркутске?"},
        {
            "role": "assistant",
            "tool_calls": [{
                "id": "call_a1b2c3",
                "type": "function",
                "function": {"name": "get_weather", "arguments": "{\"city\": \"Иркутск\"}"}
            }]
        },
        {
            "role": "tool",
            "tool_call_id": "call_a1b2c3",
            "content": "{\"temperature\": -18, \"condition\": \"ясно\"}"
        }
    ]
}

Описание tools передаётся и во втором запросе тоже: без него модель не поймёт, откуда взялось сообщение в роли tool. Цикл может повториться — ничто не мешает модели запросить ещё один вызов после первого результата.

Управление вызовами

Поддержка этих параметров зависит от модели: не каждая умеет вызывать несколько функций сразу или подчиняться жёсткому tool_choice.

Что дальше

• Структурированный вывод — как получить JSON по схеме, если внешний вызов не нужен.
• Генерация текста — устройство запроса и ответа.