Skip to main content

​
Why function tools?

LLMs can generate text, but they can’t check your database, call your APIs, or perform actions in your system. Function tools bridge that gap — you tell the model what functions exist, the model decides when it wants to call one and with what arguments, but your application is the one that actually executes the function. You then pass the result back to the model so it can formulate a natural language answer. Example use cases:
  • A customer asks “Is my order #12345 shipped?” → the model decides it needs order data and requests a call to get_order_status(order_id="12345"). Your backend queries the database, gets the tracking info, and sends it back. The model then replies “Yes, your order shipped on April 10 and is arriving Thursday.”
  • A user asks “What events are happening in Amsterdam today?” → the model requests get_local_events(city="Amsterdam"). Your app calls your events API, returns the list, and the model summarizes it conversationally.
  • An internal tool asks “How many open tickets are assigned to me?” → the model requests query_tickets(assignee="user-123", status="open"). Your service runs the query and passes back the count.

​
How it works

You send a request with tool definitions describing what functions your app can run. The model may decide it needs one — when it does, the response comes back with status: "requires_action" and the function name + arguments. The model doesn’t execute anything itself. Your application runs the function (a database query, an API call, any business logic), then sends the result back in a follow-up request. The model uses that result to generate the final answer.

​
The flow

​
Step 1: Send the initial request with tools

Define your function tool and send the user’s question. 
curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "input": "What events are happening in Amsterdam today?",
    "tools": [
      {
        "type": "function",
        "name": "get_local_events",
        "description": "Get local events happening in a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "The city name" }
          },
          "required": ["city"]
        }
      }
    ]
  }'
The model decides to call the tool. The response has status: "requires_action": 
{
  "id": "resp_01KP6J8ES9KT1B7QZZSRHZH1X1",
  "object": "response",
  "status": "requires_action",
  "model": "openai/gpt-4o-mini",
  "output": [
    {
      "type": "function_call",
      "id": "fc_01KP6J8G6ASHEYR6CCFC6NG4MA",
      "call_id": "call_f6T92dh75vCxUz7b8DW9XzNl",
      "name": "get_local_events",
      "arguments": "{\"city\":\"Amsterdam\"}",
      "status": "completed"
    }
  ],
  "tools": [
    {
      "type": "function",
      "name": "get_local_events",
      "description": "Get local events happening in a city",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "The city name" }
        },
        "required": ["city"]
      }
    }
  ],
  "usage": {
    "input_tokens": 71,
    "output_tokens": 16,
    "total_tokens": 87
  }
}

​
Step 2: Execute the function

Parse arguments from the function_call output item and run your function. In this example, the model called get_local_events with {"city": "Amsterdam"}. Your application calls whatever backend or API implements get_local_events and gets a result: 
{"events": ["Kings Day Canal Parade", "Amsterdam Light Festival", "Rijksmuseum Late Night Opening"]}

​
Step 3: Send the result back

Send a follow-up request with:
  • previous_response_id set to the response ID from step 1
  • input containing a function_call_output item with the matching call_id
The function_call_output item must include an id field (any unique string) and the call_id must match the one from the function_call in step 1.
curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "previous_response_id": "resp_01KP6J8ES9KT1B7QZZSRHZH1X1",
    "input": [
      {
        "type": "function_call_output",
        "id": "fco_events_result",
        "call_id": "call_f6T92dh75vCxUz7b8DW9XzNl",
        "output": "{\"events\": [\"Kings Day Canal Parade\", \"Amsterdam Light Festival\", \"Rijksmuseum Late Night Opening\"]}"
      }
    ]
  }'
The model now has the function result in context and generates the final answer: 
{
  "id": "resp_01KP6J9T6SDQ6CG2J18EV5PYNN",
  "object": "response",
  "status": "completed",
  "model": "openai/gpt-4o-mini",
  "input": [
    {
      "type": "message",
      "id": "msg_01KP6J8ES9KT1B7QZZSXZMVKAZ",
      "role": "user",
      "content": [{ "type": "input_text", "text": "What events are happening in Amsterdam today?" }]
    },
    {
      "type": "function_call",
      "id": "fc_01KP6J8G6ASHEYR6CCFC6NG4MA",
      "call_id": "call_f6T92dh75vCxUz7b8DW9XzNl",
      "name": "get_local_events",
      "arguments": "{\"city\":\"Amsterdam\"}"
    },
    {
      "type": "function_call_output",
      "id": "fco_events_result",
      "call_id": "call_f6T92dh75vCxUz7b8DW9XzNl",
      "output": "{\"events\": [\"Kings Day Canal Parade\", \"Amsterdam Light Festival\", \"Rijksmuseum Late Night Opening\"]}"
    }
  ],
  "output": [
    {
      "type": "message",
      "id": "msg_01KP6J9WX7KKZRBQ9RDKY90ZFV",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Here are some events happening in Amsterdam today:\n\n1. **Kings Day Canal Parade** - Celebrate Kings Day with a vibrant parade along the canals.\n\n2. **Amsterdam Light Festival** - Enjoy stunning light installations throughout the city.\n\n3. **Rijksmuseum Late Night Opening** - Visit the Rijksmuseum for a late-night viewing of its art collections.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 60,
    "output_tokens": 91,
    "total_tokens": 151
  }
}

​
Multiple tool calls

If the model calls multiple tools in a single response, provide all results in one follow-up request: 
{
  "model": "openai/gpt-4o",
  "previous_response_id": "resp_...",
  "input": [
    { "type": "function_call_output", "id": "fco_1", "call_id": "call_aaa", "output": "{...}" },
    { "type": "function_call_output", "id": "fco_2", "call_id": "call_bbb", "output": "{...}" }
  ]
}

​
Multiple rounds

The model may request additional tool calls after receiving results (e.g., it needs more data). Check the response status after each continuation — if it’s still requires_action, repeat step 2 and 3. Limit the number of rounds to prevent infinite loops.

​
API reference

Create Response

Full parameter reference for POST /v3/router/responses