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.

Called with no argument, it returns the agent’s ContextBuilder, creating it on first use, so calling it again adds to the same workflow. Passing a ContextBuilder replaces the current one and returns it. Passing a plain object uses that object as the contexts, rendered as it is, and returns the agent.

The contexts render inside the AI prompt, as ai.prompt.contexts.

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

A ContextBuilder to use in place of the current one, or the contexts as a plain object. Omit it to get the current builder. Throws a TypeError for a value that is neither.

Returns

ContextBuilder — The active ContextBuilder for further configuration, or AgentBase (this) when given a plain object.

Examples

Fluent ContextBuilder

import { AgentBase } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'intake', route: '/intake' });
const ctx = agent.defineContexts().addContext('default');
ctx.addStep('greeting')
  .setText('Greet the caller and ask for their name.')
  .setStepCriteria('The caller has provided their name.')
  .setFunctions(['lookup_account'])
  .setValidSteps(['verify']);
ctx.addStep('verify')
  .setText('Verify the caller\'s identity.')
  .setStepCriteria('Identity verified.')
  .setValidSteps(['assist']);
ctx.addStep('assist')
  .setText('Help the caller with their request.')
  .setFunctions(['search_orders', 'process_return']);
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

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