AgentsContextBuilder

GatherInfo & GatherQuestion

View as MarkdownOpen in Claude

GatherInfo and GatherQuestion provide structured information gathering within context steps. Instead of relying on LLM tool calls, the gather system uses dynamic step instruction re-injection to present questions one at a time, producing zero tool_call/tool_result entries in the LLM-visible history.

Answers are stored in global_data and can be referenced by subsequent steps or tools.

1import { ContextBuilder } from '@signalwire/sdk';

GatherInfo is typically configured through the Step.setGatherInfo() and Step.addGatherQuestion() methods rather than instantiated directly.

GatherQuestion

Represents a single question in a gather_info configuration. Each question defines a key for storing the answer, the question text, and optional validation and confirmation settings.

key
stringRequired

Key name for storing the answer in global_data. Must be unique within a single GatherInfo configuration.

question
stringRequired

The question text to present to the user.

type
stringDefaults to string

Expected answer type. Valid values:

  • "string" — free-form text
  • "number" — numeric value
  • "boolean" — yes/no
  • "integer" — whole number
confirm
booleanDefaults to false

When true, the model must confirm the answer with the user before submitting it.

prompt
string

Extra instruction text appended to the step prompt when this specific question is active. Use this to give the model additional context for asking or validating this question.

functions
string[]

Additional SWAIG function names to make visible while this question is active. Useful when a question requires tool access (e.g., a lookup function to validate an account number).

toDict

Convert the question to a dictionary for SWML generation. Fields with default values are omitted from the output.

Returns

Record<string, unknown>

GatherInfo

Configuration for gathering multiple pieces of information in a step. Wraps a list of GatherQuestion objects and controls how answers are stored and what happens after all questions are answered.

outputKey
string

Key in global_data under which to nest all answers. When undefined, answers are stored at the top level of global_data using each question’s key.

completionAction
string

Where to navigate after all questions have been answered. Valid values:

  • undefined — return to normal step mode
  • "next_step" — auto-advance to the next sequential step in the context
  • A step name (e.g., "process_results") — jump to that specific step
prompt
string

Preamble text injected once when entering the gather step. Gives the model personality and context for why it is asking these questions.

addQuestion

Add a question to the gather configuration. Returns this for method chaining.

Parameters

opts.key
stringRequired

Key name for storing the answer in global_data.

opts.question
stringRequired

The question text to ask.

opts.type
stringDefaults to string

Answer type: "string", "number", "boolean", "integer".

opts.confirm
booleanDefaults to false

Whether to confirm the answer with the user.

opts.prompt
string

Extra instruction text for this question.

opts.functions
string[]

SWAIG function names available during this question.

Returns

GatherInfo — self, for method chaining.

toDict

Convert the gather configuration to a dictionary for SWML generation. Throws an error if no questions have been added.

Returns

Record<string, unknown>

Example

The typical pattern is to use GatherInfo through the Step API:

1import { ContextBuilder } from '@signalwire/sdk';
2
3const builder = new ContextBuilder();
4const ctx = builder.addContext('default');
5
6// Configure gather info on a step
7ctx.addStep('intake')
8  .setText('Collect the caller\'s information.')
9  .setGatherInfo({
10    outputKey: 'caller_info',
11    completionAction: 'next_step',
12    prompt: 'You are a friendly receptionist collecting basic info.',
13  })
14  .addGatherQuestion({ key: 'name', question: 'What is your full name?', confirm: true })
15  .addGatherQuestion({ key: 'phone', question: 'What is your callback number?', type: 'string' })
16  .addGatherQuestion({ key: 'reason', question: 'What is the reason for your call?' });
17
18ctx.addStep('process')
19  .setText('Thank the caller and summarize what was collected.');

You can also use GatherInfo directly:

1import { GatherInfo } from '@signalwire/sdk';
2
3const gather = new GatherInfo({ outputKey: 'patient_info', completionAction: 'next_step' });
4gather.addQuestion({ key: 'dob', question: 'What is your date of birth?', type: 'string', confirm: true });
5gather.addQuestion({ key: 'allergies', question: 'Do you have any allergies?' });