***

title: PomBuilder
slug: /reference/python/agents/pom-builder
description: Build structured Prompt Object Model prompts with sections, subsections, and bullets.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

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

[addsection]: /docs/server-sdks/reference/python/agents/pom-builder/add-section

[addsubsection]: /docs/server-sdks/reference/python/agents/pom-builder/add-subsection

[addtosection]: /docs/server-sdks/reference/python/agents/pom-builder/add-to-section

[fromsections]: /docs/server-sdks/reference/python/agents/pom-builder/from-sections

[getsection]: /docs/server-sdks/reference/python/agents/pom-builder/has-section

[hassection]: /docs/server-sdks/reference/python/agents/pom-builder/has-section

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

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

[tojson]: /docs/server-sdks/reference/python/agents/pom-builder/to-json

PomBuilder provides a fluent interface for creating structured prompts using
the Prompt Object Model (POM). POM organizes prompt content into titled sections,
subsections, and bullet lists -- producing consistent, well-structured prompts
that the AI can follow reliably.

Use PomBuilder when you need fine-grained control over prompt structure beyond
what `set_prompt_text()` and `prompt_add_section()` on
[`AgentBase`][agentbase] provide. The builder
can render to Markdown or XML format.

<Note>
  PomBuilder requires the `signalwire-pom` package. Install it with:
  `pip install signalwire-pom`
</Note>

## **Methods**

<CardGroup cols={3}>
  <Card title="add_section" href="/docs/server-sdks/reference/python/agents/pom-builder/add-section">
    Add a new top-level section to the POM.
  </Card>

  <Card title="add_subsection" href="/docs/server-sdks/reference/python/agents/pom-builder/add-subsection">
    Add a subsection to an existing section.
  </Card>

  <Card title="add_to_section" href="/docs/server-sdks/reference/python/agents/pom-builder/add-to-section">
    Add content to an existing section.
  </Card>

  <Card title="from_sections" href="/docs/server-sdks/reference/python/agents/pom-builder/from-sections">
    Create a PomBuilder from a list of section dictionaries.
  </Card>

  <Card title="get_section" href="/docs/server-sdks/reference/python/agents/pom-builder/has-section">
    Get a section by title for direct manipulation.
  </Card>

  <Card title="has_section" href="/docs/server-sdks/reference/python/agents/pom-builder/has-section">
    Check if a section with a given title exists.
  </Card>

  <Card title="render" href="/docs/server-sdks/reference/python/agents/pom-builder/render">
    Render the POM as Markdown or XML.
  </Card>

  <Card title="to_dict" href="/docs/server-sdks/reference/python/agents/pom-builder/to-dict">
    Convert the POM to a list of section dictionaries.
  </Card>

  <Card title="to_json" href="/docs/server-sdks/reference/python/agents/pom-builder/to-json">
    Convert the POM to a JSON string.
  </Card>
</CardGroup>

## **Examples**

### Building a structured prompt

```python {3}
from signalwire.core.pom_builder import PomBuilder

pom = PomBuilder()

pom.add_section(
    "Role",
    body="You are a customer service representative for Acme Corp."
)

pom.add_section(
    "Guidelines",
    bullets=[
        "Always greet the customer by name when available",
        "Be concise and professional",
        "Never make promises about timelines you cannot keep"
    ]
)

pom.add_section(
    "Product Knowledge",
    body="You have access to the product catalog.",
    subsections=[
        {
            "title": "Pricing",
            "body": "Always quote current prices from the catalog."
        },
        {
            "title": "Returns",
            "body": "30-day return policy for all items."
        }
    ]
)

# Render as Markdown for use in a prompt
prompt_text = pom.render_markdown()
print(prompt_text)
```

### Incremental construction

```python {3}
from signalwire.core.pom_builder import PomBuilder

pom = PomBuilder()

# Start with a basic section
pom.add_section("Capabilities", body="You can help with the following:")

# Add bullets incrementally as skills are loaded
pom.add_to_section("Capabilities", bullet="Weather lookups")
pom.add_to_section("Capabilities", bullet="Calendar scheduling")
pom.add_to_section("Capabilities", bullets=[
    "Order tracking",
    "Account management"
])

# Add a subsection
pom.add_subsection(
    "Capabilities",
    "Limitations",
    body="You cannot process payments directly."
)

print(pom.render_markdown())
```

### Reconstructing from data

```python {8}
from signalwire.core.pom_builder import PomBuilder

# Rebuild a PomBuilder from serialized data
sections = [
    {"title": "Role", "body": "You are a helpful assistant."},
    {"title": "Rules", "bullets": ["Be concise", "Be accurate"]}
]

pom = PomBuilder.from_sections(sections)
xml_prompt = pom.render_xml()
print(xml_prompt)
```