BroadRouter
Começar

Tool calling com modelos abertos: schemas, chamadas paralelas, retry

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em · Atualizado em

Modelos abertos em APIs compatíveis com a OpenAI usam o mesmo formato tools e tool_calls da OpenAI. Mantenha os schemas pequenos e planos, trate os argumentos como strings JSON, valide-os antes de executar qualquer coisa e devolva os erros ao modelo como resultados de ferramenta para ele tentar de novo. Limite os passos. Na BroadNet, GLM 5.3 e Qwen3.8 27B listam suporte a ferramentas.

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?

  1. Você envia messages mais uma lista tools. Cada ferramenta tem um nome, uma descrição e um JSON Schema para os argumentos.
  2. O modelo responde com finish_reason: "tool_calls" e uma lista tool_calls. Cada item tem um id, um nome de função e arguments como string JSON.
  3. O seu código executa cada chamada e acrescenta uma mensagem role: "tool" por chamada, com o tool_call_id correspondente.
  4. 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_file ou search_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: false e todos os campos em required, com null como tipo para os opcionais. Nem todo provedor impõe strict, 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:

  1. 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.
  2. O loop é limitado. max_steps para um modelo que fica chamando ferramentas sem progredir.
  3. Retries de transporte são separados. max_retries no 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.

Perguntas frequentes

Modelos abertos suportam function calling?

Muitos sim, mas o suporte depende do modelo e de como o provedor o serve. Na BroadNet Inference, a documentação lista tool calling para GLM 5.3 e Qwen3.8 27B. Não lista para DeepSeek V4.1 Flash nem para Gemma 4 VL 26B.

Por que os argumentos das minhas chamadas de ferramenta vêm como JSON inválido?

A menos que o servidor restrinja a decodificação, os argumentos são gerados como texto e parseados depois. A documentação do vLLM diz que argumentos extraídos do texto bruto podem ocasionalmente vir malformados. Capture o erro de parse e devolva-o como resultado da ferramenta para o modelo se corrigir.

Como desativo as chamadas paralelas de ferramentas?

No formato da OpenAI, defina parallel_tool_calls como false. Isso limita o modelo a zero ou uma chamada de ferramenta por turno. Confira se o seu provedor respeita o campo.

Por que o modelo responde em texto em vez de chamar uma ferramenta?

Com tool_choice auto, quem decide é o modelo. Defina tool_choice como required, ou como uma função específica, quando a chamada for obrigatória. Confira também se a descrição da ferramenta diz quando usá-la.

Por que a minha chamada de ferramenta vem cortada?

Modelos de raciocínio contam o pensamento em max_tokens. Um limite pequeno pode encerrar a resposta no meio dos argumentos. Confira o finish_reason e aumente max_tokens.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity