Caicaini
Начать

Возможности

Инструменты

Инструменты превращают модель в вызывающего функции. Ты объявляешь, что она может делать; модель решает, когда позвать; ты выполняешь; результат возвращается в диалог.

Цикл tool-use

  1. Отправь запрос с объявленными tools.
  2. Модель либо отвечает обычным текстом (stop_reason: end_turn), либо просит вызвать инструмент (stop_reason: tool_use).
  3. При tool_use найди в content блок tool_use, выполни свой код с присланным input и добавь user-сообщение с блоком tool_result, ссылающимся на тот же tool_use_id.
  4. Отправь обновлённый список сообщений обратно. Модель продолжит, имея результат в контексте. Повторяй, пока stop_reason не перестанет быть tool_use.

Объявление инструмента

Инструмент — это имя, описание и JSON-схема входа. Не жалей времени на описание самого инструмента и на описание каждого параметра — именно по этим строкам модель решает, звать ли его.

определение инструмента
{
  "name": "get_weather",
  "description": "Get the current weather for a city. Use this when the user asks about temperature, rain, or conditions outside.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name in plain English." },
      "units": { "type": "string", "enum": ["celsius","fahrenheit"], "description": "Default celsius." }
    },
    "required": ["city"]
  }
}

Полный цикл от и до

Пример ниже отправляет один промпт, обрабатывает получившийся вызов инструмента и печатает финальный ответ модели. В проде стоит дополнительно обрабатывать случаи, когда модель просит инструмент, которого ты не знаешь (верни ошибку в content поля tool_result), и когда цикл превышает разумное число итераций (поставь предел в 8 или 10).

curl https://caicaini.com/v1/messages \
  -H "Authorization: Bearer cai_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "caicaini/sonnet",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather for a city.",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": {"type": "string"},
          "units": {"type": "string", "enum": ["celsius","fahrenheit"]}
        },
        "required": ["city"]
      }
    }],
    "messages": [
      {"role": "user", "content": "What is the weather in Lisbon right now?"}
    ]
  }'

Как выглядит ответ tool_use

ответ · stop_reason: tool_use
{
  "id": "msg_01H...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01XyZ...",
      "name": "get_weather",
      "input": { "city": "Lisbon", "units": "celsius" }
    }
  ],
  "model": "caicaini/sonnet",
  "stop_reason": "tool_use",
  "usage": { "input_tokens": 122, "output_tokens": 38, "credits_consumed": 76 }
}

Ответ через tool_result

user-сообщение
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01XyZ...",
      "content": "{\"city\":\"Lisbon\",\"temperature\":21,\"units\":\"celsius\",\"conditions\":\"Sunny\"}"
    }
  ]
}

Принудительный вызов инструмента

По умолчанию решение остаётся за моделью. Это можно переопределить через tool_choice:

  • developers.docs.tools.toolChoiceItem1
  • developers.docs.tools.toolChoiceItem2
  • developers.docs.tools.toolChoiceItem3

Параллельные вызовы инструментов

Один поворот ассистента может содержать несколько блоков tool_use. Выполняй их параллельно на клиенте и отправь одно user-сообщение с тем же количеством блоков tool_result в том же порядке.

Возврат ошибок модели

Если инструмент упал, верни tool_result с JSON-кодированным телом ошибки и поставь is_error в true. Модель увидит сбой и либо повторит с другими параметрами, либо извинится перед пользователем.

tool_result с is_error
{
  "type": "tool_result",
  "tool_use_id": "toolu_01XyZ...",
  "is_error": true,
  "content": "{\"error\":\"city_not_found\",\"city\":\"Atlantis\"}"
}

Какие модели поддерживают инструменты

Все пять виртуальных id принимают инструменты. Качество и надёжность выше всего у caicaini/opus и caicaini/sonnet; меньшие модели отлично справляются с узкими, малонеоднозначными инструментами. Для сложных агентских циклов с множеством инструментов и долгим рассуждением сочетай инструменты с расширенным размышлением на caicaini/opus.

ДалееРазмышление