ContextBuilder | SignalWire

ContextBuilder is the top-level container for defining structured conversation workflows. It holds one or more Context objects, each containing a sequence of Step objects. Use it when your agent needs guided, multi-step conversations instead of free-form prompting.

Access the builder by calling define_contexts() on an AgentBase instance. The builder validates the entire context tree when the SWML document is rendered.

Properties

agent

AgentBaseRequired

The parent agent that owns these contexts. Typically called internally by AgentBase.define_contexts() rather than instantiated directly.

You rarely create a ContextBuilder directly. Call self.define_contexts() inside your agent class, which creates the builder and wires it into SWML generation automatically.

Methods

add_context

Create a new named context and add it to the builder.

get_context

Retrieve an existing context by name.

to_dict

Convert all contexts to a dictionary for SWML generation.

validate

Validate the entire context configuration tree.

create_simple_context

Helper to create a standalone Context without a ContextBuilder.

Limits

Limit	Value
Maximum contexts per builder	50
Maximum steps per context	100

Examples

Single context with sequential steps

1 from signalwire import AgentBase
2 
3 class OrderAgent(AgentBase):
4     def __init__(self):
5         super().__init__(name="order-agent")
6         self.add_language("English", "en-US", "rime.spore")
7         self.prompt_add_section("Role", "You help customers place orders.")
8 
9         contexts = self.define_contexts()
10 
11         order = contexts.add_context("default")
12 
13         order.add_step("get_item") \
14             .set_text("Ask what item they want to order.") \
15             .set_step_criteria("Customer has specified an item") \
16             .set_valid_steps(["get_quantity"])
17 
18         order.add_step("get_quantity") \
19             .set_text("Ask how many they want.") \
20             .set_step_criteria("Customer has specified a quantity") \
21             .set_valid_steps(["confirm"])
22 
23         order.add_step("confirm") \
24             .set_text("Confirm the order details and thank them.") \
25             .set_step_criteria("Order has been confirmed") \
26             .set_end(True)
27 
28 if __name__ == "__main__":
29     agent = OrderAgent()
30     agent.run()

Multiple contexts

1 from signalwire import AgentBase
2 
3 class SupportAgent(AgentBase):
4     def __init__(self):
5         super().__init__(name="support-agent")
6         self.add_language("English", "en-US", "rime.spore")
7         self.prompt_add_section("Role", "You are a customer support assistant.")
8 
9         contexts = self.define_contexts()
10 
11         # Main menu
12         main = contexts.add_context("default")
13         main.add_step("menu") \
14             .set_text("Ask whether they need sales, support, or billing help.") \
15             .set_functions("none") \
16             .set_valid_contexts(["sales", "support", "billing"])
17 
18         # Sales context
19         sales = contexts.add_context("sales")
20         sales.set_system_prompt("You are a friendly sales representative.")
21         sales.add_step("qualify") \
22             .set_text("Understand what product the caller is interested in.") \
23             .set_functions(["check_inventory", "get_pricing"]) \
24             .set_valid_steps(["close"])
25         sales.add_step("close") \
26             .set_text("Close the sale or schedule a follow-up.") \
27             .set_valid_contexts(["default"])
28 
29         # Support context
30         support = contexts.add_context("support")
31         support.set_system_prompt("You are a patient support engineer.")
32         support.add_step("diagnose") \
33             .set_text("Understand the customer's issue.") \
34             .set_functions(["lookup_account", "check_status"]) \
35             .set_valid_steps(["resolve"])
36         support.add_step("resolve") \
37             .set_text("Resolve the issue or escalate.") \
38             .set_functions(["create_ticket", "transfer_call"]) \
39             .set_valid_contexts(["default"])