defineContexts | SignalWire

Define contexts and steps for multi-step conversation workflows. Contexts allow an agent to guide the caller through a structured sequence of interactions — such as gathering information, verifying identity, and then performing an action.

Returns a ContextBuilder for fluent context definition. If an existing ContextBuilder instance is passed, it is used directly. Otherwise a new empty ContextBuilder is created and returned.

Contexts can coexist with traditional prompts. The only restriction is that POM sections and raw text cannot be mixed in the main prompt.

Parameters

contexts

ContextBuilder | Record<string, unknown> | undefined

An existing ContextBuilder instance to use directly. If omitted or a plain object is passed, a new empty ContextBuilder is created instead.

Returns

ContextBuilder — The active ContextBuilder for further configuration.

Examples

Fluent ContextBuilder

1 import { AgentBase } from '@signalwire/sdk';
2 
3 const agent = new AgentBase({ name: 'intake', route: '/intake' });
4 const ctx = agent.defineContexts().addContext('default');
5 
6 ctx.addStep('greeting')
7   .setText('Greet the caller and ask for their name.')
8   .setStepCriteria('The caller has provided their name.')
9   .setFunctions(['lookup_account'])
10   .setValidSteps(['verify']);
11 
12 ctx.addStep('verify')
13   .setText('Verify the caller\'s identity.')
14   .setStepCriteria('Identity verified.')
15   .setValidSteps(['assist']);
16 
17 ctx.addStep('assist')
18   .setText('Help the caller with their request.')
19   .setFunctions(['search_orders', 'process_return']);
20 
21 await agent.serve();

addStep() is a method on Context, not on Step. Since Step methods like setValidSteps() return the Step (not the parent Context), you must keep a reference to the Context and call addStep() on it for each new step.

Using an existing ContextBuilder

1 import { AgentBase, ContextBuilder } from '@signalwire/sdk';
2 
3 const builder = new ContextBuilder();
4 const ctx = builder.addContext('default');
5 ctx.addStep('greeting').setText('Greet the caller.');
6 ctx.addStep('verify').setText('Verify identity.');
7 
8 const agent = new AgentBase({ name: 'intake', route: '/intake' });
9 agent.defineContexts(builder);
10 await agent.serve();