> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botcadence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompts

> Write, generate, and refine the instructions that guide your Botcadence agents

Prompts are the instructions for your AI Agent. They explain its role, tone, limits, and how it should use information and actions. You can write a prompt in a workflow or create a first draft with the **AI Prompt Generator**.

> [!NOTE]
>
> Keep product setup outside the prompt when the dashboard already has a setting for it. Use the prompt for behavior and decision-making; use **Voice**, **Tools**, **Channels**, and **Admin** settings for configuration.

## Choose where the prompt lives

* **Workflow Agent or Supervisor** — Use this when the prompt is part of a visual Chat or Voice workflow. Open **Build → Workflows**, select a node, and edit **Prompt / Instructions** in the **General** tab.
* **Task node** — Give a focused task its own instructions. A task should describe the result it must produce and the information it may use, rather than repeating the entire agent policy.
* **AI Configuration** — Some channel setups expose a prompt selector and model settings in **AI Configuration**. This is useful for a simple agent that does not need a multi-node flow.
* **AI Prompt Generator** — Open **AI Prompt Generator** from the project sidebar to create a first draft from a description, then refine it with follow-up instructions.

## Write a dependable prompt

Use a predictable structure so the agent can make the same decision every time:

1. **Role and objective** — Say who the agent is and what a successful conversation accomplishes.
2. **Scope** — List the questions and actions it handles, plus the requests it must decline or hand off.
3. **Conversation behavior** — Describe tone, language, response length, clarification questions, and how it should acknowledge uncertainty.
4. **Knowledge policy** — Tell it to use the project knowledge base for factual answers and not invent policies, prices, availability, or account details.
5. **Tool policy** — State when a tool is appropriate, what must be confirmed before a write action, and what to do when a tool fails.
6. **Handover and completion** — Explain when to transfer to a human, create a ticket, create a booking, or end the interaction.

### Example structure

```text theme={null}
You are the support agent for Acme.

Goal: resolve product and delivery questions in one conversation.
Use the knowledge base for product facts. If the answer is not there, say so and offer a handover.
Before changing an order or creating a ticket, confirm the customer's identity and the requested action.
Keep replies concise, friendly, and specific. Ask one clarifying question at a time.
Escalate billing disputes, threats, and requests for a human.
```

## Use variables safely

The prompt editor and welcome message support the dashboard's variable picker. Insert a variable only when the value is available for that conversation surface. Test a prompt with missing, empty, and unexpected values so the agent does not expose template syntax to customers.

## Generate and refine a prompt

**1. Open AI Prompt Generator**

From a project, choose **AI Prompt Generator**. The page loads available models and your previous generation history.

**2. Describe the agent**

Explain the audience, business, common requests, tone, knowledge sources, and escalation rules. Specific context produces a more useful first draft.

**3. Review the result**

Check the generated instructions for unsupported claims, overly broad permissions, and missing handover conditions. The generator is a drafting aid; your team owns the final behavior.

**4. Refine or copy**

Ask for a targeted change, such as a shorter tone or stricter refund policy, or copy the result into the relevant workflow node's **Prompt / Instructions** field.

## Publish and test

Saving a prompt changes a workflow draft. Select **Build → Playground**, choose the workflow, and test both normal questions and failure paths. Then publish the workflow from the designer before expecting a channel, inbound, or campaign to use the change. A draft prompt does not change live traffic.

For voice agents, pair prompt testing with [Voice Lab](/docs/build/voice-lab.md), then test interruptions, silence, ambiguous answers, and handover in [Playground](/docs/build/playground.md). For chat agents, verify the final response in the target [channel](/docs/deploy/channels.md) and review the resulting thread in [Conversations](/docs/operate/conversations.md).

## Common prompt problems

* **The agent invents an answer** — make knowledge-base use mandatory for factual questions and define a clear fallback.
* **The agent uses a tool too often** — add a condition, required inputs, and a confirmation step for writes.
* **The agent never hands off** — include observable trigger phrases and an explicit handover action or transfer path.
* **A change is not visible** — confirm the edited workflow is the one attached to the channel and that it is published.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.