Signals

LiveWire provides error and signal classes that tool handlers can throw or return to control agent behavior.

StopResponse

Extends Error. When thrown inside a tool handler, signals that the tool should not trigger another LLM reply. Use this when the tool’s side effect is the final action and no further conversation is needed.

import { tool, StopResponse } from '@signalwire/sdk/livewire';
const endCall = tool({
  description: 'End the current call.',
  parameters: { reason: { type: 'string' } },
  execute: (params) => {
    // Perform cleanup...
    throw new StopResponse(`Call ended: ${params.reason}`);
  },
});

Constructor

new StopResponse(message?: string)

message

stringDefaults to "StopResponse"

Optional error message. Defaults to "StopResponse".

ToolError

Extends Error. Signals a tool execution failure. Throw this when a tool encounters a problem that should be reported back to the LLM so it can communicate the issue to the user or retry.

import { tool, ToolError } from '@signalwire/sdk/livewire';
const transferFunds = tool<{ amount: number; toAccount: string }>({
  description: 'Transfer funds to another account.',
  parameters: {
    amount: { type: 'number' },
    toAccount: { type: 'string' },
  },
  execute: (params) => {
    if (params.amount <= 0) {
      throw new ToolError('Amount must be positive.');
    }
    return `Transferred $${params.amount} to ${params.toAccount}.`;
  },
});

Constructor

new ToolError(message: string)

message

stringRequired

Error message describing what went wrong. This is sent back to the LLM.

AgentHandoff

A signal class for handing off a conversation to a different agent in multi-agent scenarios. Created via the handoff() helper function.

import { Agent, handoff, tool } from '@signalwire/sdk/livewire';
const billingAgent = new Agent({
  instructions: 'You handle billing questions.',
});
const transferToBilling = handoff({
  agent: billingAgent,
  returns: 'Transferred to billing department.',
});

Properties

agent

Agent

The target Agent for the handoff.

returns

string | undefined

Optional return message for the handoff.

handoff()

function handoff(options: { agent: Agent; returns?: string }): AgentHandoff

Factory function that creates an AgentHandoff instance.

agent

AgentRequired

The target agent to hand off to.

returns

string | undefined

Optional return value for the handoff.

ChatContext

A minimal class mirroring the LiveKit ChatContext. Stores an in-memory list of chat messages. On SignalWire, the platform manages conversation history for the active call — this class exists so that existing livekit-agents code that references ChatContext compiles without errors, and so callers can stage messages in prewarm code.

import { llm } from '@signalwire/sdk/livewire';
const chat = new llm.ChatContext();
chat.append({ role: 'system', text: 'You are a helpful agent.' });

Properties

messages

Array<Record<string, string>>

Appended chat messages. Each entry is stored as { role, content }.

append

append(options: { role?: string; text?: string }): this

Append a message to messages. The stored entry uses content (not text) as the body key — text is renamed to match the on-wire message shape.

role

stringDefaults to "user"

The message role ("user", "assistant", "system", etc.).

text

stringDefaults to ""

The message content.