git diff

to see what changed

git revert

to roll back

pytest

to verify each step

git log

to audit every change

The Problem

Prompt Blobs Are Not Software

You Cannot Unit Test a Prompt

A 2,000-word prompt blob has no defined interface, no isolation boundary, and no deterministic behavior. Every deployment is a bet.

Diffing Prose Tells You Nothing

Someone changed the prompt. The diff shows 47 lines of modified prose. What behavior changed? Nobody knows until a caller reports it.

Rollback Means Finding an Old Prompt

The agent broke after the last update. The old version is somewhere in a dashboard, a Slack message, or a Google Doc. Good luck.

Auditing Means Guessing

A regulated industry auditor asks: which instructions were active during this call? With a monolithic prompt, the answer is all of them. Or none. Depends on the model's mood.

Build a Voice AI Agent

from signalwire_agents import AgentBase
from signalwire_agents.core.function_result import SwaigFunctionResult

class SupportAgent(AgentBase):
    def __init__(self):
        super().__init__(name="Support Agent", route="/support")
        self.prompt_add_section("Instructions",
            body="You are a customer support agent. "
                 "Greet the caller and resolve their issue.")
        self.add_language("English", "en-US", "rime.spore:mistv2")

    @AgentBase.tool(name="check_order")
    def check_order(self, order_id: str):
        """Check the status of a customer order.

        Args:
            order_id: The order ID to look up
        """
        return SwaigFunctionResult(f"Order {order_id}: shipped, ETA April 2nd")

agent = SupportAgent()
agent.run()

import { AgentBase, FunctionResult } from '@signalwire/sdk';

const agent = new AgentBase({
  name: 'Support Agent',
  route: '/support',
});

agent.promptAddSection('Instructions',
  'You are a customer support agent. Greet the caller and resolve their issue.');

agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.spore:mistv2' });

agent.defineTool({
  name: 'check_order',
  description: 'Check the status of a customer order',
  parameters: {
    type: 'object',
    properties: {
      order_id: { type: 'string', description: 'The order ID to look up' },
    },
    required: ['order_id'],
  },
  handler: (args) => {
    return new FunctionResult(`Order ${args.order_id}: shipped, ETA April 2nd`);
  },
});

agent.run();

package main

import (
	"fmt"

	"github.com/signalwire/signalwire-go/pkg/agent"
	"github.com/signalwire/signalwire-go/pkg/swaig"
)

func main() {
	a := agent.NewAgentBase(
		agent.WithName("Support Agent"),
		agent.WithRoute("/support"),
	)

	a.PromptAddSection("Instructions",
		"You are a customer support agent. Greet the caller and resolve their issue.")

	a.AddLanguage(map[string]any{
		"name": "English", "code": "en-US", "voice": "rime.spore:mistv2",
	})

	a.DefineTool(agent.ToolDefinition{
		Name:        "check_order",
		Description: "Check the status of a customer order",
		Parameters: map[string]any{
			"type": "object",
			"properties": map[string]any{
				"order_id": map[string]any{
					"type": "string", "description": "The order ID to look up",
				},
			},
			"required": []string{"order_id"},
		},
		Handler: func(args map[string]any, rawData map[string]any) *swaig.FunctionResult {
			orderID := args["order_id"]
			return swaig.NewFunctionResult(
				fmt.Sprintf("Order %v: shipped, ETA April 2nd", orderID),
			)
		},
	})

	a.Run()
}

import com.signalwire.sdk.agent.AgentBase;
import com.signalwire.sdk.swaig.FunctionResult;

import java.util.List;
import java.util.Map;

