Dev48
Language
  • About
  • Services
  • Industries
  • Technologies
  • Articles
  • Contacts
Book a call
    Home/Articles/Write server side tools for a signalwire ai agent
Dev48
info@dev48.org+375 29 320-40-96WhatsApp@isky_by

© 2026 · All rights reserved.

Write Server-Side Tools for a SignalWire AI Agent

Source: Signalwire•November 19, 2026 at 10:53 PM

Write Server-Side Tools for a SignalWire AI Agent

Tools the AI calls, with the wording kept in code

Article

Nov 19, 2026

read

Tools the AI calls, with the wording kept in code

Adam Kalsey

EVP, Product

Build it free.

Create a space and ship your first call flow in minutes.

Voice AI

AI Agents

Developer Tutorials

This is part 3 of a series about a jack-o'-lantern I built to talk with trick-or-treaters, and the build starts in part 1. In part 2 the pumpkin got a personality and three modes. In this part it gets tools, which are functions on my server that the model calls in the middle of a conversation. They give the model fresh material for the four-hundredth visitor of the night. They also hold the wording that has to be right, so that wording comes from code rather than from the model's best guess.

Write a tool

A tool is a method on the agent marked with the @AgentBase.tool decorator. The decorator gives it a name, a description, and a JSON schema for its parameters. When the model calls the tool, SignalWire posts the request to my server, our Python SDK runs the method, and the method returns a FunctionResult.

The pumpkin calls consult_memory when someone asks about its past:

The model reads the description to decide when to call the tool, which makes the description prompt text. It says in plain words when to call and sends the nearest wrong case to another tool. The enum limits topic to the topics the server has material for. The result is prompt text as well, since it carries the fragment along with instructions for how to use it.

Draw lines from a pool, without repeats

The pumpkin's backstory is a dictionary of topics, and each topic has a handful of fragments that contradict each other on purpose:

Asked its age twice, the pumpkin gives two different answers, which suits the character, but giving one group the same answer twice wouldn't. So pick_unused keeps a list in global_data of the fragments this visit has used, and it draws from the rest:

Every tool request we send carries the call's global_data, so the handler reads the visit's state from it and returns the update with its result. When the next group arrives, the server resets used_fragments, and the whole pool is available again.

Tell stories one beat at a time

The pumpkin never says "I don't know." When a visitor asks something it can't answer, it tells a story that starts on the question and wanders off. tell_a_story builds each story from three absurd turns drawn at random:

Each call returns only the next beat, and the story's place lives in global_data.story. A visitor who says "and then what?" gets the next turn, and one who changes the subject leaves the story behind.

Once the pumpkin should be sending a group on, the tool refuses, because a story is the surest way to keep them standing there.

Return exact wording for boundaries

Some requests need the same answer every time. A visitor asks to touch the pumpkin, wants a photo, swears, shares their address, or says "you're an AI." decline_to_answer takes the kind of request and returns the guidance for it from a table:

The model recognizes the moment and picks the category, and the response lives in code, where I can review it and test it.

Give each mode its own copy of a tool

Some tools need different wording in gentle mode: a cozy story rather than a grand one, and a warm refusal rather than a cold one. I register a gentle copy of each of those tools and list only the copies in gentle mode's step.

Each copy reuses the original's description, parameters, and settings, with a handler fixed to the gentle wording:

Gentle mode's step doesn't list the originals, so the model in gentle mode has no way to reach the act's wording.

Test a tool without a call

swaig-test runs a tool the way SignalWire would, with the arguments you give it and any global_data you want the request to carry:

The second command never returns the Tuesday fragment, however many times you run it. --list-tools shows every registered tool, and the gentle copies are in that list.

Traps to avoid

Don't have one tool read a mode flag to choose its wording. A flag in global_data can drift from the mode the agent is really in, and a tool request doesn't say which context it came from. Register a separate copy for each mode and list it only in that mode's steps, so the context decides.

Don't hand the model a multi-step plan to pace itself. Given all three turns of a story at once, a model tends to tell them in one breath or lose its place. Return one step per call and keep the place on the server.

Next

The pumpkin can talk and has plenty to say, but it can't see who it's talking to. In part 4 it gets eyes, and checks the camera before any decision that matters.

The series

  • The system and the call.

The system and the call.

  • The agent: a personality and three modes, as contexts and steps.

The agent: a personality and three modes, as contexts and steps.

  • Tools: what the AI calls on my server, and why its material lives in code (this post).

Tools: what the AI calls on my server, and why its material lives in code (this post).

  • Vision: letting the agent see, and checking the camera before any decision that matters.

Vision: letting the agent see, and checking the camera before any decision that matters.

  • The stage: detecting who is standing in front of the pumpkin, in the browser.

The stage: detecting who is standing in front of the pumpkin, in the browser.

  • The voice: audio effects in the browser.

The voice: audio effects in the browser.

  • Pacing and state: the server keeps score.

Pacing and state: the server keeps score.

  • The operator: a person with a phone who can overrule the agent.

The operator: a person with a phone who can overrule the agent.

  • Testing it, and running it for a whole night.

Testing it, and running it for a whole night.

← All articles

What this article says

More in Telecom & Networks

All →
Nokia powers CMC Networks’ EMEA-R corridor, connecting key hubs across Europe, the Middle East and Africa
Nokia

Nokia powers CMC Networks’ EMEA-R corridor, connecting key hubs across Europe, the Middle East and Africa

Elon Musk says SpaceX has a plan to eliminate cell phone dead zonesПресса
SpaceX

Elon Musk says SpaceX has a plan to eliminate cell phone dead zones

Extending Twilio Verify Beyond Carrier Channels: Passkeys, TOTP, and Push Without the Plumbing
Twilio

Extending Twilio Verify Beyond Carrier Channels: Passkeys, TOTP, and Push Without the Plumbing

The absolute best time to send email campaigns in 2026
Twilio

The absolute best time to send email campaigns in 2026

Bring LiveKit agents into Zoom, Google Meet, and Microsoft Teams with Recall.ai
LiveKit

Bring LiveKit agents into Zoom, Google Meet, and Microsoft Teams with Recall.ai

Trump bought Nvidia, Palantir, SpaceX in September as federal deals, White House ties grewПресса
SpaceX

Trump bought Nvidia, Palantir, SpaceX in September as federal deals, White House ties grew

More from Signalwire

Give a Voice AI Agent a Personality and Modes
Signalwire

Give a Voice AI Agent a Personality and Modes

Prompt Injection on the Phone: How to Secure Voice AI Agents
Signalwire

Prompt Injection on the Phone: How to Secure Voice AI Agents

Build a Talking Jack-o'-Lantern with a SignalWire AI Agent
Signalwire

Build a Talking Jack-o'-Lantern with a SignalWire AI Agent

Voice AI Is Growing Up
Signalwire

Voice AI Is Growing Up

What Your AI Agent Should Never Hear: Card Numbers and CVVs
Signalwire

What Your AI Agent Should Never Hear: Card Numbers and CVVs

Build a Voice AI Agent That Follows Code, Not Prompts
Signalwire

Build a Voice AI Agent That Follows Code, Not Prompts