Bluwing/Docsv0.9.0
Operational
API ReferenceConsole

Get started

  • Introduction
  • Quickstart
  • How it works

Build

  • Tool format
  • Matching hints
  • Toolsets and builds
  • Versions and live

Call

  • Resolve a request
  • Reading responses
  • OpenAI and Anthropic compatibility

Account

  • Authentication
  • Credits and billing
  • Limits
  • Errors
  • Security and data
  • FAQ

Call

Reading responses

The three answers, every field in them, and what your code should do with each.

Bluwing returns a deterministic response object with a high-level status discriminator. Your application handles one of three well-defined cases on every turn:

01
API Response Received

Status field indicates resolution outcome

↓
02
Status: tool_calls

Array of executable functions with grounded arguments

↓
03
Status: needs_input

Clarifying question when required parameter is absent

↓
04
Status: no_tool

Fast deadband routing (<20ms) for general conversational prompts


#1. tool_calls: Ready for Execution

When one or more tools match with high confidence and all required parameters are present, status is "tool_calls".

json
{
  "id": "res_01jc8w4n6f2q7v9k3d5t",
  "status": "tool_calls",
  "tool_calls": [
    {
      "id": "call_8f2k1q",
      "name": "book_table",
      "arguments": {
        "restaurant": "Nok",
        "party_size": 4,
        "date": "2026-11-15",
        "time": "19:00"
      },
      "confidence": 0.9842,
      "side_effect": "write",
      "requires_confirmation": false,
      "grounding": {
        "restaurant": "Nok",
        "party_size": "four people",
        "date": "tomorrow",
        "time": "7pm"
      }
    }
  ],
  "needs_input": [],
  "message": null,
  "timing_us": {
    "total": 21850
  },
  "token_usage": {
    "prompt_tokens": 14,
    "completion_tokens": 42,
    "metered_input_tokens": 14
  }
}

Tool Call Fields

FieldTypeDescription
idstringUnique call identifier (e.g. call_8f2k1q).
namestringThe exact function name from your toolset schema.
argumentsobjectParsed and validated typed arguments matching your JSON Schema.
confidencenumberCalibrated model probability (0.0 to 1.0). Typical matches score > 0.85.
side_effectstring"read" (safe idempotent read), "write" (state-mutating database write), or "irreversible" (financial transfers, deletions).
requires_confirmationbooleantrue if the tool definition flags this action as needing explicit user approval before execution.
groundingobjectSubstrings from the user prompt or facts that substantiate each parameter value.

#2. needs_input: Clarifying Missing Arguments

If an ideal tool matches the user's intent, but one or more required parameters are missing from both the user prompt and facts, Bluwing will never make up a guess. Instead, it returns status: "needs_input":

json
{
  "id": "res_01jc8w5p1a3x7e2k4m9v",
  "status": "needs_input",
  "tool_calls": [],
  "needs_input": [
    {
      "parameter": "party_size",
      "question": "For how many people should I reserve the table?"
    }
  ],
  "message": "For how many people should I reserve the table?",
  "timing_us": { "total": 19400 }
}

Your frontend can directly present message to the user. When the user responds with "For 4 people", re-invoke resolve with the original context or facts.


#3. no_tool: Deadband & Conversational Prompts

When the prompt is general conversation ("Good morning", "Tell me a joke") or completely unrelated to your tools, the engine avoids false positives and answers status: "no_tool" in under 20 ms:

json
{
  "id": "res_01jc8w6z9d8c2m1v4k5t",
  "status": "no_tool",
  "tool_calls": [],
  "needs_input": [],
  "message": null,
  "timing_us": { "total": 16200 }
}

When receiving no_tool, pass the prompt to your general LLM to reply directly to the user.


#Complete TypeScript Handling Pattern

typescript
import OpenAI from "openai";
import { executeTool } from "./services/tools";
import { streamChatReply } from "./services/llm";

const openai = new OpenAI({
  baseURL: "https://api.bluwing.si/v1",
  apiKey: process.env.BLUWING_API_KEY,
});

async function handleUserTurn(userId: string, userText: string, tools: any[]) {
  const completion = await openai.chat.completions.create({
    model: "bluwing",
    messages: [{ role: "user", content: userText }],
    tools,
  });

  const choice = completion.choices[0];
  if (choice.finish_reason === "tool_calls" && choice.message.tool_calls) {
    for (const toolCall of choice.message.tool_calls) {
      const args = JSON.parse(toolCall.function.arguments);
      await executeTool(toolCall.function.name, args);
    }
    return { ok: true, executed: choice.message.tool_calls.map((c) => c.function.name) };
  } else if (choice.message.content) {
    // Missing required parameters: ask the clarifying question
    return { reply: choice.message.content };
  } else {
    // Conversational fallback
    return { stream: streamChatReply(userText) };
  }
}
PreviousResolve a requestNext OpenAI and Anthropic compatibility

Something unclear or missing? Write to [email protected] and we'll fix the page.

On this page

  • 1. tool_calls: Ready for Execution
  • 2. needs_input: Clarifying Missing Arguments
  • 3. no_tool: Deadband & Conversational Prompts
  • Complete TypeScript Handling Pattern