public class SupportAgent {
    public static void main(String[] args) throws Exception {
        var agent = AgentBase.builder()
                .name("Support Agent")
                .route("/support")
                .build();

        agent.promptAddSection("Instructions",
                "You are a customer support agent. "
              + "Greet the caller and resolve their issue.");

        agent.addLanguage("English", "en-US", "rime.spore:mistv2");

        agent.defineTool(
                "check_order",
                "Check the status of a customer order",
                Map.of("type", "object",
                       "properties", Map.of(
                           "order_id", Map.of(
                               "type", "string",
                               "description", "The order ID to look up")),
                       "required", List.of("order_id")),
                (toolArgs, rawData) -> {
                    var orderId = toolArgs.get("order_id");
                    return new FunctionResult(
                        "Order " + orderId + ": shipped, ETA April 2nd");
                }
        );

        agent.run();
    }
}

# frozen_string_literal: true

require 'signalwire'

agent = SignalWire::AgentBase.new(name: 'Support Agent', route: '/support')

agent.prompt_add_section('Instructions',
  'You are a customer support agent. Greet the caller and resolve their issue.')

agent.add_language(name: 'English', code: 'en-US', voice: 'rime.spore:mistv2')

agent.define_tool(
  name:        'check_order',
  description: 'Check the status of a customer order',
  parameters:  {
    'order_id' => { 'type' => 'string', 'description' => 'The order ID to look up' }
  }
) do |args, _raw|
  SignalWire::Swaig::FunctionResult.new(
    "Order #{args['order_id']}: shipped, ETA April 2nd"
  )
end

agent.run

<?php
require 'vendor/autoload.php';

use SignalWire\Agent\AgentBase;
use SignalWire\SWAIG\FunctionResult;

$agent = new AgentBase(['name' => 'Support Agent', 'route' => '/support']);

$agent->promptAddSection('Instructions',
    'You are a customer support agent. Greet the caller and resolve their issue.');

$agent->addLanguage('English', 'en-US', 'rime.spore:mistv2');

$agent->defineTool(
    name: 'check_order',
    description: 'Check the status of a customer order',
    parameters: [
        'order_id' => ['type' => 'string', 'description' => 'The order ID to look up'],
    ],
    handler: function (array $args): FunctionResult {
        return new FunctionResult("Order {$args['order_id']}: shipped, ETA April 2nd");
    }
);

$agent->run();

#!/usr/bin/env perl
use strict;
use warnings;
use lib 'lib';
use SignalWire::Agent::AgentBase;
use SignalWire::SWAIG::FunctionResult;

my $agent = SignalWire::Agent::AgentBase->new(
    name  => 'Support Agent',
    route => '/support',
);

$agent->prompt_add_section('Instructions',
    'You are a customer support agent. Greet the caller and resolve their issue.');

$agent->add_language(name => 'English', code => 'en-US', voice => 'rime.spore:mistv2');

$agent->define_tool(
    name        => 'check_order',
    description => 'Check the status of a customer order',
    parameters  => {
        order_id => { type => 'string', description => 'The order ID to look up' },
    },
    handler => sub {
        my ($args, $raw) = @_;
        return SignalWire::SWAIG::FunctionResult->new(
            response => "Order $args->{order_id}: shipped, ETA April 2nd"
        );
    },
);

$agent->run;

#include <signalwire/agent/agent_base.hpp>

using namespace signalwire;
using json = nlohmann::json;

class SupportAgent : public agent::AgentBase {
public:
    SupportAgent() : AgentBase("Support Agent", "/support") {
        prompt_add_section("Instructions",
            "You are a customer support agent. "
            "Greet the caller and resolve their issue.");

        add_language({"English", "en-US", "rime.spore:mistv2"});

        define_tool({
            .name = "check_order",
            .description = "Check the status of a customer order",
            .parameters = {
                {"order_id", {{"type", "string"},
                              {"description", "The order ID to look up"}}}
            },
            .handler = [](const json& args, const json&) {
                auto order_id = args.value("order_id", "unknown");
                return swaig::FunctionResult(
                    "Order " + order_id + ": shipped, ETA April 2nd");
            }
        });
    }
};

int main() {
    SupportAgent().run();
}

using SignalWire.Agent;
using SignalWire.SWAIG;

