Why swaramFeatures DocsSign in
View as .md

Function calling

Give swaram actions to take — look up an order, check the weather, save a note. You list your tools when you configure the session; the model decides when one is needed and asks for it; your app runs it and sends the result back; then swaram speaks the answer in Malayalam. It works the same in both modes.

1. Declare your tools

Add a tools array to your opening session.update. Each tool is a function with a name, a description, and a JSON-Schema for its arguments.

JSON
{
  "type": "session.update",
  "session": {
    "instructions": "You are a helpful shop assistant. Speak Malayalam.",
    "voice": "mal-female",
    "tools": [
      {
        "type": "function",
        "name": "get_order_status",
        "description": "Look up an order by its id.",
        "parameters": {
          "type": "object",
          "properties": { "order_id": { "type": "string" } },
          "required": ["order_id"]
        }
      }
    ],
    "tool_choice": "auto"
  }
}

2. Handle the call

When the model wants a tool, you receive a response.function_call_arguments.done event with the name, a call_id, and the arguments (a JSON string). Run the function, then send the result back as a conversation.item.create of type function_call_output — keyed by the same call_id. swaram continues and speaks the answer.

async for raw in ws:
    event = json.loads(raw)
    if event["type"] == "response.function_call_arguments.done":
        args = json.loads(event["arguments"])
        result = lookup_order(args["order_id"])          # your code
        await ws.send(json.dumps({
            "type": "conversation.item.create",
            "item": {
                "type": "function_call_output",
                "call_id": event["call_id"],
                "output": json.dumps(result),            # a JSON string
            },
        }))

ws.on("message", (data) => {
  const event = JSON.parse(data);
  if (event.type === "response.function_call_arguments.done") {
    const args = JSON.parse(event.arguments);
    const result = lookupOrder(args.order_id);            // your code
    ws.send(JSON.stringify({
      type: "conversation.item.create",
      item: {
        type: "function_call_output",
        call_id: event.call_id,
        output: JSON.stringify(result),                   // a JSON string
      },
    }));
  }
});

ws.onmessage = (e) => {
  const event = JSON.parse(e.data);
  if (event.type === "response.function_call_arguments.done") {
    const args = JSON.parse(event.arguments);
    const result = lookupOrder(args.order_id);            // your code
    ws.send(JSON.stringify({
      type: "conversation.item.create",
      item: {
        type: "function_call_output",
        call_id: event.call_id,
        output: JSON.stringify(result),                   // a JSON string
      },
    }));
  }
};

Choosing when tools run

tool_choice controls whether the model may call a tool:

tool_choice Behaviour
auto The model decides (default).
none Never call a tool — just speak.
required The model must call a tool.

Tips

Keep tools fast. A tool call adds a short pause before swaram replies. Keep the work quick, and confirm before anything important. You can set your instructions so swaram says a brief Malayalam filler while it waits.

← All docs