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.

reset

Remove all contexts, returning the builder to its initial state.

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

from signalwire import AgentBase
class OrderAgent(AgentBase):
    def __init__(self):
        super().__init__(name="order-agent")
        self.add_language("English", "en-US", "rime.spore")
        self.prompt_add_section("Role", "You help customers place orders.")
        contexts = self.define_contexts()
        order = contexts.add_context("default")
        order.add_step("get_item") \
            .set_text("Ask what item they want to order.") \
            .set_step_criteria("Customer has specified an item") \
            .set_valid_steps(["get_quantity"])
        order.add_step("get_quantity") \
            .set_text("Ask how many they want.") \
            .set_step_criteria("Customer has specified a quantity") \
            .set_valid_steps(["confirm"])
        order.add_step("confirm") \
            .set_text("Confirm the order details and thank them.") \
            .set_step_criteria("Order has been confirmed") \
            .set_end(True)
if __name__ == "__main__":
    agent = OrderAgent()
    agent.run()

Multiple contexts

from signalwire import AgentBase
class SupportAgent(AgentBase):
    def __init__(self):
        super().__init__(name="support-agent")
        self.add_language("English", "en-US", "rime.spore")
        self.prompt_add_section("Role", "You are a customer support assistant.")
        contexts = self.define_contexts()
        # Main menu
        main = contexts.add_context("default")
        main.add_step("menu") \
            .set_text("Ask whether they need sales, support, or billing help.") \
            .set_functions("none") \
            .set_valid_contexts(["sales", "support", "billing"])
        # Sales context
        sales = contexts.add_context("sales")
        sales.set_system_prompt("You are a friendly sales representative.")
        sales.add_step("qualify") \
            .set_text("Understand what product the caller is interested in.") \
            .set_functions(["check_inventory", "get_pricing"]) \
            .set_valid_steps(["close"])
        sales.add_step("close") \
            .set_text("Close the sale or schedule a follow-up.") \
            .set_valid_contexts(["default"])
        # Support context
        support = contexts.add_context("support")
        support.set_system_prompt("You are a patient support engineer.")
        support.add_step("diagnose") \
            .set_text("Understand the customer's issue.") \
            .set_functions(["lookup_account", "check_status"]) \
            .set_valid_steps(["resolve"])
        support.add_step("resolve") \
            .set_text("Resolve the issue or escalate.") \
            .set_functions(["create_ticket", "transfer_call"]) \
            .set_valid_contexts(["default"])