Использование инструментов и вызов функций

Дайте модели возможность вызывать ваши функции — цикл запросов, оба формата и ошибки, которые расходуют токены.

Использование инструментов позволяет модели попросить вас выполнить функцию, а затем продолжить работу с её результатом. На этом механизме основан каждый агент для программирования.

Цикл работы

1. Вы отправляете messages и tools с описанием доступных возможностей.
2. Модель отвечает stop_reason: tool_use и tool_use блоком с названием инструмента и его аргументами.
3. Вы выполняете его — шлюз никогда не запускает ваш код.
4. Вы отправляете обратно всю историю вместе с tool_result блоком.
5. Модель формирует окончательный ответ или запрашивает другой инструмент.

Определение инструментов (формат Messages)

Copy{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Current weather for a city. Use when the user asks about weather.",
    "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string", "description": "City name"}},
      "required": ["city"]
    }
  }],
  "messages": [{"role": "user", "content": "Weather in Paris?"}]
}

Возврат результата

Copy{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC...",
    "content": "18C, light rain"
  }]
}

Формат OpenAI

В /v1/chat/completions эндпоинт принимает формат OpenAI tools / tool_calls вместо этого, а результаты возвращаются в виде сообщений с ролью tool.

Стоимость использования инструментов

• Определения повторно отправляются на каждом шаге. Двадцать подробных схем инструментов могут составить основную часть входных токенов ещё до начала диалога.
• Результаты становятся контекстом. Если инструмент возвращает 200 строк JSON, все они попадают в следующий запрос и в каждый последующий.
• Каждый цикл запроса и ответа оплачивается как отдельный вызов. Задача с пятью инструментами требует как минимум шести запросов.
• Ограничивайте длину вывода инструмента и сокращайте результаты перед возвратом. Сокращение результата до того, что действительно нужно модели, — самое эффективное изменение в большинстве циклов работы агента.