Для AI-агентов: markdown этой страницы — /docs-content/ai/chat/tools.md индекс документации — /llms.txt

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

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

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

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

Terminal 
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
400 tool_choice_without_tools Передан tool_choice, но массив tools отсутствует

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

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

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

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

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

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