***
title: Prompts & POM
description: The Prompt Object Model (POM) provides a structured way to build AI prompts using sections, subsections, and bullets rather than raw text.
slug: /guides/prompts-pom
max-toc-depth: 3
---------------------
For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt
### Why POM?
| Aspect | Raw Text Prompt | POM Structured Prompt |
| ------------------- | ------------------- | -------------------------------------------------- |
| **Format** | One long string | Organized sections with body, bullets, subsections |
| **Maintainability** | Hard to maintain | Easy to modify individual sections |
| **Structure** | No structure | Clear hierarchy (Role -> Guidelines -> Rules) |
| **Extensibility** | Difficult to extend | Reusable components |
**Raw Text Problems:**
* Everything mixed together in one string
* Hard to find and update specific instructions
* Difficult to share sections between agents
**POM Benefits:**
* Sections keep concerns separated
* Bullets make lists scannable
* Subsections add depth without clutter
* Renders to clean, formatted markdown
### POM Structure
### Adding Sections
#### Basic Section with Body
The `prompt_add_section` method is the primary way to build prompts:
```python
from signalwire import AgentBase
class MyAgent(AgentBase):
def __init__(self):
super().__init__(name="my-agent")
# Simple section with body text
self.prompt_add_section(
"Role",
"You are a helpful customer service representative for Acme Corp."
)
```
```typescript
import { AgentBase } from 'signalwire-agents';
const agent = new AgentBase({ name: 'my-agent' });
agent.promptAddSection('Role', { body: 'You are a helpful customer service representative for Acme Corp.' });
```
#### Section with Bullets
Adding bullets to a section follows a similar pattern across languages:
| Language | Syntax |
| ---------- | ------------------------------------------------------------- |
| Python | `prompt_add_section("Title", body="text", bullets=[...])` |
| TypeScript | `promptAddSection('Title', { body: 'text', bullets: [...] })` |
```python
## Section with bullet points
self.prompt_add_section(
"Guidelines",
body="Follow these guidelines when speaking with customers:",
bullets=[
"Be professional and courteous at all times",
"Ask clarifying questions when the request is unclear",
"Keep responses concise - this is a voice conversation",
"Offer to transfer to a human if you cannot help"
]
)
```
#### Section with Numbered Bullets
```python
## Use numbered list instead of bullets
self.prompt_add_section(
"Process",
body="Follow this process for each call:",
bullets=[
"Greet the customer warmly",
"Identify the reason for their call",
"Resolve the issue or transfer",
"Thank them and end the call"
],
numbered_bullets=True # 1. 2. 3. instead of bullets
)
```
### Subsections
Add nested structure within sections:
```python
## First, create the parent section
self.prompt_add_section(
"Policies",
body="Follow company policies in these areas:"
)
## Then add subsections
self.prompt_add_subsection(
"Policies", # Parent section title
"Returns", # Subsection title
body="For return requests:",
bullets=[
"Items can be returned within 30 days",
"Receipt is required for cash refunds",
"Exchanges are always available"
]
)
self.prompt_add_subsection(
"Policies",
"Billing",
body="For billing inquiries:",
bullets=[
"Verify customer identity first",
"Review last 3 statements",
"Offer payment plans if needed"
]
)
```
### Declarative Prompts (PROMPT\_SECTIONS)
Define prompts declaratively as a class attribute:
```python
class DeclarativeAgent(AgentBase):
PROMPT_SECTIONS = {
"Role": "You are a friendly assistant for a pizza restaurant.",
"Menu Knowledge": [
"Small pizza: $10",
"Medium pizza: $14",
"Large pizza: $18",
"Toppings: $1.50 each"
],
"Order Process": {
"body": "When taking orders:",
"bullets": [
"Confirm the size first",
"List available toppings",
"Repeat the order back",
"Provide total price"
]
},
"Policies": {
"body": "Restaurant policies:",
"subsections": [
{
"title": "Delivery",
"body": "Delivery information:",
"bullets": [
"Free delivery over $25",
"$5 fee under $25",
"30-45 minute delivery time"
]
},
{
"title": "Pickup",
"bullets": [
"Ready in 15-20 minutes",
"Call when you arrive"
]
}
]
}
}
def __init__(self):
super().__init__(name="pizza-agent")
self.add_language("English", "en-US", "rime.spore")
```
### POM Builder Direct Access
For advanced use, access the POM builder directly:
```python
class AdvancedAgent(AgentBase):
def __init__(self):
super().__init__(name="advanced-agent")
# Direct POM access
self.pom.section("Role").body(
"You are an expert technical support agent."
)
self.pom.section("Expertise").bullets([
"Network troubleshooting",
"Software installation",
"Hardware diagnostics"
])
# Chain multiple calls
(self.pom
.section("Process")
.body("Follow these steps:")
.numbered_bullets([
"Identify the issue",
"Run diagnostics",
"Apply solution",
"Verify resolution"
]))
```
### Post-Call Prompts
Post-prompts run after a call ends, allowing the AI to generate summaries, extract data, or create structured output from the conversation.
#### When Post-Prompts Run
Post-prompts execute:
* After the caller hangs up
* After a transfer completes
* After an inactivity timeout
* Before any post-call webhooks fire
The AI has access to the full conversation history when generating the post-prompt response.
#### set\_post\_prompt() vs set\_post\_prompt\_data()
Use `set_post_prompt()` for simple text instructions:
| Language | Syntax |
| ---------- | ------------------------------------------------ |
| Python | `self.set_post_prompt("Summarize this call...")` |
| TypeScript | `agent.setPostPrompt('Summarize this call...')` |
```python
self.set_post_prompt(
"Summarize this call including: "
"1) The customer's issue "
"2) How it was resolved "
"3) Any follow-up needed"
)
```
Use `set_post_prompt_data()` for full control over generation parameters:
```python
self.set_post_prompt_data({
"text": "Generate a detailed call summary.",
"temperature": 0.3,
"top_p": 0.9
})
```
#### Post-Prompt Data Options
| Field | Type | Default | Description |
| ------------- | ------ | -------- | ----------------------------------------------- |
| `text` | string | Required | The post-prompt instruction |
| `temperature` | float | 0.3 | Creativity level (0-2, lower = more consistent) |
| `top_p` | float | 1.0 | Nucleus sampling threshold |
| `max_tokens` | int | 256 | Maximum output length |
#### Common Post-Prompt Use Cases
**Call summarization:**
```python
self.set_post_prompt(
"Summarize this call in 2-3 sentences. Include the main topic, "
"outcome, and any commitments made."
)
```
**Structured data extraction:**
```python
self.set_post_prompt_data({
"text": """
Extract from this conversation and format as JSON:
{
"customer_name": "name if mentioned",
"issue_category": "billing|technical|sales|general",
"resolution": "resolved|escalated|pending|unknown",
"follow_up_required": true/false,
"sentiment": "positive|neutral|negative"
}
""",
"temperature": 0.1 # Low for consistent structure
})
```
**CRM notes:**
```python
self.set_post_prompt(
"Generate CRM notes for this call. Include: "
"- Customer inquiry summary "
"- Actions taken by agent "
"- Next steps or follow-up items "
"- Any account changes discussed"
)
```
**Compliance logging:**
```python
self.set_post_prompt(
"Log compliance-relevant details: "
"- Was identity verified? "
"- What sensitive data was discussed? "
"- Were required disclosures given? "
"- Any compliance concerns noted?"
)
```
#### Post-Prompt Best Practices
**DO:**
* Use low temperature (0.1-0.3) for structured extraction
* Keep instructions clear and specific
* Test with various conversation types
* Use JSON format for machine-readable output
**DON'T:**
* Expect post-prompt to modify call behavior (call already ended)
* Use high temperature for data extraction
* Request very long outputs (increases latency)
* Assume all fields will always be populated
### Voice-Optimized Prompts
Write prompts optimized for voice conversations:
```python
class VoiceOptimizedAgent(AgentBase):
def __init__(self):
super().__init__(name="voice-agent")
self.add_language("English", "en-US", "rime.spore")
self.prompt_add_section(
"Voice Guidelines",
body="Optimize all responses for voice:",
bullets=[
"Keep sentences short - under 20 words",
"Avoid technical jargon unless necessary",
"Use conversational language, not formal",
"Pause naturally between topics",
"Don't list more than 3 items at once",
"Spell out acronyms on first use"
]
)
self.prompt_add_section(
"Response Style",
bullets=[
"Start responses with the key information",
"Confirm understanding before long explanations",
"Ask 'Does that make sense?' after complex topics",
"Use filler words naturally: 'Let me check that for you'"
]
)
```
### Prompt Best Practices
#### 1. Lead with Role Definition
```python
## Good - clear role first
self.prompt_add_section(
"Role",
"You are Sarah, a senior customer service representative "
"at TechCorp with 5 years of experience helping customers "
"with software products."
)
```
#### 2. Separate Concerns
```python
## Good - each section has one purpose
self.prompt_add_section("Role", "...")
self.prompt_add_section("Knowledge", "...")
self.prompt_add_section("Guidelines", "...")
self.prompt_add_section("Restrictions", "...")
## Bad - everything mixed together
self.prompt_add_section("Instructions",
"You are an agent. Be nice. Don't share secrets. "
"You know about products. Follow the rules..."
)
```
#### 3. Use Bullets for Lists
```python
## Good - scannable bullets
self.prompt_add_section(
"Products",
body="You can help with these products:",
bullets=["Basic Plan - $10/mo", "Pro Plan - $25/mo", "Enterprise - Custom"]
)
## Bad - inline list
self.prompt_add_section(
"Products",
"Products include Basic Plan at $10/mo, Pro Plan at $25/mo, "
"and Enterprise with custom pricing."
)
```
#### 4. Be Specific About Restrictions
```python
## Good - explicit restrictions
self.prompt_add_section(
"Restrictions",
bullets=[
"Never share customer passwords or security codes",
"Do not process refunds over $500 without transfer",
"Cannot modify account ownership",
"Must verify identity before account changes"
]
)
```
### Generated Prompt Output
POM converts your structure to formatted text:
```text
## Role
You are Sarah, a customer service representative for Acme Corp.
## Guidelines
Follow these guidelines:
* Be professional and courteous
* Ask clarifying questions when needed
* Keep responses concise for voice
## Policies
### Returns
For return requests:
* Items can be returned within 30 days
* Receipt required for cash refunds
### Billing
For billing inquiries:
* Verify customer identity first
* Review recent statements
```