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

Опишите функции, которые модель может вызвать, и она сама решит, когда это нужно. Модель не выполняет функцию — она возвращает её имя и аргументы, а вызов делает ваш код. Результат вы отправляете обратно в диалог, и модель формулирует финальный ответ.

Когда модель решает вызвать функцию, `finish_reason` равен `tool_calls`, а `content` — `null`. Аргументы приходят в `tool_calls[].function.arguments` строкой с JSON.

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/chat/completions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.5",
    "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"
  }'
```

## Пример ответа

```json
{
  "id": "chatcmpl-9aaee7576d8057ab",
  "object": "chat.completion",
  "model": "bitrix/bitrixgpt-5.5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "tool_calls",
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "chatcmpl-tool-a423212c4e614cab",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"Москва\"}"
            }
          }
        ]
      }
    }
  ],
  "usage": {"prompt_tokens": 275, "completion_tokens": 26, "total_tokens": 301}
}
```

## Возврат результата в диалог

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

```json
{
  "messages": [
    {"role": "user", "content": "Какая погода в Москве?"},
    {"role": "assistant", "content": null, "tool_calls": [{"id": "chatcmpl-tool-a423212c4e614cab", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"Москва\"}"}}]},
    {"role": "tool", "tool_call_id": "chatcmpl-tool-a423212c4e614cab", "content": "+5°C, облачно"}
  ]
}
```

Следующим ответом модель сформулирует человеческий текст на основе полученного результата.

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `unsupported_tool_type` | В массиве `tools` есть элемент с `type`, отличным от `function`. Для поиска в интернете используйте [`POST /v1/search`](/docs/search/run) |
| 400 | `tool_choice_without_tools` | Передан `tool_choice`, но массив `tools` отсутствует |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Поддерживается только `type: "function"`.** Встроенных инструментов вроде поиска в интернете у эндпоинта нет. Запрос с другим значением `type` отклоняется с `400`, а не выполняется молча без инструментов.

**Имена в ответе сверяются с вашим списком.** Если модель придумала имя функции, которого нет в `tools`, такой вызов удаляется из ответа. Когда придуманными оказываются все вызовы, `finish_reason` меняется на `stop`, а в `content` приходит текстовое объяснение — диалог не зацикливается на несуществующей функции.

**Аргументы приходят строкой.** Поле `arguments` — это JSON в виде строки, его нужно разобрать перед использованием. Модель может вернуть синтаксически корректный JSON, не соответствующий вашей схеме параметров, поэтому проверяйте значения перед вызовом.

## Смотрите также

- [Создать чат-комплишен](./completions.md)
- [Гарантированный JSON-ответ](./json.md)
- [Веб-поиск](/docs/search/run)
- [Список моделей](/docs/ai/models/list)