USING TOOLS

WebSocket Tools

This guide shows how to extend a basic WebSocket conversation to work with WebSocket tools.

While this guide runs through creating and using a sync WebSocket tool, the core workflow remains the same with async WebSocket tools.

Full working examples in both Node and Python are available in the Phonic examples repository.

Prerequisites

Before adding tools to your WebSocket conversation, you should have:

Tool Call Messages

When the agent makes a tool call, Phonic sends this message over the WebSocket:

1{
2  "type": "tool_call",
3  "tool_call_id": "string",
4  "tool_name": "string",
5  "parameters": {
6    // Map from parameter names to values
7  }
8}

Respond with a tool_call_output message:

1{
2  type: "tool_call_output";
3  tool_call_id: string; // The ID from the tool_call message
4  output: unknown; // The result, can be any JSON-serializable object
5}

WebSocket tools expose an Output timeout (tool_call_output_timeout_ms) — the maximum time to wait for the tool_call_output message. Default 5000 ms, between 1000 and 180000 ms.

The WebSocket tool call output may be any JSON-serializable value, but is truncated if its JSON serialized representation exceeds 16,000 characters.

Adding Tool Support

To handle tool calls in your existing WebSocket server, you need to:

  1. Listen for tool_call messages from Phonic
  2. Process the tool call with your business logic
  3. Send back a tool_call_output message with the result

Step 1: Choose How to Provide Tools

You can provide WebSocket tools in two ways:

  • Pre-defined WebSocket tools: create the tool once with the Tools API or Phonic UI, then reference it by name from an agent or conversation config. Use pre-defined WebSocket tools to avoid having to define the same tool across agents or conversations.
  • Inline WebSocket tools: define the tool inline in the WebSocket config message. Inline WebSocket tools are not persisted to your workspace. Use inline WebSocket tools when the parameters for the tool may change between conversations.

Inline tools are defined when you make the tool available (see Step 2). For a pre-defined tool, create it first with the Tools API or in the dashboard:

1import { PhonicClient } from "phonic";
2
3const phonic = new PhonicClient({ apiKey: process.env.PHONIC_API_KEY });
4
5await phonic.tools.create({
6  name: "get_temperature",
7  description: "Get the current temperature for a specific city",
8  type: "custom_websocket",
9  execution_mode: "sync",
10  parameters: [
11    {
12      type: "string",
13      name: "city",
14      description: "The city to get the temperature for",
15      is_required: true,
16    },
17  ],
18});

Step 2: Make the Tool Available

Pre-defined Tools

Add pre-defined tools to your agent’s configuration by name:

1await phonic.agents.create({
2  name: "weather-assistant",
3  tools: ["get_temperature"],  // Add your tool here
4  // ... other agent configuration
5});

Inline WebSocket Tools

For inline WebSocket tools, pass the tool definition inline when you start the WebSocket conversation. The tool_schema follows OpenAI’s function tool shape.

Inline tools currently support type: "custom_websocket" only.

1await phonicSocket.sendConfig({
2  type: "config",
3  agent: "weather-assistant",
4  tools: [
5    {
6      type: "custom_websocket",
7      tool_schema: {
8        type: "function",
9        function: {
10          name: "get_temperature",
11          description: "Get the current temperature for a specific city",
12          parameters: {
13            type: "object",
14            properties: {
15              city: {
16                type: "string",
17                description: "The city to get the temperature for",
18              },
19            },
20            required: ["city"],
21            additionalProperties: false,
22          },
23          strict: true,
24        },
25      },
26      execution_mode: "sync",
27      tool_call_output_timeout_ms: 5000,
28    },
29  ],
30});

Step 3: Handle Tool Calls in Your WebSocket Server

Modify your existing WebSocket message handler to process tool_call messages:

1// Add to your existing phonicSocket message handler
2phonicSocket.on("message", async (message) => {
3  // Your existing handlers for audio_chunk, etc...
4  
5  // Add: Handle tool calls
6  if (message.type === "tool_call") {
7    switch (message.tool_name) {
8      case "get_temperature": {
9        const { city } = message.parameters;
10        
11        // Your implementation
12        const temperature = await getTemperature(city);
13        
14        // Send result back to Phonic
15        await phonicSocket.sendToolCallOutput({
16          type: "tool_call_output",
17          tool_call_id: message.tool_call_id,
18          output: {
19            city: city,
20            temperature: "75°F"
21          },
22        });
23        break;
24      }
25    }
26  }
27});
See the complete examples in our examples repository.