Вызов инструментов — то, что превращает модель в агента. С открытыми моделями в OpenAI-совместимом API формат запроса тот же, что и с OpenAI. Различается то, как часто что-то идёт не так, и что сервер делает, чтобы это предотвратить. В статье — формат, как писать схемы, с которыми открытые модели хорошо справляются, параллельные вызовы, пять сбоев, которые вы действительно увидите, и цикл на Python, который их переживает.
Как работает вызов инструментов в OpenAI-совместимом API?
- Вы отправляете
messagesи списокtools. У каждого инструмента есть имя, описание и JSON Schema для аргументов. - Модель отвечает с
finish_reason: "tool_calls"и спискомtool_calls. В каждом элементе естьid, имя функции иargumentsв виде JSON-строки. - Ваш код выполняет каждый вызов и добавляет по одному сообщению
role: "tool"на вызов с соответствующимtool_call_id. - Вы снова вызываете API. Модель отвечает или запрашивает ещё инструменты.
Сама модель ничего не выполняет. Что запускать, решает ваш код.
Как писать схемы инструментов?
Открытые модели надёжнее следуют простым схемам. Эти правила взяты из руководства OpenAI и из того, что обычно ломается:
- Называйте инструменты по действию, например
read_fileилиsearch_code, и пишите в описании, когда использовать каждый. - Держите список коротким. Руководство OpenAI называет «меньше 20 функций в начале хода» мягкой рекомендацией. К тому же каждая схема отправляется при каждом вызове; см. бюджет токенов агента.
- Предпочитайте плоские аргументы. Строки, числа, булевы значения и enum. Избегайте глубокой вложенности и объектов произвольной формы.
- Используйте enum для фиксированных вариантов, чтобы модель не могла придумать значение. Генератор JSON Schema превращает образец объекта аргументов в плоскую схему, которую можно вставить в
parameters. - Отмечайте обязательные поля. Строгий режим OpenAI требует
additionalProperties: falseи все поля вrequired, а для необязательных —nullкак один из типов. Обеспечивает ли провайдерstrict, бывает по-разному, так что валидируйте в любом случае.
А что с параллельными вызовами?
Модель может вернуть за один ход несколько элементов в tool_calls, например три чтения файлов. Выполняйте независимые вызовы параллельно и возвращайте по одному результату на каждый tool_call_id, в любом порядке. Если у инструментов есть побочные эффекты, зависящие друг от друга, задайте parallel_tool_calls: false; по руководству OpenAI, тогда модель делает не больше одного вызова за ход. Проверьте, что ваш провайдер это учитывает.
Почему вызовы инструментов сбоят?
| Сбой | Что вы видите | Решение |
|---|---|---|
| Некорректные аргументы | json.loads выбрасывает исключение |
Вернуть ошибку разбора как результат инструмента; повторить |
| Несоответствие схеме | Нет поля, не тот тип, выдуманное значение enum | Валидировать; вернуть ошибку валидации |
| Неизвестный инструмент | Имя, которое вы не определяли | Вернуть «unknown tool, available: …» |
| Нет вызова, когда он нужен | Вместо него текстовый ответ | tool_choice: "required" или конкретная функция |
| Обрезанный вызов | finish_reason: "length" |
Увеличить max_tokens; рассуждения делят тот же лимит |
Первые два сбоя ожидаемы, а не редки. Документация vLLM по вызову инструментов говорит, что в режиме auto, если инструмент не задаёт strict: true (или сервер не навязывает минимальную строгость) и парсер модели не поддерживает ограничения, “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (перевод: «vLLM извлекает вызовы инструментов из сырого текста, поэтому аргументы иногда могут быть некорректными или нарушать схему параметров функции».) Для явно указанной функции vLLM использует бэкенд структурированного вывода. Ваш провайдер может обслуживать модели иначе, поэтому считайте валидацию обязательной.
На последней строке спотыкаются те, кто использует модели с рассуждениями. GLM 5.3 и Qwen3.8 27B размышляют перед ответом, и размышления входят в max_tokens. Почему ответы приходят пустыми или обрезанными — там же сказано, сколько места оставить.
Цикл инструментов с валидацией и повторами
import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"
TOOLS = [{"type": "function", "function": {
"name": "get_order_status",
"description": "Look up one order by its ID. Use when the user asks where an order is.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}
def run_call(call):
name = call.function.name
if name not in IMPL:
return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
try:
args = json.loads(call.function.arguments or "{}")
validate(args, SCHEMAS[name])
except (json.JSONDecodeError, ValidationError) as e:
return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
return str(IMPL[name](**args))
def agent(messages, max_steps=8):
for _ in range(max_steps):
r = client.chat.completions.create(model=MODEL, messages=messages,
tools=TOOLS, max_tokens=4000)
msg = r.choices[0].message
if r.choices[0].finish_reason == "length":
raise RuntimeError("Output limit reached; raise max_tokens")
messages.append(msg.model_dump(exclude_none=True))
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
messages.append({"role": "tool", "tool_call_id": call.id,
"content": run_call(call)})
raise RuntimeError("Step limit reached")
Здесь важны три проектных решения:
- Ошибки возвращаются модели как результаты инструментов. Модель видит, что было не так, и обычно исправляет это на следующем ходу. Выбросив исключение, вы лишаете её этого шанса.
- Цикл ограничен.
max_stepsостанавливает модель, которая продолжает вызывать инструменты без прогресса. - Повторы на уровне транспорта — отдельно.
max_retriesу клиента обрабатывает 429 и 5xx. Плохие аргументы обрабатываются в цикле. Не смешивайте одно с другим; см. ошибки и повторы.
Для инструментов с побочными эффектами, например отправки письма, добавьте ключ идемпотентности, чтобы повторённый шаг не сработал дважды. Подробнее — в статье о долго работающих агентах.
Какие модели BroadNet поддерживают вызов инструментов?
| Модель | Инструменты указаны | Контекст | Примечания |
|---|---|---|---|
| GLM 5.3 | Да | 1 048 576 | Также структурированный вывод |
| Qwen3.8 27B | Да | 262 144 | Также ввод изображений |
| DeepSeek V4.1 Flash | Не указаны | 1 048 576 | Ввод изображений; протестируйте инструменты, прежде чем на них полагаться |
| Gemma 4 VL 26B | Не указаны | 32 768 | Не для циклов с инструментами |
Как выбрать между двумя моделями с поддержкой инструментов, см. GLM 5.3 или Qwen3.8 27B. Когда итоговый ответ должен иметь определённую форму, но никакую функцию запускать не нужно, структурированный вывод проще инструмента.
Место BroadNet Inference
BroadNet Inference обслуживает GLM 5.3 и Qwen3.8 27B с заявленным вызовом инструментов через стандартный формат chat completions, так что цикл выше работает без изменений с OpenAI Python SDK. Цены за токены — на странице цен. Серверных инструментов вроде веб-поиска или выполнения кода BroadNet не предоставляет, а в документации вызов инструментов не указан для DeepSeek V4.1 Flash — модели безлимитных тарифов. Для агента, активно работающего с инструментами, берите GLM 5.3 или Qwen3.8 27B с оплатой за токены. Если вам всё же нужен фиксированный тариф, перед покупкой месяца проверьте на часе Meteor за $1, что DeepSeek V4.1 Flash надёжно вызывает ваши инструменты.
