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

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

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

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

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"
  }'

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

{
  "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:

{
  "messages": [
    {"role": "user", "content": "Какая погода в Москве?"},
    {"role": "assistant", "content": null, "reasoning_content": "Нужна погода по городу — вызываю get_weather с city=Москва.", "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, облачно"}
  ]
}

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

Модель с рассуждением читает в таком диалоге рассуждение каждого прошлого хода ассистента, поэтому возвращайте его полем reasoning_content рядом с tool_calls того же сообщения — иначе модель теряет нить между вызовами. Условия приёма поля и максимум символов — Создать чат-комплишен.

Ошибки

Полный список общих ошибок API — Ошибки.

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

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

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

В потоковом режиме этот фильтр имён не применяется: проверяйте имя вызова по своему списку tools перед исполнением. Если вызов был отброшен ещё до платформы, пустой ход или финиш вызова без самого вызова сопровождается текстовым объяснением. Синхронный ответ также содержит предупреждение TOOL_CALL_MISSING; в потоке объяснение приходит в delta.content до finish_reason: "stop". Используйте объявленные инструменты для продолжения. При tool_choice: "none" и структурированном ответе это объяснение не добавляется.

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

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

• Создать чат-комплишен
• Гарантированный JSON-ответ
• Веб-поиск
• Список моделей