Tool calling é o que transforma um modelo em um agente. Com modelos abertos em uma API compatível com a OpenAI, o formato da requisição é o mesmo que você usaria com a OpenAI. O que muda é a frequência com que algo dá errado e o que o servidor faz para evitar. Este post cobre o formato, como escrever schemas que modelos abertos lidam bem, chamadas paralelas, as cinco falhas que você vai ver na prática e um loop em Python que sobrevive a elas.
Como funciona o tool calling em uma API compatível com a OpenAI?
- Você envia
messagesmais uma listatools. Cada ferramenta tem um nome, uma descrição e um JSON Schema para os argumentos. - O modelo responde com
finish_reason: "tool_calls"e uma listatool_calls. Cada item tem umid, um nome de função eargumentscomo string JSON. - O seu código executa cada chamada e acrescenta uma mensagem
role: "tool"por chamada, com otool_call_idcorrespondente. - Você chama a API de novo. O modelo responde ou pede mais ferramentas.
O modelo nunca executa nada. Quem decide o que executar é o seu código.
Como escrever schemas de ferramentas?
Modelos abertos seguem schemas simples com mais confiabilidade. Estas regras vêm do guia da OpenAI e do que costuma quebrar:
- Dê às ferramentas nomes de ação, como
read_fileousearch_code, e diga na descrição quando usar cada uma. - Mantenha a lista curta. O guia da OpenAI trata menos de 20 funções no início de um turno como uma sugestão, não uma regra rígida. Cada schema também é enviado em toda chamada; veja o orçamento de tokens de um agente.
- Prefira argumentos planos. Strings, números, booleanos e enums. Evite aninhamento profundo e objetos livres.
- Use enums para escolhas fixas, assim o modelo não inventa um valor. O gerador de JSON schema transforma um objeto de argumentos de exemplo em um schema plano para colar em
parameters. - Marque os campos obrigatórios. O modo strict da OpenAI exige
additionalProperties: falsee todos os campos emrequired, comnullcomo tipo para os opcionais. Nem todo provedor impõestrict, então valide de qualquer forma.
E as chamadas paralelas de ferramentas?
Um modelo pode retornar vários itens em tool_calls no mesmo turno, por exemplo três leituras de arquivo. Execute em paralelo as chamadas independentes e devolva um resultado por tool_call_id, em qualquer ordem. Se as suas ferramentas têm efeitos colaterais que dependem uns dos outros, defina parallel_tool_calls: false; o guia da OpenAI diz que isso limita o modelo a zero ou uma chamada por turno. Teste se o seu provedor respeita isso.
Por que as chamadas de ferramenta falham?
| Falha | O que você vê | Correção |
|---|---|---|
| Argumentos malformados | json.loads levanta exceção |
Devolva o erro de parse como resultado da ferramenta; tente de novo |
| Schema não respeitado | Campo ausente, tipo errado, enum inventado | Valide; devolva o erro de validação |
| Ferramenta desconhecida | Um nome que você nunca definiu | Devolva “unknown tool, available: …” |
| Nenhuma chamada quando precisa | Resposta em texto | tool_choice: "required" ou uma função específica |
| Chamada cortada | finish_reason: "length" |
Aumente max_tokens; o raciocínio divide esse limite |
As duas primeiras são esperadas, não raras. A documentação de tool calling do vLLM diz que, no modo auto, a menos que uma ferramenta defina strict: true (ou o servidor imponha um piso de rigor) e o parser do modelo suporte restrições, “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (tradução: o vLLM extrai chamadas de ferramenta do texto bruto, então os argumentos podem ocasionalmente vir malformados ou violar o schema de parâmetros da função). Uma função específica usa o backend de structured outputs do vLLM. O seu provedor pode servir os modelos de outro jeito, então trate a validação como obrigatória.
A última linha pega quem usa modelos de raciocínio. GLM 5.3 e Qwen3.8 27B pensam antes de responder, e o pensamento conta em max_tokens. Por que as respostas voltam vazias ou cortadas explica quanto espaço deixar.
Um loop de ferramentas que valida e tenta de novo
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")
Três decisões de design importam aqui:
- Os erros voltam ao modelo como resultados de ferramenta. O modelo vê o que estava errado e normalmente corrige no turno seguinte. Levantar uma exceção joga essa chance fora.
- O loop é limitado.
max_stepspara um modelo que fica chamando ferramentas sem progredir. - Retries de transporte são separados.
max_retriesno cliente trata 429 e 5xx. Argumentos ruins são tratados no loop. Não misture os dois; veja erros e retries.
Para ferramentas com efeitos colaterais, como enviar um e-mail, adicione uma chave de idempotência para que um passo repetido não aja duas vezes. Agentes de longa duração cobre isso.
Quais modelos da BroadNet suportam tool calling?
| Modelo | Ferramentas listadas | Contexto | Observações |
|---|---|---|---|
| GLM 5.3 | Sim | 1.048.576 | Também saída estruturada |
| Qwen3.8 27B | Sim | 262.144 | Também entrada de imagens |
| DeepSeek V4.1 Flash | Não listada | 1.048.576 | Entrada de imagem; teste as ferramentas antes de depender delas |
| Gemma 4 VL 26B | Não listada | 32.768 | Não é para loops de ferramentas |
Para escolher entre os dois modelos com ferramentas, veja GLM 5.3 vs Qwen3.8 27B. Quando a resposta final precisa ter um formato mas nenhuma função precisa rodar, a saída estruturada é mais simples que uma ferramenta.
Onde a BroadNet Inference se encaixa
A BroadNet Inference serve GLM 5.3 e Qwen3.8 27B com tool calling listado, pelo formato padrão de chat completions, então o loop acima roda sem mudanças com o SDK Python da OpenAI. Os preços por token estão na página de preços. Ela não hospeda ferramentas do lado do servidor, como busca na web ou execução de código, e a documentação não lista tool calling para o DeepSeek V4.1 Flash, o modelo dos planos ilimitados. Para um agente que usa muitas ferramentas, use GLM 5.3 ou Qwen3.8 27B por token. Se quiser o plano de preço fixo mesmo assim, confira numa hora Meteor de $1 se o DeepSeek V4.1 Flash chama as suas ferramentas de forma confiável antes de comprar um mês.
