Function calling

This guide uses the Perceptron Python SDK with Perceptron’s public API. The model selects a function and generates its arguments; your Python code runs it and returns the result.

Run a complete example

Install the client and set PERCEPTRON_API_KEY to your API key:

pip install "perceptron>=0.4.0"
export PERCEPTRON_API_KEY="your-api-key"

Save the following as inventory.py and run python inventory.py. The inventory is a local example dataset, so only the model request needs network access. Replace lookup_inventory with your own database or service once the loop is working.

import json

from perceptron import Client, function_tool


client = Client(timeout=60.0)

INVENTORY = {
    "BALL-RED": {"name": "Red ball", "quantity": 12},
    "BALL-BLUE": {"name": "Blue ball", "quantity": 0},
}

TOOLS = [function_tool(
    "lookup_inventory",
    description="Look up the current stock for one product SKU.",
    parameters={
        "type": "object",
        "properties": {
            "sku": {"type": "string", "description": "The exact product SKU."},
        },
        "required": ["sku"],
        "additionalProperties": False,
    },
)]


def execute_tool(name, arguments):
    try:
        if name != "lookup_inventory":
            raise ValueError("Unknown tool. Use lookup_inventory.")
        args = json.loads(arguments)
        if not isinstance(args, dict) or set(args) != {"sku"}:
            raise ValueError("Arguments must contain only sku.")
        if not isinstance(args["sku"], str):
            raise ValueError("sku must be a string.")
        item = INVENTORY.get(args["sku"])
        return json.dumps({"sku": args["sku"], "found": item is not None, "item": item})
    except (TypeError, ValueError) as error:
        return json.dumps({"error": str(error)})


def complete_turn(messages, tool_choice="auto"):
    response = client.chat.completions.create(
        model="perceptron-mk1.5",
        messages=messages,
        tools=TOOLS,
        tool_choice=tool_choice,
        parallel_tool_calls=True,
        reasoning_effort="high",
        max_completion_tokens=2048,
    )
    choice = response.choices[0]
    message = choice.message.to_dict()
    return message, choice.finish_reason, response.usage


def run():
    messages = [{
        "role": "user",
        "content": (
            "Use inventory lookup to compare BALL-RED and BALL-BLUE. "
            "Which is in stock, and how many are available?"
        ),
    }]
    calls_used = 0
    for _ in range(4):
        message, finish_reason, usage = complete_turn(messages)
        if usage is not None:
            print(f"Tokens this request: {usage.total_tokens}")

        calls = message.get("tool_calls") or []
        if finish_reason == "stop" and not calls:
            messages.append(message)
            return messages
        if finish_reason != "tool_calls" or not calls:
            raise RuntimeError(f"Incomplete response: {finish_reason}")
        if calls_used + len(calls) > 6:
            raise RuntimeError("Tool call budget exhausted.")

        messages.append(message)
        for call in calls:
            function = call["function"]
            result = execute_tool(function["name"], function["arguments"])
            messages.append({
                "role": "tool",
                "tool_call_id": call["id"],
                "content": result,
            })
        calls_used += len(calls)

    raise RuntimeError("Model round budget exhausted.")


if __name__ == "__main__":
    history = run()
    print(history[-1].get("content") or "")

The example allows at most four model requests and six tool executions. It executes calls sequentially for clarity, even when the model requests them in the same turn. A successful answer should report 12 red balls and no blue balls in this example inventory; the wording and number of calls can vary. run() returns the completed conversation, including the final assistant answer, so another request can reuse the tool results.

Preserve the conversation

Append the whole assistant message before its tool results. The SDK accepts the returned response.message directly in messages; use its to_dict() method when storing history as dictionaries, as in the example. Both retain content, tool_calls, and any returned reasoning_content. The model’s next input does not necessarily include every saved field. Historical reasoning_content is forwarded when the request includes function tools or tool-call/result history; it is ignored on ordinary requests without either. When an assistant message contains tool calls, its accompanying prose in content is omitted from the next model input. Keep the full message for the tool round trip, and put information needed for subsequent reasoning in the user messages or tool results. Each call needs one result with the matching tool_call_id before you continue. Results may be supplied in a different order from the calls. Keep function.arguments as the returned string in assistant history, even after parsing it for execution. Continue sending the same function declarations on subsequent requests, including when you want a final answer. For a constrained JSON or regex answer, complete the tool loop first, then omit the tool declarations and options from that separate request. Assistant text and tool arguments can be absent or empty while a response is streaming.

