Skip to navigation
AgentsLiveWire

Signals

View as MarkdownOpen in Claude

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.