> ## Documentation Index
> Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

<Note>
  Поддержка tool calling зависит от модели. Проверяйте возможности в [каталоге моделей](/docs/gaidy/models).
</Note>

## Что такое Tool Calling?

Tool Calling (вызов функций) — это механизм, позволяющий модели:

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

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

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

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

<Steps>
  <Step title="Определите функции">
    Опишите доступные функции с параметрами в формате JSON Schema
  </Step>

  <Step title="Отправьте запрос">
    Передайте описание функций вместе с сообщением пользователя
  </Step>

  <Step title="Получите вызов">
    Модель вернёт название функции и параметры для вызова
  </Step>

  <Step title="Выполните функцию">
    Вызовите функцию в своём коде и верните результат модели
  </Step>

  <Step title="Получите финальный ответ">
    Модель использует результат для формирования ответа пользователю
  </Step>
</Steps>

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

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

```typescript theme={null}
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']
      }
    }
  }
];
```

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

```typescript theme={null}
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://speshu.ai/api/v1',
  apiKey: '<SPESHU_AI_API_KEY>'
});

const completion = await openai.chat.completions.create({
  model: 'openai/gpt-5.5',
  messages: [
    { role: 'user', content: 'Какая погода в Москве?' }
  ],
  tools: tools,
  tool_choice: 'auto'
});

// Проверяем, запросила ли модель вызов функции
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);
}
```

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

```typescript theme={null}
// Получаем вызов функции от модели
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-5.5',
  messages: [
    { role: 'user', content: 'Какая погода в Москве?' },
    completion.choices[0].message,
    {
      role: 'tool',
      tool_call_id: toolCall.id,
      content: JSON.stringify(weatherData)
    }
  ],
  tools: tools
});
```

## Параметры tool\_choice

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

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

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

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

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

**Пишите понятные описания**
Чем точнее описание функции и параметров, тем лучше модель понимает, когда её использовать.

**Используйте enum для ограниченных значений**
Если параметр имеет фиксированный набор значений, используйте `enum` для валидации.

**Обрабатывайте ошибки**
Если функция завершилась с ошибкой, верните понятное описание ошибки модели.

**Ограничивайте количество функций**
Большое количество функций усложняет выбор для модели. Группируйте связанные операции.