runApp

1 function runApp(options: any): void

The main entry point for a LiveWire application. It prints the ASCII banner, runs the prewarm function (if defined), creates a JobContext, prints a random tip, invokes the registered entry function, and starts the underlying SignalWire agent.

This mirrors cli.runApp() from @livekit/agents-js. It is also available as cli.runApp.

Parameters

options

anyRequired

The agent definition returned by defineAgent(), or an object with entry and optional prewarm functions.

Returns

void — This function runs the agent lifecycle asynchronously.

Lifecycle

Prints the LiveWire ASCII banner to stderr.
If the agent definition has a prewarm function, calls it with a fresh JobProcess instance. Logs an informational message noting that warm process pools are not needed on SignalWire.
Creates a JobContext.
Prints a random “Did you know?” tip to stderr.
Calls the entry function with the JobContext. If the entry function is async, it is awaited.
After entry completes, starts the underlying SignalWire agent if one was bound.

Example

1 import {
2   Agent, AgentSession, JobContext, tool, defineAgent, runApp,
3 } from '@signalwire/sdk/livewire';
4 
5 const getTime = tool({
6   description: 'Get the current time.',
7   execute: () => new Date().toISOString(),
8 });
9 
10 const agentDef = defineAgent({
11   entry: async (ctx: JobContext) => {
12     await ctx.connect();
13     await ctx.waitForParticipant();
14 
15     const agent = new Agent({
16       instructions: 'You are a helpful assistant that can tell the time.',
17       tools: { getTime },
18     });
19 
20     const session = new AgentSession();
21     await session.start({ agent, room: ctx.room });
22     session.generateReply({ instructions: 'Greet the user.' });
23   },
24 });
25 
26 runApp(agentDef);

defineAgent

1 function defineAgent(agent: {
2   entry: (ctx: JobContext) => Promise<void>;
3   prewarm?: (proc: JobProcess) => any;
4 }): { entry: (ctx: JobContext) => Promise<void>; prewarm?: (proc: JobProcess) => any }

Wraps an entry function (and optional prewarm function) into an agent definition object that can be passed to runApp(). This mirrors defineAgent() from @livekit/agents-js.

Parameters

entry

(ctx: JobContext) => Promise<void>Required

The main entry function for the agent. Receives a JobContext and should create an Agent, an AgentSession, and call session.start().

prewarm

(proc: JobProcess) => anyDefaults to undefined

Optional setup function called before the entry function. Receives a JobProcess whose userData object can be used to share state with the entry function.

Returns

The same object, for passing to runApp().

Example

1 import { defineAgent, runApp, JobContext, JobProcess } from '@signalwire/sdk/livewire';
2 
3 const agentDef = defineAgent({
4   prewarm: (proc: JobProcess) => {
5     proc.userData.greeting = 'Welcome to Acme Corp!';
6   },
7   entry: async (ctx: JobContext) => {
8     const greeting = ctx.proc.userData.greeting ?? 'Hello!';
9     // ... set up agent and session
10   },
11 });
12 
13 runApp(agentDef);