---
title: "Tool calling com modelos abertos: schemas, retry, código"
description: "Function calling em modelos abertos compatíveis com a OpenAI: schemas, chamadas paralelas, as cinco formas de falha e um loop em Python que valida e tenta de novo."
url: https://broadrouter.com/pt/blog/tool-calling-open-models/
lang: pt-BR
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/blog/tool-calling-open-models/) (atualizado em 2026-11-16).

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

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em 2026-11-14 · Atualizado em 2026-11-16

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.

## Pontos principais

-   O formato é o mesmo da OpenAI: uma lista tools na entrada, tool\_calls na saída e depois uma mensagem com papel tool para cada tool\_call\_id.
-   Os argumentos chegam como string JSON. A documentação do vLLM avisa que, quando extrai chamadas de ferramenta do texto bruto, elas "may occasionally be malformed or violate the function’s parameter schema" (tradução: podem ocasionalmente vir malformadas ou violar o schema de parâmetros da função).
-   Valide toda chamada, devolva os erros como resultados de ferramenta e limite tanto os retries quanto o total de passos.
-   Menos ferramentas, e mais planas, funcionam melhor. A OpenAI sugere menos de 20 funções no início de um turno.
-   Na BroadNet Inference, use GLM 5.3 ou Qwen3.8 27B para tool calling; teste o DeepSeek V4.1 Flash antes de depender dele.

**Nesta página**

1.  Como funciona o tool calling em uma API compatível com a OpenAI?
2.  Como escrever schemas de ferramentas?
3.  E as chamadas paralelas de ferramentas?
4.  Por que as chamadas de ferramenta falham?
5.  Um loop de ferramentas que valida e tenta de novo
6.  Quais modelos da BroadNet suportam tool calling?
7.  Onde a BroadNet Inference se encaixa

