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:
- Você envia a pergunta junto com a descrição das suas funções.
- 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 emtools.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_valueemtoolseflowai_tools: os dois campos são mutuamente exclusivos.flowai_toolscontrola as ferramentas do nosso lado, etoolscontrola as suas próprias funções.- O modelo chama a função repetidamente: verifique se sua mensagem com
role: "tool"traz otool_call_idcorreto e se a mensagem do modelo comtool_callsestá incluída no segundo passo. 400por causa do nome: espaços, pontos e letras com acento não são permitidos no nome da função.