USING TOOLS

Using 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:

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.

Option A: Create a Pre-defined WebSocket Tool

Create pre-defined WebSocket tools when the same tool should be reused across agents or conversations:

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.