[Tool calling](https://broadrouter.com/pt/glossary/tool-calling/) é o que transforma um modelo em um agente. Com modelos abertos em uma [API compatível com a OpenAI](https://broadrouter.com/pt/glossary/openai-compatible-api/), 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](https://broadrouter.com/pt/blog/agent-token-budget/).
-   **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](https://broadrouter.com/tools/json-schema-generator/) 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](https://broadrouter.com/pt/glossary/reasoning-tokens/). GLM 5.3 e Qwen3.8 27B pensam antes de responder, e o pensamento conta em [`max_tokens`](https://broadrouter.com/pt/glossary/max-tokens/). [Por que as respostas voltam vazias ou cortadas](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/) explica quanto espaço deixar.

## Um loop de ferramentas que valida e tenta de novo

```python
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](https://broadrouter.com/pt/guides/errors-and-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](https://broadrouter.com/pt/blog/long-running-agents-timeouts-retries/) cobre isso.

## Quais modelos da BroadNet suportam tool calling?

| Modelo | Ferramentas listadas | Contexto | Observações |
| --- | --- | --- | --- |
| [GLM 5.3](https://broadrouter.com/pt/models/glm-5.3/) | Sim | 1.048.576 | Também saída estruturada |
| [Qwen3.8 27B](https://broadrouter.com/pt/models/qwen3.8-27b/) | Sim | 262.144 | Também entrada de imagens |
| [DeepSeek V4.1 Flash](https://broadrouter.com/pt/models/deepseek-v4.1-flash/) | Não listada | 1.048.576 | Entrada de imagem; teste as ferramentas antes de depender delas |
| [Gemma 4 VL 26B](https://broadrouter.com/pt/models/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](https://broadrouter.com/compare/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](https://broadrouter.com/pt/blog/structured-output-json-schema/) é 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](https://broadrouter.com/pt/guides/openai-python-sdk/). Os preços por token estão na [página de preços](https://broadrouter.com/pt/pricing/). 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.

Ferramentas gratuitas sobre o tema (em inglês)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Ferramentas gratuitas (em inglês)](https://broadrouter.com/tools/)

## Termos neste artigo

[Tool calling (chamada de ferramentas)](https://broadrouter.com/pt/glossary/tool-calling/)

Tool calling, também chamado de function calling ou chamada de ferramentas, é um recurso de APIs de LLM em que o modelo devolve um pedido estruturado para executar uma função definida pelo desenvolvedor, com argumentos JSON. A aplicação executa a função e devolve o resultado; o modelo nunca executa código sozinho.

[Token](https://broadrouter.com/pt/glossary/token/)

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

[Saída estruturada (structured output)](https://broadrouter.com/pt/glossary/structured-output/)

Saída estruturada é um recurso de APIs de LLM que restringe a resposta de um modelo a um formato definido pelo desenvolvedor, normalmente um JSON Schema, para que o código consiga interpretá-la de forma confiável. É mais rigorosa que o JSON mode, que garante um JSON válido, mas não uma estrutura específica.

[vLLM](https://broadrouter.com/pt/glossary/vllm/)

vLLM é uma biblioteca open source de inferência e serving de LLMs, desenvolvida originalmente no Sky Computing Lab da UC Berkeley. Ela gerencia a memória do KV cache com PagedAttention, agrupa as requisições em batching contínuo, suporta muitos formatos de quantização e expõe um servidor HTTP compatível com OpenAI.

[API compatível com a OpenAI](https://broadrouter.com/pt/glossary/openai-compatible-api/)

Uma API compatível com a OpenAI é uma API HTTP que aceita os mesmos formatos de requisição e de resposta da API da OpenAI, como POST /v1/chat/completions, de modo que SDKs e ferramentas da OpenAI podem usá-la trocando só a base URL, a chave de API e o nome do modelo.

[JSON Schema](https://broadrouter.com/pt/glossary/json-schema/)

JSON Schema é um vocabulário, escrito em JSON, para descrever e validar a estrutura de dados JSON: tipos, campos obrigatórios, valores permitidos e aninhamento. A versão atual é a 2020-12. APIs de LLM o usam para definir parâmetros de tools e o formato exato que uma saída estruturada deve seguir.

[Chat Completions API](https://broadrouter.com/pt/glossary/chat-completions-api/)

A Chat Completions API é o endpoint HTTP da OpenAI, POST /v1/chat/completions, que recebe o nome de um modelo e uma lista de mensagens marcadas com papéis e devolve a próxima mensagem do modelo. O formato da requisição e da resposta virou o padrão comum que provedores e SDKs compatíveis com a OpenAI reutilizam.

[Chave de idempotência (idempotency key)](https://broadrouter.com/pt/glossary/idempotency-key/)

Uma chave de idempotência é um valor único, normalmente um ID aleatório como um UUID, que o cliente anexa a uma requisição que altera estado, como um pagamento ou uma compra. Se a mesma requisição for enviada de novo com a mesma chave, o servidor retorna o resultado original em vez de executar a ação duas vezes.

## 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.

## Continue lendo

-   [OpenClaw e Hermes Agent com um modelo barato: setup e custos](https://broadrouter.com/pt/blog/openclaw-hermes-agent-cheap-model/)
-   [JSON mode vs json\_schema: saída estruturada que não quebra](https://broadrouter.com/pt/blog/structured-output-json-schema/)
-   [Servidores MCP com modelos compatíveis com OpenAI (qualquer provedor)](https://broadrouter.com/pt/blog/mcp-with-openai-compatible-models/)
-   [Agentes de longa duração: timeouts, retentativas e checkpoints](https://broadrouter.com/pt/blog/long-running-agents-timeouts-retries/)
-   [Orçamento de tokens de agentes: para onde vão os tokens de um loop](https://broadrouter.com/pt/blog/agent-token-budget/)
-   [Hardware de GPU e serving da BroadNet, segundo a própria BroadNet](https://broadrouter.com/pt/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache de respostas de LLM para cortar custo: um cache exato em Python](https://broadrouter.com/pt/blog/cache-llm-responses-cut-cost/)
-   [Guia: Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)
-   [Guia: Rodar o OpenAI Agents SDK na BroadNet Inference](https://broadrouter.com/pt/guides/openai-agents-sdk-custom-provider/)
-   [Guia: Por que um modelo de raciocínio devolve uma resposta vazia](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/)
-   [Guia: Códigos de erro da BroadNet Inference e quando tentar de novo](https://broadrouter.com/pt/guides/errors-and-retries/)

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-tool-calling-open-models&utm_content=page-cta) ·

**Fontes**

-   [OpenAI, guia de function calling (verificado em 2026-11-14)](https://developers.openai.com/api/docs/guides/function-calling)
-   [Documentação do vLLM, tool calling (verificado em 2026-11-14)](https://docs.vllm.ai/en/latest/features/tool_calling/)
-   [Referência da API da BroadNet Inference, modelos (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-tool-calling-open-models&utm_content=sources#models)
