El tool calling (llamada a herramientas) es lo que convierte un modelo en un agente. Con modelos abiertos en una API compatible con OpenAI, el formato de la petición es el mismo que usaría con OpenAI. Lo que cambia es la frecuencia con que algo sale mal y lo que hace el servidor para evitarlo. Este artículo cubre el formato, cómo escribir esquemas que los modelos abiertos manejen bien, las llamadas en paralelo, los cinco fallos que realmente verá y un bucle de Python que los resiste.
¿Cómo funciona el tool calling en una API compatible con OpenAI?
- Usted envía
messagesmás una listatools. Cada herramienta tiene un nombre, una descripción y un JSON Schema para sus argumentos. - El modelo responde con
finish_reason: "tool_calls"y una listatool_calls. Cada entrada tiene unid, un nombre de función yargumentscomo una cadena JSON. - Su código ejecuta cada llamada y añade un mensaje
role: "tool"por llamada, con eltool_call_idcorrespondiente. - Vuelve a llamar a la API. El modelo responde o pide más herramientas.
El modelo nunca ejecuta nada. Su código decide qué se ejecuta.
¿Cómo escribir los esquemas de las herramientas?
Los modelos abiertos siguen con más fiabilidad los esquemas sencillos. Estas reglas salen de la guía de OpenAI y de lo que suele romperse:
- Nombre las herramientas por la acción, como
read_fileosearch_code, y diga en la descripción cuándo usar cada una. - Mantenga la lista corta. La guía de OpenAI presenta menos de 20 funciones al inicio de un turno como una sugerencia flexible. Además, cada esquema se envía en cada llamada; vea el presupuesto de tokens del agente.
- Prefiera argumentos planos. Cadenas, números, booleanos y enums. Evite el anidamiento profundo y los objetos de forma libre.
- Use enums para opciones fijas, de modo que el modelo no pueda inventarse un valor. El generador de JSON Schema convierte un objeto de argumentos de ejemplo en un esquema plano que puede pegar en
parameters. - Marque los campos obligatorios. El modo estricto de OpenAI exige
additionalProperties: falsey todos los campos enrequired, connullcomo tipo para los opcionales. Que un proveedor apliquestricto no varía, así que valide igualmente.
¿Y las llamadas a herramientas en paralelo?
Un modelo puede devolver varias entradas en tool_calls en un mismo turno, por ejemplo tres lecturas de archivo. Ejecute las llamadas independientes de forma concurrente y devuelva un resultado por cada tool_call_id, en cualquier orden. Si sus herramientas tienen efectos secundarios que dependen unos de otros, ponga parallel_tool_calls: false; la guía de OpenAI indica que eso limita al modelo a cero o una llamada por turno. Compruebe que su proveedor lo respeta.
¿Por qué fallan las llamadas a herramientas?
| Fallo | Lo que ve | Solución |
|---|---|---|
| Argumentos mal formados | json.loads lanza una excepción |
Devuelva el error de análisis como resultado de herramienta; reintente |
| No coincide con el esquema | Falta un campo, tipo erróneo, enum inventado | Valide; devuelva el error de validación |
| Herramienta desconocida | Un nombre que nunca definió | Devuelva “unknown tool, available: …” |
| No llama cuando debería | Responde con texto | tool_choice: "required" o una función con nombre |
| Llamada cortada | finish_reason: "length" |
Suba max_tokens; el razonamiento lo comparte |
Los dos primeros son esperables, no raros. La documentación de tool calling de vLLM dice que en modo auto, salvo que una herramienta fije strict: true (o el servidor imponga un mínimo de rigor) y el parser del modelo admita restricciones, “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (Traducción: «vLLM extrae las llamadas a herramientas del texto en bruto, así que los argumentos pueden estar a veces mal formados o incumplir el esquema de parámetros de la función»). Una función con nombre usa el backend de salidas estructuradas de vLLM. Su proveedor puede servir los modelos de otra manera, así que considere obligatoria la validación.
La última fila sorprende a quien usa modelos de razonamiento. GLM 5.3 y Qwen3.8 27B piensan antes de responder, y el pensamiento cuenta dentro de max_tokens. Por qué las respuestas llegan vacías o cortadas explica cuánto margen dejar.
Un bucle de herramientas que valida y reintenta
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")
Aquí importan tres decisiones de diseño:
- Los errores vuelven al modelo como resultados de herramienta. El modelo ve qué estaba mal y suele corregirlo en el turno siguiente. Lanzar una excepción desperdicia esa oportunidad.
- El bucle está acotado.
max_stepsdetiene a un modelo que sigue llamando herramientas sin avanzar. - Los reintentos de transporte van aparte.
max_retriesen el cliente gestiona los 429 y 5xx. Los argumentos incorrectos se gestionan en el bucle. No mezcle ambas cosas; vea errores y reintentos.
En herramientas con efectos secundarios, como enviar un correo, añada una clave de idempotencia para que un paso reintentado no actúe dos veces. Agentes de larga duración trata este tema.
¿Qué modelos de BroadNet admiten tool calling?
| Modelo | Herramientas listadas | Contexto | Notas |
|---|---|---|---|
| GLM 5.3 | Sí | 1,048,576 | También salida estructurada |
| Qwen3.8 27B | Sí | 262,144 | También entrada de imágenes |
| DeepSeek V4.1 Flash | No listadas | 1,048,576 | Entrada de imágenes; pruebe las herramientas antes de depender de ellas |
| Gemma 4 VL 26B | No listadas | 32,768 | No apto para bucles de herramientas |
Para elegir entre los dos modelos con herramientas, vea GLM 5.3 frente a Qwen3.8 27B. Cuando la respuesta final debe ajustarse a una forma pero no hace falta ejecutar ninguna función, la salida estructurada es más sencilla que una herramienta.
Dónde encaja BroadNet Inference
BroadNet Inference sirve GLM 5.3 y Qwen3.8 27B con tool calling listado, mediante el formato estándar de chat completions, así que el bucle anterior funciona sin cambios con el SDK de OpenAI para Python. Los precios por token están en la página de precios. No aloja herramientas del lado del servidor, como búsqueda web o ejecución de código, y su documentación no lista tool calling para DeepSeek V4.1 Flash, el modelo de los planes ilimitados. Para un agente con uso intensivo de herramientas, use GLM 5.3 o Qwen3.8 27B por token. Si de todos modos quiere el plan fijo, compruebe con una hora del plan Meteoro (Meteor) por $1 que DeepSeek V4.1 Flash llama a sus herramientas de forma fiable antes de comprar un mes.
