Agent

View as MarkdownOpen in Claude

The Agent<UserData> class mirrors a LiveKit voice agent. It holds the system prompt (instructions), a set of tools, and optional user data. When bound to an AgentSession, the session translates this into a SignalWire AgentBase under the hood.

1import { Agent, tool } from '@signalwire/sdk/livewire';
2
3const getWeather = tool({
4 description: 'Get the current weather for a city.',
5 parameters: { city: { type: 'string' } },
6 execute: (params) => {
7 return `It is sunny in ${params.city}.`;
8 },
9});
10
11const agent = new Agent({
12 instructions: 'You are a helpful weather assistant.',
13 tools: [getWeather],
14});

Constructor

1new Agent<UserData>(options?: {
2 instructions?: string;
3 tools?: FunctionTool[];
4 userData?: UserData;
5 chatCtx?: unknown;
6 stt?: unknown;
7 tts?: unknown;
8 llm?: unknown;
9 vad?: unknown;
10 turnDetection?: unknown;
11 mcpServers?: unknown;
12 allowInterruptions?: boolean;
13 minEndpointingDelay?: number;
14 maxEndpointingDelay?: number;
15})

The constructor options are source-compatible with LiveKit’s Agent constructor, including pipeline fields like stt, tts, vad, turnDetection, and mcpServers. SignalWire handles speech, TTS, and VAD on the control plane, so those fields are accepted but logged as a no-op the first time they are supplied.

instructions
stringDefaults to ""

System prompt text. Mapped to the SignalWire prompt when the session starts.

tools
FunctionTool[]Defaults to []

Array of FunctionTool objects. Stored internally as a name-keyed record; each tool is registered as a SWAIG function on the underlying agent.

userData
UserDataDefaults to undefined

Arbitrary data attached to the agent. Accessible from tool handlers via RunContext.userData.

llm
unknown

Accepted for LiveKit parity. Pipeline mapping hint — SignalWire selects the model from the SWML ai.params.

allowInterruptions
boolean

Accepted for LiveKit parity. Forwarded to the SignalWire AI params when the session starts.

minEndpointingDelay
number

Accepted for LiveKit parity. Forwarded to the SignalWire AI params when the session starts.

maxEndpointingDelay
number

Accepted for LiveKit parity. Forwarded to the SignalWire AI params when the session starts.

stt / tts / vad / turnDetection / mcpServers
unknown

Accepted for LiveKit source compatibility. SignalWire handles these capabilities on the control plane; passing a value logs a one-time “no-op” advisory and does not affect behavior.

Properties

instructions
string

The system prompt text for the agent. Can be read or modified directly.

tools
Record<string, FunctionTool>

Internal name-keyed map of registered tools.

userData
UserData | undefined

The user data attached to this agent.

session
AgentSession | undefined

The AgentSession bound to this agent, if any. Set when session.start({ agent }) is called.

Example

1import { Agent, AgentSession, tool, defineAgent, runApp, JobContext } from '@signalwire/sdk/livewire';
2
3const lookupAccount = tool({
4 description: 'Look up a customer account by email.',
5 parameters: { email: { type: 'string' } },
6 execute: (params) => {
7 return `Account found for ${params.email}: Premium tier.`;
8 },
9});
10
11const agentDef = defineAgent({
12 entry: async (ctx: JobContext) => {
13 const agent = new Agent({
14 instructions: 'You are a customer support agent. Help users with their accounts.',
15 tools: [lookupAccount],
16 userData: { department: 'support' },
17 });
18
19 const session = new AgentSession();
20 await session.start({ agent });
21 session.generateReply({ instructions: 'Greet the customer and ask how you can help.' });
22 },
23});
24
25runApp(agentDef);