> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# ContextBuilder

> Build multi-step conversation workflows with structured contexts and steps.

[context]: /docs/server-sdks/reference/python/agents/context-builder/context

[step]: /docs/server-sdks/reference/python/agents/context-builder/step

[agentbase]: /docs/server-sdks/reference/python/agents/agent-base

[addcontext]: /docs/server-sdks/reference/python/agents/context-builder/add-context

[getcontext]: /docs/server-sdks/reference/python/agents/context-builder/get-context

[reset]: /docs/server-sdks/reference/python/agents/context-builder/reset

[todict]: /docs/server-sdks/reference/python/agents/context-builder/to-dict

[validate]: /docs/server-sdks/reference/python/agents/context-builder/validate

ContextBuilder is the top-level container for defining structured conversation
workflows. It holds one or more [`Context`][context]
objects, each containing a sequence of [`Step`][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`][agentbase] instance. The builder
validates the entire context tree when the SWML document is rendered.

## **Properties**

**`agent`** `AgentBase` — required

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

---

> **Note**
>
> 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](/docs/server-sdks/reference/python/agents/context-builder/add-context)

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

#### [get\_context](/docs/server-sdks/reference/python/agents/context-builder/get-context)

Retrieve an existing context by name.

#### [reset](/docs/server-sdks/reference/python/agents/context-builder/reset)

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

#### [to\_dict](/docs/server-sdks/reference/python/agents/context-builder/to-dict)

Convert all contexts to a dictionary for SWML generation.

#### [validate](/docs/server-sdks/reference/python/agents/context-builder/validate)

Validate the entire context configuration tree.

#### [create\_simple\_context](/docs/server-sdks/reference/python/agents/context-builder/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

```python
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

```python
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"])
```

> Build multi-step conversation workflows with structured contexts and steps.

## Docs

- [add_context](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/add-context.md): Create a new named context and add it to the builder.
- [Context](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context.md): A named conversation workflow containing steps, prompts, and navigation rules.
- [add_bullets](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/add-bullets.md): Add a POM section with bullet points to the context prompt.
- [add_enter_filler](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/add-enter-filler.md): Add enter fillers for a specific language.
- [add_exit_filler](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/add-exit-filler.md): Add exit fillers for a specific language.
- [add_section](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/add-section.md): Add a POM section to the context prompt.
- [add_step](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/add-step.md): Add a new step to this context.
- [add_system_bullets](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/add-system-bullets.md): Add a POM section with bullets to the system prompt.
- [add_system_section](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/add-system-section.md): Add a POM section to the system prompt.
- [get_step](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/get-step.md): Get an existing step by name.
- [move_step](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/move-step.md): Move an existing step to a specific position in the step order.
- [remove_step](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/remove-step.md): Remove a step from this context.
- [set_consolidate](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-consolidate.md): Set whether to consolidate conversation history when entering this context.
- [set_enter_fillers](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-enter-fillers.md): Set all enter fillers at once.
- [set_exit_fillers](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-exit-fillers.md): Set all exit fillers at once.
- [set_full_reset](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-full-reset.md): Set whether to completely replace the system prompt when entering this context.
- [set_history](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-history.md): Set the default history visibility mode for every step in this context.
- [set_initial_step](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-initial-step.md): Set which step the context starts on when entered.
- [set_isolated](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-isolated.md): Set whether to truncate conversation history when entering this context.
- [set_post_prompt](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-post-prompt.md): Override the post-prompt text while this context is active.
- [set_prompt](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-prompt.md): Set the context's prompt text directly.
- [set_system_prompt](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-system-prompt.md): Set a new system prompt that takes effect when this context is entered.
- [set_user_prompt](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-user-prompt.md): Inject a user message when entering this context.
- [set_valid_contexts](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-valid-contexts.md): Set which contexts the agent can navigate to from this context.
- [set_valid_steps](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/context/set-valid-steps.md): Set which steps can be navigated to from any step in this context.
- [create_simple_context](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/create-simple-context.md): Helper function to create a standalone Context without a ContextBuilder.
- [GatherInfo & GatherQuestion](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/gather-classes.md): Structured information gathering within context steps using the server-side gather_info system.
- [get_context](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/get-context.md): Retrieve an existing context by name.
- [reset](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/reset.md): Remove all contexts, returning the builder to its initial state.
- [Step](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step.md): An individual step in a conversation context with prompt, criteria, and navigation.
- [add_bullets](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/add-bullets.md): Add a POM section with bullet points to the step.
- [add_gather_question](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/add-gather-question.md): Add a question to this step's gather_info configuration.
- [add_section](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/add-section.md): Add a POM section to the step.
- [clear_sections](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/clear-sections.md): Remove all POM sections and direct text from this step.
- [set_end](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-end.md): Set whether the conversation should end after this step completes.
- [set_functions](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-functions.md): Set which SWAIG functions are available during this step.
- [set_gather_info](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-gather-info.md): Enable structured info gathering for this step.
- [set_history](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-history.md): Control what the model still sees from earlier steps when this step is entered.
- [set_reset_consolidate](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-reset-consolidate.md): Set whether to consolidate conversation history on context switch.
- [set_reset_full_reset](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-reset-full-reset.md): Set whether to completely replace the system prompt on context switch.
- [set_reset_system_prompt](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-reset-system-prompt.md): Set a new system prompt for context switching from this step.
- [set_reset_user_prompt](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-reset-user-prompt.md): Set a user message to inject when this step triggers a context switch.
- [set_skip_to_next_step](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-skip-to-next-step.md): Automatically advance to the next step without evaluating criteria.
- [set_skip_user_turn](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-skip-user-turn.md): Skip waiting for user input after this step completes.
- [set_step_criteria](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-step-criteria.md): Define when this step is considered complete.
- [set_text](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-text.md): Set the step's prompt text directly.
- [set_valid_contexts](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-valid-contexts.md): Set which contexts the agent can navigate to from this step.
- [set_valid_steps](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/step/set-valid-steps.md): Set which steps the agent can navigate to from this step.
- [to_dict](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/to-dict.md): Convert all contexts to a dictionary for SWML generation.
- [validate](https://signalwire.com/docs/server-sdks/reference/python/agents/context-builder/validate.md): Validate the entire context configuration tree.