Tool calling (function calling) в Heli API: пример на Python

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

• Вы отправляете в POST https://getheli.ru/v1/chat/completions сообщения и массив tools: у каждой функции есть name, description и JSON Schema аргументов в parameters.
• Если модель решила вызвать функцию, в ответе приходит message.tool_calls, а finish_reason равен tool_calls. В каждом вызове есть id, имя функции и arguments — строка с JSON.
• Приложение разбирает arguments, выполняет функцию у себя и добавляет в историю сообщение с role tool, tool_call_id и результатом.
• Повторный запрос с полной историей возвращает итоговый ответ модели. Модель может вызвать несколько функций сразу или сделать несколько кругов.
• Параметр tool_choice управляет поведением: auto — модель решает сама, required — вызов обязателен, none — инструменты запрещены.

Пример на Python

Выполняйте только те функции, которые сами объявили, и проверяйте аргументы перед использованием: модель может прислать неожиданные значения. Для операций с деньгами и данными пользователей добавьте подтверждение человеком.

import json
import os
from openai import OpenAI

client = OpenAI(base_url="https://getheli.ru/v1", api_key=os.environ["HELI_API_KEY"])
MODEL = "openai/gpt-5.4-mini"

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Текущая погода в городе",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

def get_weather(city):
    return {"city": city, "temp_c": 7}  # здесь вызов вашего сервиса

messages = [{"role": "user", "content": "Какая погода в Казани?"}]
resp = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
msg = resp.choices[0].message

if msg.tool_calls:
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result, ensure_ascii=False)})
    resp = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)

print(resp.choices[0].message.content)

Какие модели выбрать

Качество tool calling сильно различается между моделями: слабые модели путают аргументы или отвечают текстом вместо вызова. Для простых функций достаточно недорогой модели, для агентов с десятком инструментов нужна сильная.

GPT-5.4 mini — недорогие вызовы простых функций.

Claude Sonnet 5 — агенты с большим набором инструментов.

Gemini 3.5 Flash — быстрые вызовы в чат-ботах.

Частые ошибки

• Ошибка про сообщение с role tool — в историю не добавлено сообщение ассистента с tool_calls или tool_call_id не совпадает с id вызова.
• Модель не вызывает функцию — уточните description, задайте tool_choice: required или выберите более сильную модель.
• json.loads падает — arguments не валидный JSON; оберните разбор в try и попросите модель повторить вызов.
• 401 и 402 — неверный ключ или закончился баланс; проверьте вкладки «Ключи» и «Баланс».
• Таймауты в длинных циклах — ограничьте число кругов и включите стриминг.

Документация API

Оплата — пополнение баланса.

JSON mode и Structured Outputs