var agent = new AgentBase(new AgentOptions { Name = "Support Agent", Route = "/support" });

agent.PromptAddSection("Instructions",
    "You are a customer support agent. Greet the caller and resolve their issue.");

agent.AddLanguage("English", "en-US", "rime.spore:mistv2");

agent.DefineTool("check_order", "Check the status of a customer order",
    new { type = "object", properties = new {
        order_id = new { type = "string", description = "The order ID to look up" }
    }, required = new[] { "order_id" } },
    (args, rawData) =>
    {
        var orderId = args.TryGetValue("order_id", out var id) ? id : "unknown";
        return new FunctionResult($"Order {orderId}: shipped, ETA April 2nd");
    });

agent.Run();

Prompt and Pray vs. Testable Agents

Prompt and Pray

✗ Cannot unit test a probabilistic prompt blob
✗ Diffing 2,000 words of prose to find what changed
✗ No defined interface to regression test against
✗ Rolling back means finding an old prompt in a dashboard
✗ Auditing means guessing which instruction applied

Declarative Agents

✓ Each step is an isolated unit with defined inputs and outputs
✓ Structured diffs show exactly what changed
✓ Step contracts define expected tool calls and transitions
✓ Rollback with git revert
✓ Audit with git log; every step and transition is recorded

Capability Comparison

Capability	Prompt Blob	Declarative Agent
Version control	Blob in a dashboard	Structured artifact in git
Diff between versions	Manual prose comparison	git diff
Code review	Read a 2,000-word prompt	Review a step change
Unit testing	Not possible (probabilistic)	Step-level isolation
Integration testing	Manual QA calls	Automated conversation simulation
Regression testing	Hope nothing broke	CI/CD pipeline on every push
Rollback	Find the old prompt somewhere	git revert
Audit trail	What was the prompt on March 3rd?	git log
A/B testing	Two prompt blobs, no metrics	Two versioned configs, metrics per version

Meaningful Diffs in Pull Requests

The change is clear: a new tool was added to the authenticated step. Reviewers evaluate whether the tool belongs in this step and whether transitions still make sense.

diff

- name: authenticated
   prompt: "Help the customer with their account."
-  tools: [check_balance, update_address]
+  tools: [check_balance, update_address, schedule_service]
   transitions:
     farewell: "Issue resolved"

Ship Voice AI Like Software

1

Define your agent as config

Write agent definitions in YAML or generate them from the Python SDK. Both produce structured, versionable artifacts.

2

Write tests for each step

Test tool availability, transition rules, and conversation flows. Each step is an isolated unit with deterministic boundaries.

3

Review in pull requests

Agent changes go through code review. Structured diffs make it clear what behavior changed and why.

4

Deploy through CI/CD

Validate, test, and deploy through your existing pipeline. No manual dashboard updates. No copy-paste into a web form.

💡

Each step has explicit inputs, tools, and transitions. You are not testing whether the AI does the right thing in all scenarios. You are testing whether this step calls the right tool and transitions to the right next step. That is a tractable testing problem.

FAQ

Can I use my existing CI/CD pipeline?

Yes. Agent definitions are files in your repository. They go through the same pipeline as application code: commit, review, test, merge, deploy.

What about the probabilistic nature of LLMs?

You test the structure, not the prose. Each step has defined tools and transitions. The model handles natural language within bounded constraints that your tests verify.

How do I A/B test agent versions?

Deploy two versioned configurations. Route a percentage of calls to each version. Compare metrics per version: resolution rate, handle time, transfer rate, customer satisfaction.

What is the difference between YAML and SDK testing?

YAML agents validate schema and structure. SDK agents add Python testing tools: IDE support, debuggers, mock frameworks. Both produce testable, diffable artifacts.

Trusted by 2,000+ companies

Ship Voice AI With Confidence

Version control, CI/CD, and automated testing for every AI agent you deploy.

Get Started Free Read the Docs

Your Voice Agent Deserves a Test Suite