FlowModels

Let the model call your own functions: tools and tool_calls

Published on 11. November 2026

With function calling, the model can decide that it needs data from your system for a response, for example a stock level or an appointment. FlowModels supports this in OpenAI's format through tools. One important point up front: We don't run your functions. The model tells you which function it wants to call with which values. You run it in your system and send the result back.

The two-step flow

A function call always consists of two requests, and both are billed:

  1. You send the question together with the description of your functions.
  2. The model responds with a call. You run it and send the result back in a second request. Only then does the model write the actual response.

Step 1: Offer functions

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [{"role": "user", "content": "Is item A-1042 still in stock?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_stock_level",
      "description": "Returns the current stock level of an item.",
      "parameters": {
        "type": "object",
        "properties": {"item_number": {"type": "string"}},
        "required": ["item_number"]
      }
    }
  }]
}

If the model wants to use the function, you get a response with finish_reason: "tool_calls", content: null and the requested calls:

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

arguments is a text with JSON inside, not an object. Parse it in your code before you use the values, and validate them like any other input.

Step 2: Send the result back

Without the Brain, you send the history so far, the model's message with tool_calls and your result as a message with role: "tool". The tool_call_id must match the id from the call exactly, otherwise the API rejects the request with HTTP 400:

{
  "model": "groq/openai/gpt-oss-120b",
  "messages": [
    {"role": "user", "content": "Is item A-1042 still in stock?"},
    {"role": "assistant", "tool_calls": [{"id": "call_abc", "type": "function", "function": {"name": "get_stock_level", "arguments": "{\"item_number\":\"A-1042\"}"}}]},
    {"role": "tool", "tool_call_id": "call_abc", "content": "{\"stock\": 37, \"warehouse\": \"Hamburg\"}"}
  ],
  "tools": [ … same list as in step 1 … ]
}

If you use the Brain with external_identifier, in the second step you send only the same external_identifier, the conversation from the response and the message with role: "tool". We've already stored the model's call. Sending the entire history again would double the context. More on the Brain in Use the Brain: store and continue conversations per end user.

Control when a function is called

  • tool_choice: "auto" lets the model decide, "none" prohibits calls, "required" forces at least one, and {"type": "function", "function": {"name": "get_stock_level"}} forces exactly this function. The name must appear in tools.
  • parallel_tool_calls: allows or prohibits several calls in one response.

Both fields are only allowed together with tools.

Limits

  • at most 128 functions per request
  • each description at most 65,536 characters, each schema at most 65,536 bytes
  • function names consist of 1 to 64 characters: letters, digits, underscores and hyphens

Whether a model accepts functions at all is shown in GET /models under capabilities.tools and capabilities.parallel_tool_calls. If the capability is missing, you get 400 unsupported_for_model, see What a model can do: check capabilities, limits, output length and reasoning effort.

Streaming and Responses

With streaming, the calls arrive collected in a separate chunk right before the end, in choices[0].delta.tool_calls with index. On the /responses endpoint, they appear as entries of type function_call in output, and you respond with an entry of type function_call_output. There too, you send the functions themselves in the nested form shown above.

If something goes wrong

  • 400 invalid_field_value with tools and flowai_tools: The two fields are mutually exclusive. flowai_tools controls tools on our side, tools your own functions.
  • The model keeps calling the function: Check that your message with role: "tool" carries the right tool_call_id and that the second step includes the model's message with tool_calls.
  • 400 because of the name: Spaces, periods and umlauts aren't allowed in the function name.

Was this article helpful?

Back to Models, limits & errors