FlowModels

Deixar o modelo chamar suas funções: tools e tool_calls

Publicado em 11. novembro 2026

Com function calling, o modelo pode decidir que precisa de dados do seu sistema para responder, por exemplo um estoque ou um horário. O FlowModels oferece isso no formato da OpenAI, por meio de tools. Um ponto importante antes de começar: nós não executamos as suas funções. O modelo diz qual função quer chamar e com quais valores. Você a executa no seu sistema e devolve o resultado.

O fluxo em dois passos

Uma chamada de função sempre envolve duas requisições, e as duas são cobradas:

  1. Você envia a pergunta junto com a descrição das suas funções.
  2. O modelo responde com uma chamada. Você a executa e devolve o resultado em uma segunda requisição. Só então o modelo formula a resposta de fato.

Passo 1: oferecer funções

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [{"role": "user", "content": "O artigo A-1042 ainda está em estoque?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "consultar_estoque",
      "description": "Retorna o estoque atual de um artigo.",
      "parameters": {
        "type": "object",
        "properties": {"codigo_artigo": {"type": "string"}},
        "required": ["codigo_artigo"]
      }
    }
  }]
}

Se o modelo quiser usar a função, chega uma resposta com finish_reason: "tool_calls", content: null e as chamadas desejadas:

"message": {
  "role": "assistant",
  "content": null,
  "tool_calls": [{
    "id": "call_abc",
    "type": "function",
    "function": {"name": "consultar_estoque", "arguments": "{\"codigo_artigo\":\"A-1042\"}"}
  }]
}

arguments é um texto contendo JSON, não um objeto. Faça o parse no seu código antes de usar os valores e valide-os como qualquer outra entrada.

Passo 2: devolver o resultado

Sem o Brain, você envia o histórico até ali, a mensagem do modelo com tool_calls e o seu resultado como mensagem com role: "tool". O tool_call_id precisa corresponder exatamente ao id da chamada, senão a API recusa a requisição com HTTP 400:

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [
    {"role": "user", "content": "O artigo A-1042 ainda está em estoque?"},
    {"role": "assistant", "tool_calls": [{"id": "call_abc", "type": "function", "function": {"name": "consultar_estoque", "arguments": "{\"codigo_artigo\":\"A-1042\"}"}}]},
    {"role": "tool", "tool_call_id": "call_abc", "content": "{\"estoque\": 37, \"deposito\": \"Hamburg\"}"}
  ],
  "tools": [ … a mesma lista do passo 1 … ]
}

Se você usa o Brain com external_identifier, no segundo passo envie apenas o mesmo external_identifier, o conversation da resposta e a mensagem com role: "tool". A chamada do modelo já está salva do nosso lado. Enviar o histórico inteiro de novo duplicaria o contexto. Mais sobre o Brain em Usar o Brain: salvar e continuar conversas por usuário final.

Controlar quando uma função é chamada

  • tool_choice: "auto" deixa o modelo decidir, "none" proíbe chamadas, "required" obriga pelo menos uma, e {"type": "function", "function": {"name": "consultar_estoque"}} obriga exatamente essa função. O nome precisa estar em tools.
  • parallel_tool_calls: permite ou proíbe várias chamadas em uma resposta.

Os dois campos só são permitidos junto com tools.

Limites

  • no máximo 128 funções por requisição
  • cada descrição com no máximo 65.536 caracteres, cada schema com no máximo 65.536 bytes
  • nomes de função com 1 a 64 caracteres: letras, dígitos, sublinhado e hífen

Se um modelo aceita funções ou não, GET /models indica em capabilities.tools e capabilities.parallel_tool_calls. Sem esse recurso, você recebe 400 unsupported_for_model, veja O que um modelo sabe fazer: verificar capacidades, limites, tamanho da saída e profundidade de raciocínio.

Streaming e Responses

No streaming, as chamadas chegam reunidas em um chunk próprio logo antes do encerramento, em choices[0].delta.tool_calls com index. No endpoint /responses, elas aparecem como entradas do tipo function_call em output, e você responde com uma entrada do tipo function_call_output. Lá também as funções são enviadas na forma aninhada mostrada acima.

Quando algo não funciona

  • 400 invalid_field_value em tools e flowai_tools: os dois campos são mutuamente exclusivos. flowai_tools controla as ferramentas do nosso lado, e tools controla as suas próprias funções.
  • O modelo chama a função repetidamente: verifique se sua mensagem com role: "tool" traz o tool_call_id correto e se a mensagem do modelo com tool_calls está incluída no segundo passo.
  • 400 por causa do nome: espaços, pontos e letras com acento não são permitidos no nome da função.

Este artigo foi útil?

Voltar para Modelos, limites e erros