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

# prompt

> The operator prompt that instructs the ai_sidecar observer how to coach the agent.

[ai_sidecar]: /docs/swml/reference/calling/ai-sidecar

The operator prompt instructs the sidecar how to coach the agent — what to watch for, when to speak up, and when to stay silent. SignalWire automatically adds built-in instructions for the sidecar's role, so your prompt only needs to describe the coaching behavior. It is recommended to write prompts using markdown formatting, as models better understand structured content.

`prompt` is optional. When omitted, the sidecar falls back to a minimal default prompt, so setting one is strongly recommended.

The sidecar prompt supports the text, POM, and file forms below. The model's settings are configured separately — see the [`model`](/docs/swml/reference/calling/ai-sidecar) field and [`params`](/docs/swml/reference/calling/ai-sidecar/params).

### Prompt forms

There are three ways to define the prompt content:

* **Text** — A single string with the full prompt. Provide it as a bare string (`prompt: "..."`) or as an object with a `text` field. Best for simple coaching instructions.
* **POM (Prompt Object Model)** — A structured array of sections with titles, body text, and bullets. SignalWire renders the POM into a markdown document before sending it to the model. Best for prompts that benefit from clear organization.
* **File** — A path to a server-side file whose contents become the prompt.

## **Properties**

**`ai_sidecar.prompt`** `string | object`

The operator prompt. Provide a plain string, or one of the objects below.

---

#### Text

**`prompt.text`** `string` — required

The full operator prompt as a single block of text. Equivalent to passing `prompt` as a bare string.

---

#### POM

**`prompt.pom`** `object[]` — required

An array of POM sections that SignalWire renders into a markdown document before sending it to the model.

---

**`pom[].title`** `string`

Title for the section.

---

**`pom[].body`** `string`

Body text for the section.

---

**`pom[].bullets`** `string[]`

An array of bullet points for the section.

---

**`pom[].subsections`** `object[]`

An array of nested POM sections, each with the same fields as a top-level section.

---

**`pom[].numbered`** `boolean` — default: false

Whether to number the section.

---

**`pom[].numberedBullets`** `boolean` — default: false

Whether to number the bullets within the section.

---

#### File

**`prompt.file`** `string` — required

Path to a server-side file whose contents are used as the prompt. If both `file` and `pom`/`text` are present, `file` takes precedence.

---

## **Variable expansion**

The prompt supports variable expansion in any form. Reference values from `global_data`, from the persistent `ai_agents_global_data`, and from the following call variables:

**`${global_data.*}`** `string`

Any value from the sidecar's [`global_data`](/docs/swml/reference/calling/ai-sidecar), e.g. `${global_data.customer_id}`.

---

**`${ai_agents_global_data.*}`** `string`

Any value from `ai_agents_global_data`, which persists across sessions on the same call leg, e.g. `${ai_agents_global_data.deal.mrr}`.

---

**`${caller_id_number}`** `string`

The caller's phone number.

---

**`${destination_number}`** `string`

The destination phone number.

---

**`${customer_role}`** `string`

Which leg is the customer — `remote-caller` or `local-caller`.

---

**`${local_date}`** `string`

The current local date.

---

**`${local_time}`** `string`

The current local time.

---

**`${local_tz}`** `string`

The local timezone.

---

**`${session_uuid}`** `string`

The unique identifier for the call session.

---

## **Examples**

#### Text (YAML)

```yaml
version: 1.0.0
sections:
  main:
    - ai_sidecar:
        prompt: "You are a real-time sales copilot. After each customer turn, give the agent one concise piece of advice, or call sidecar_skip if no advice is needed."
        lang: "en-US"
```

#### Text (JSON)

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "ai_sidecar": {
          "prompt": "You are a real-time sales copilot. After each customer turn, give the agent one concise piece of advice, or call sidecar_skip if no advice is needed.",
          "lang": "en-US"
        }
      }
    ]
  }
}
```

#### POM (YAML)

```yaml
version: 1.0.0
sections:
  main:
    - ai_sidecar:
        prompt:
          pom:
            - title: Personality
              body: "You are a real-time sales copilot."
            - title: Instructions
              bullets:
                - "Watch for buying signals."
                - "Call lookup_competitor when a competitor is mentioned."
        lang: "en-US"
```

#### POM (JSON)

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "ai_sidecar": {
          "prompt": {
            "pom": [
              {
                "title": "Personality",
                "body": "You are a real-time sales copilot."
              },
              {
                "title": "Instructions",
                "bullets": [
                  "Watch for buying signals.",
                  "Call lookup_competitor when a competitor is mentioned."
                ]
              }
            ]
          },
          "lang": "en-US"
        }
      }
    ]
  }
}
```