# 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.

```python
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
            },
        }))
```

```node
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
      },
    }));
  }
});
```

```browser
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.

- Send the `output` as a **JSON string**. If it isn't valid JSON it's wrapped as
  `{"result": "<your text>"}`.
- The `call_id` ties a result to its call — always echo back the one you received.
- Parallel calls are supported; answer each `call_id` you're given.