Stream a tool call

Replace complete_turn in the example with this version. The execution loop stays the same. The SDK assembles calls by index and accumulates argument fragments. The example waits for the complete stream and checks the result before returning anything that can be executed.

def complete_turn(messages, tool_choice="auto"):
    with client.chat.completions.create(
        model="perceptron-mk1.5",
        messages=messages,
        tools=TOOLS,
        tool_choice=tool_choice,
        parallel_tool_calls=True,
        reasoning_effort="high",
        max_completion_tokens=2048,
        stream=True,
        stream_options={"include_usage": True},
    ) as stream:
        for chunk in stream:
            for choice in chunk.choices:
                print(choice.delta.content or "", end="", flush=True)
        response = stream.get_final_completion()

    if not response.complete or response.finish_reason not in {"stop", "tool_calls"}:
        raise RuntimeError(f"Incomplete stream: {response.finish_reason}")
    calls = response.tool_calls or []
    ids = [call.id for call in calls]
    if calls and (not all(ids) or len(set(ids)) != len(ids)):
        raise RuntimeError("Missing or duplicate tool call IDs.")
    return response.message.to_dict(), response.finish_reason, response.usage

The SDK requests usage by default for Perceptron streams; the example sets stream_options.include_usage: true explicitly. Usage can arrive in a separate trailing chunk with choices: []. get_final_completion() consumes any remaining chunks and returns the assembled message and usage. If you read chunks yourself, consume usage independently of choice deltas and keep reading after a finish reason. finish_reason: "tool_calls" means a model turn is complete and ready for your application to handle. "stop" is a completed answer. Treat "length", a missing finish reason, or an API error as an incomplete turn; do not execute accumulated arguments. The SDK raises an SDKError subclass for API or transport failures, and IncompleteStreamError when the stream ends without [DONE]. Its error may carry a .partial completion for diagnostics; do not execute those partial calls. A raw SSE client must also handle {"error": ...} events, which end the stream without [DONE].

Supported controls

The API behaviors below apply when the request declares non-empty tools. The SDK validates controls before sending a request: unsupported tool_choice values and incompatible tool/output combinations raise BadRequestError locally. At the HTTP API layer, validly shaped tool_choice and parallel_tool_calls values are ignored when tools is omitted or empty.

Control	Behavior
`tool_choice: "auto"`	Default. The model chooses whether to call a function.
`tool_choice: "none"`	Best effort request for an answer without calls. Your application must still handle returned calls.
`tool_choice: "required"` or a named function	Unsupported; the SDK raises `BadRequestError`. Direct API requests with non-empty `tools` receive HTTP 400.
`parallel_tool_calls`	Defaults to `true`. Always accept an array of calls, including when set to `false`; prior parallel history can preserve this behavior.
Function `strict: true`	Accepted, but argument-schema enforcement is not implemented. Validate arguments yourself.
`n`	Chat completions supports `1`. Several tool calls can still appear within that one completion.
JSON-schema `response_format` or `regex` with tools	Unsupported in the same request.
Multilook	Does not support tool declarations, tool calls, or tool-result history. Use chat completions.

For a machine-readable final report, finish the tool workflow and make a separate structured-output request without tool declarations. Completed tool history can remain in the conversation. For execution budgets, image results, and retrieval patterns, continue to Building a tool agent.

Get Started

Capabilities

Developer Guides

Scaling & deployment

Best practices

Run a complete example

Preserve the conversation

Stream a tool call

Supported controls

​Run a complete example

​Preserve the conversation

​Stream a tool call

​Supported controls

Run a complete example

Preserve the conversation

Stream a tool call

Supported controls