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

Как использовать функции и инструменты в запросах к AI моделям

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

Tool Calling позволяет AI моделям вызывать определённые вами функции для получения данных или выполнения действий.

Поддержка tool calling зависит от модели. Проверяйте возможности в каталоге моделей.

Что такое Tool Calling?

Tool Calling (вызов функций) позволяет модели:

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

Сценарии использования

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

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

Определите функции: опишите доступные функции с параметрами в формате JSON Schema
Отправьте запрос: передайте описание функций вместе с сообщением пользователя
Получите вызов: модель вернёт название функции и параметры для вызова
Выполните функцию: вызовите функцию в своём коде и верните результат модели
Получите финальный ответ: модель использует результат для формирования ответа пользователю

Пример использования

1. Определение функций

# tools передаётся в запросе вместе с messages
curl -X POST "https://api.usellm.ru/v1/chat/completions" \
  -H "Authorization: Bearer <USELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [{"role": "user", "content": "Какая погода в Москве?"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Получить текущую погоду в указанном городе",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string", "description": "Название города, например Москва"},
              "units": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "Единицы измерения температуры"}
            },
            "required": ["city"]
          }
        }
      }
    ]
  }'

const tools = [
  {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Получить текущую погоду в указанном городе',
      parameters: {
        type: 'object',
        properties: {
          city: {
            type: 'string',
            description: 'Название города, например "Москва"'
          },
          units: {
            type: 'string',
            enum: ['celsius', 'fahrenheit'],
            description: 'Единицы измерения температуры'
          }
        },
        required: ['city']
      }
    }
  },
  {
    type: 'function',
    function: {
      name: 'send_email',
      description: 'Отправить email',
      parameters: {
        type: 'object',
        properties: {
          to: { type: 'string', description: 'Email получателя' },
          subject: { type: 'string', description: 'Тема письма' },
          body: { type: 'string', description: 'Текст письма' }
        },
        required: ['to', 'subject', 'body']
      }
    }
  }
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Получить текущую погоду в указанном городе",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "Название города, например 'Москва'"
                    },
                    "units": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Единицы измерения температуры"
                    }
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "send_email",
            "description": "Отправить email",
            "parameters": {
                "type": "object",
                "properties": {
                    "to": {"type": "string", "description": "Email получателя"},
                    "subject": {"type": "string", "description": "Тема письма"},
                    "body": {"type": "string", "description": "Текст письма"}
                },
                "required": ["to", "subject", "body"]
            }
        }
    }
]

2. Отправка запроса с функциями

curl -X POST "https://api.usellm.ru/v1/chat/completions" \
  -H "Authorization: Bearer <USELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [
      {"role": "user", "content": "Какая погода в Москве?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Получить текущую погоду в указанном городе",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string", "description": "Название города"}
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

import OpenAI from 'openai'

const openai = new OpenAI({
  baseURL: 'https://api.usellm.ru/v1',
  apiKey: '<USELLM_API_KEY>'
})

const completion = await openai.chat.completions.create({
  model: 'openai/gpt-6-astra',
  messages: [
    { role: 'user', content: 'Какая погода в Москве?' }
  ],
  tools,
  tool_choice: 'auto' // или 'required' для обязательного вызова
})

// Проверяем, запросила ли модель вызов функции
if (completion.choices[0].message.tool_calls) {
  const toolCall = completion.choices[0].message.tool_calls[0]
  console.log('Функция:', toolCall.function.name)
  console.log('Параметры:', toolCall.function.arguments)
}

from openai import OpenAI

client = OpenAI(
    base_url="https://api.usellm.ru/v1",
    api_key="<USELLM_API_KEY>"
)

completion = client.chat.completions.create(
    model="openai/gpt-6-astra",
    messages=[
        {"role": "user", "content": "Какая погода в Москве?"}
    ],
    tools=tools,
    tool_choice="auto"  # или "required" для обязательного вызова
)

# Проверяем, запросила ли модель вызов функции
if completion.choices[0].message.tool_calls:
    tool_call = completion.choices[0].message.tool_calls[0]
    print(f"Функция: {tool_call.function.name}")
    print(f"Параметры: {tool_call.function.arguments}")

3. Обработка вызова и отправка результата

curl -X POST "https://api.usellm.ru/v1/chat/completions" \
  -H "Authorization: Bearer <USELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [
      {"role": "user", "content": "Какая погода в Москве?"},
      {"role": "assistant", "content": null, "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"Москва\"}"}}]},
      {"role": "tool", "tool_call_id": "call_abc123", "content": "{\"temperature\": 15, \"units\": \"celsius\", \"condition\": \"облачно с прояснениями\"}"}
    ],
    "tools": []
  }'

// Получаем вызов функции от модели
const toolCall = completion.choices[0].message.tool_calls[0]
const args = JSON.parse(toolCall.function.arguments)

// Выполняем функцию (ваша реализация)
const weatherData = await getWeather(args.city, args.units)

// Отправляем результат обратно модели
const finalCompletion = await openai.chat.completions.create({
  model: 'openai/gpt-6-astra',
  messages: [
    { role: 'user', content: 'Какая погода в Москве?' },
    completion.choices[0].message, // Сообщение с tool_calls
    {
      role: 'tool',
      tool_call_id: toolCall.id,
      content: JSON.stringify(weatherData)
    }
  ],
  tools
})

console.log(finalCompletion.choices[0].message.content)
// "В Москве сейчас +15°C, облачно с прояснениями."

import json

# Получаем вызов функции от модели
tool_call = completion.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)

# Выполняем функцию (ваша реализация)
weather_data = get_weather(args["city"], args.get("units"))

# Отправляем результат обратно модели
final_completion = client.chat.completions.create(
    model="openai/gpt-6-astra",
    messages=[
        {"role": "user", "content": "Какая погода в Москве?"},
        completion.choices[0].message,  # Сообщение с tool_calls
        {
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(weather_data)
        }
    ],
    tools=tools
)

print(final_completion.choices[0].message.content)
# "В Москве сейчас +15°C, облачно с прояснениями."

Параметры tool_choice

Значение	Описание
`auto`	Модель решает, вызывать ли функцию
`required`	Модель обязательно вызовет одну из функций
`none`	Модель не будет вызывать функции
`{"type": "function", "function": {"name": "..."}}`	Вызвать конкретную функцию

Параллельные вызовы

Модель может запросить несколько функций одновременно:

{
  "tool_calls": [
    {
      "id": "call_1",
      "function": { "name": "get_weather", "arguments": "{\"city\": \"Москва\"}" }
    },
    {
      "id": "call_2",
      "function": { "name": "get_weather", "arguments": "{\"city\": \"Санкт-Петербург\"}" }
    }
  ]
}

Обрабатывайте все вызовы и возвращайте результаты для каждого tool_call_id.

Советы и лучшие практики

Пишите понятные описания

Используйте enum для ограниченных значений

Обрабатывайте ошибки

Ограничивайте количество функций

Следующие шаги

Структурный вывод

Получение структурированных данных

Текстовые запросы

Основы работы с Chat Completions API