GatherInfo & GatherQuestion

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.

1 from signalwire import GatherInfo, GatherQuestion

GatherInfo is typically configured through the Step.set_gather_info() and Step.add_gather_question() 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

strRequired

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

question

strRequired

The question text to present to the user.

type

strDefaults to string

JSON schema type for the answer parameter. Valid values:

"string" — free-form text
"number" — numeric value
"boolean" — yes/no
"integer" — whole number

confirm

boolDefaults to false

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

prompt

str

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

list[str]

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).

to_dict

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

Returns

dict[str, Any]

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.

output_key

str

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

completion_action

str

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

None — 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

str

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

add_question

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

Parameters

key

strRequired

Key name for storing the answer in global_data.

question

strRequired

The question text to ask.

**kwargs

Any

Optional fields passed to GatherQuestion: type, confirm, prompt, functions.

Returns

GatherInfo — self, for method chaining.

to_dict

Convert the gather configuration to a dictionary for SWML generation. Raises ValueError if no questions have been added.

Returns

dict[str, Any]

Example

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

1 from signalwire import AgentBase
2 
3 class IntakeAgent(AgentBase):
4     def __init__(self):
5         super().__init__(name="intake-agent", route="/intake")
6 
7         contexts = self.define_contexts()
8         ctx = contexts.add_context("default")
9 
10         intake = ctx.add_step("intake")
11         intake.set_text("Collect the caller's information.")
12         intake.set_gather_info(
13             output_key="caller_info",
14             completion_action="next_step",
15             prompt="You are a friendly receptionist collecting basic info."
16         )
17         intake.add_gather_question("name", "What is your full name?", confirm=True)
18         intake.add_gather_question("phone", "What is your callback number?", type="string")
19         intake.add_gather_question("reason", "What is the reason for your call?")
20 
21         process = ctx.add_step("process")
22         process.set_text("Thank the caller and summarize what was collected.")

You can also use GatherInfo directly:

1 from signalwire import GatherInfo, GatherQuestion
2 
3 gather = GatherInfo(output_key="patient_info", completion_action="next_step")
4 gather.add_question("dob", "What is your date of birth?", type="string", confirm=True)
5 gather.add_question("allergies", "Do you have any allergies?")