# Data Mansion Console — User Guide: Agents, Workflows & Templates

This guide explains how to create AI agents, design conversation workflows, and use templates in the Data Mansion Console. It is written for business users and operators who configure agents — not for developers.

---

## What you can do

The Console lets you:

1. **Create agents** — AI assistants that talk to customers on your website, via API, or (with integrations) on WhatsApp and Telegram.
2. **Build workflows** — Visual conversation flows that collect information, send replies, calculate quotes, book calendar slots, and hand off to your team.
3. **Use templates** — Start from 20+ industry-ready workflows (events, retail, wellness, healthcare, and more), or save your own workspace templates to reuse across agents.

Every agent belongs to a **workspace** (created automatically when you sign up). All agents in a workspace share integrations and billing.

---

## Console navigation

| Path | Purpose |
|------|---------|
| `/console` | Dashboard — list of agents, quick stats |
| `/console/agents/new` | Create a new agent (blank or from template) |
| `/console/agents/{id}` | Configure a specific agent |
| `/console/settings/integrations` | Connect Google Calendar, WhatsApp, Telegram, WooCommerce |
| `/console/inbox` | View conversations handed off from agents |
| `/docs/agents-workflows-templates` | **Public** user guide (HTML — no login, scrapable) |
| `/docs/user-guide-agent-creation-workflows-templates.md` | **Public** raw markdown for knowledge-base ingestion |

---

## Creating an agent

Go to **Dashboard → New agent** (`/console/agents/new`). You have three options.

### Option A — Start from scratch

1. Enter an **agent name** (internal name; you can change the customer-facing display name later).
2. Click **Open workflow builder**.
3. You land on the agent's **Workflow** tab with a default flow:
   - Start → Ask a question → Send a message.

Use this when you want full control and no pre-built industry logic.

### Option B — Use a platform template

Platform templates are curated industry workflows maintained by Data Mansion. They include:

- Pre-wired workflow steps (qualification, quoting, booking, handoff)
- Default personality and welcome message
- A parameter registry (data fields the workflow collects)
- Required integrations (if any)

**Steps:**

1. Browse templates grouped by **sector** (Events, Retail, Wellness, Healthcare, F&B, etc.).
2. Click a template card to see details — step count, data fields captured, integrations needed.
3. Enter a **name for your agent** (e.g. "Penang Events Bot").
4. Click **Create agent with this workflow**.

You are taken directly to the **Workflow** tab with the template flow loaded. The agent starts in **Draft** status.

### Option C — Use a workspace template

If your team has saved custom templates (see [Saving your own templates](#saving-your-own-templates)), they appear under **Your workspace templates** on the create page. The flow is the same as platform templates: pick template → name agent → open workflow builder.

---

## Platform template catalog

There are **20 industry templates** across these sectors:

| Sector | Template |
|--------|----------|
| Events | Event Professionals |
| Retail | Retail & Trade Supplies |
| Wellness | Wellness & Aesthetics |
| Healthcare | Dental & Veterinary |
| Home Services | Home Services |
| F&B | F&B & Catering |
| Fitness | Fitness & Lifestyle |
| Logistics | Micro-Logistics |
| Automotive | Automobile Services |
| Education | Education & Enrichment |
| Property | Property & Rentals |
| Professional | Legal & Accounting |
| Travel | Travel & Tours |
| Services | Laundry & Dry Cleaning |
| Pet Care | Pet Grooming & Boarding |
| Construction | Interior & Renovation |
| Print | Printing & Signage |
| Workspace | Co-working & Meeting Rooms |
| Wedding | Wedding & Bridal |
| Insurance | Insurance Brokers |

Each template card shows how many **data fields** it captures and which **integrations** it expects (e.g. `google_calendar`, `whatsapp`, `woocommerce`).

**Example — Event Professionals**

- Captures: event date, event type, venue, duration, guest count, budget range
- Integrations: Google Calendar (availability check + booking)
- Flow pattern: greet → qualify → check calendar → quote → confirm or hand off

Connect required integrations **before going live** (see [Integrations](#integrations)).

---

## Agent configuration tabs

After creation, open any agent at `/console/agents/{id}`. The header shows the agent name, status dropdown, and seven tabs.

### Overview

Quick stats: knowledge sources, indexed chunks, conversations, safety blocks. Also shows model, language, and widget key.

### Personality & Brand

Configure how the agent presents itself:

| Setting | What it does |
|---------|--------------|
| **Display name** | Shown in the chat widget header (can differ from internal agent name) |
| **Avatar** | Uploaded image for the widget |
| **Welcome message** | First message visitors see when they open chat |
| **Brand guidelines** | Voice and rules (e.g. "Never quote prices — refer to booking page"). Prepended to the system prompt server-side |
| **Tone preset** | Professional, friendly, casual, formal, or custom |
| **Tone notes** | Extra guidance on how the agent should sound |
| **Widget theme** | Primary color and header subtitle |
| **System prompt** | Advanced: direct instructions to the LLM (editable) |
| **Model** | Which AI model powers free-form replies outside strict workflow steps |

Save changes before testing.

### Workflow

The visual **Process flow** builder (see [Workflow builder](#workflow-builder) below). This is where you design the conversation logic customers experience.

### Safety

Per-agent content safety rules: blocked topics/phrases, custom refusal message, strict mode. Platform-level safety (moderation, spam limits) is always on and cannot be disabled.

### Knowledge

Upload documents, paste text, or add URLs. The agent uses this for RAG (retrieval-augmented) answers when the conversation is not driven by a strict workflow step. Knowledge is indexed automatically; failed sources show an error message.

### Test chat

Live preview of the agent in the Console. **Important:** save your workflow and set agent status to **Active** before testing workflow behavior.

### Deploy

- **Website widget** — Copy embed code (`widget.js` or `widget-v2.js`) and paste into your site. Set status to **Active** first.
- **REST API** — Send messages from your backend using the agent's widget key (`X-Agent-Key` header).

---

## Agent status

| Status | Behavior |
|--------|----------|
| **Draft** | Agent exists but is not live on widget/API for production visitors |
| **Active** | Agent responds on widget, API, and connected channels |
| **Paused** | Temporarily stopped; existing embeds will not get replies |

Change status from the dropdown in the agent header.

---

## Workflow builder

The workflow builder is a drag-and-drop canvas. It defines the **structured conversation path** your agent follows — distinct from free-form AI chat driven by knowledge + system prompt.

### Layout

```
┌─────────────┬──────────────────────────┬──────────────┐
│ Node library│      Canvas (flow)       │ Node settings│
│  (left)     │      (center)            │  (right)     │
└─────────────┴──────────────────────────┴──────────────┘
                        Toolbar: Save workflow | Save as template
```

### Basic operations

1. **Add a node** — Drag from the Node library onto the canvas, or search nodes by name.
2. **Connect nodes** — Drag from one node's output handle to another node's input handle. Connections define execution order.
3. **Edit a node** — Click a node; settings appear in the right panel (Node settings).
4. **Delete a node** — Select it, then click **Remove step**, or press Delete/Backspace. The Start node cannot be removed.
5. **Save** — Click **Save workflow** in the toolbar. Unsaved changes are not active in Test chat or production.

The toolbar shows a live count of nodes, connections, and derived **Parameters** (auto-detected from Ask nodes).

### Start node

Every workflow has one **Start** node — the entry point when a customer sends their first message. Connect its bottom handle to your first real step (usually an Ask or Say node).

### How workflows run during chat

When a customer messages your agent:

1. The system loads the agent's **active workflow** (saved graph).
2. A **workflow run** is created or resumed for that conversation (state persists across messages).
3. The engine walks the graph node by node:
   - **Ask** nodes wait for the customer's reply, then store the answer in a variable.
   - **Say** nodes send a message and may auto-advance.
   - **If/Else** nodes branch based on a variable.
   - **Integration** nodes call external services (calendar, WhatsApp, WooCommerce, quote engine).
   - **Handoff** nodes queue the conversation in your Inbox for a human.
4. Variables collected along the way can be referenced in later messages using `{{variable_name}}`.

If no active workflow exists, the agent falls back to knowledge + system prompt (standard AI chat).

---

## Node reference

Nodes are grouped into three categories in the library.

### Conversation

| Node | Purpose | Key settings |
|------|---------|--------------|
| **Ask a question** | Collect information from the customer | Parameter label, field key, input type (text/number/date/select), required flag, question text |
| **Send a message** | Reply with fixed or templated text | Message body; use `{{field_key}}` for variables |
| **Hand off to human** | Escalate to your team | Handoff message; conversation appears in Inbox |

**Ask node — field key vs label**

- **Field key** — Internal variable name (e.g. `event_date`). Used in `{{event_date}}` templates and If/Else conditions. Must be unique within the workflow.
- **Parameter label** — Human-readable name shown in the Console parameter summary.

When you save a workflow, Ask nodes automatically update the agent's **parameters** registry.

**Send a message — variable interpolation**

```
Thanks {{customer_name}}! Your event on {{event_date}} at {{venue_location}} is noted.
```

Missing variables render as empty strings.

### Integrations

These nodes require a connected integration under **Settings → Integrations**.

| Node | Purpose | Key settings |
|------|---------|--------------|
| **Google Calendar** | Check availability or book an event | Connection, action, date variable, duration, event title template |
| **WhatsApp** | Send a WhatsApp message | Connection, message template, recipient (customer or staff alert), staff phone |
| **Telegram** | Send a Telegram message | Connection, message template |
| **WooCommerce** | Search products or check stock | Store connection, keyword variable, max results |

**Google Calendar actions**

- **Check availability** — Uses the date variable (default: `event_date`) to find open slots.
- **Book event** — Creates a calendar event with configurable duration and title template.

**WhatsApp recipient modes**

- **Customer** — Message goes to the visitor (when phone is known from the conversation).
- **Staff** — Alert your team (e.g. emergency triage in Dental & Veterinary template).

### Logic & routing

| Node | Purpose | Key settings |
|------|---------|--------------|
| **If / Else** | Branch based on a collected answer | Variable, operator (equals / not equals / contains), value. Connect Yes/No handles on the canvas to different paths |
| **Get quote** | AI-powered quote from prompt + pricing context | Mode (prompt + pasted context, rules, or API), prompt instructions, pricing table text. Outputs variables like `quote_amount` and `quote_summary` |
| **Calculate price (legacy)** | Deterministic base price + rules | Base amount, currency (default MYR). Used in seeded templates; prefer **Get quote** for new flows |

**If / Else example**

- Variable: `event_type`
- Operator: Equals
- Value: `Wedding`
- Yes branch → premium pricing path
- No branch → standard pricing path

Connect the **true** and **false** output handles on the If/Else node to the appropriate next steps.

---

## Variables and parameters

### Variables

Variables are key-value pairs collected during a conversation:

- Created by **Ask** nodes (key = field key)
- Enriched by **Get quote**, **Calculate price**, **Google Calendar**, and **WooCommerce** nodes
- Referenced in **Send a message**, **WhatsApp/Telegram** templates, and **If/Else** conditions

Variables persist for the duration of a conversation (stored in `workflow_runs`).

### Parameters registry

The agent's **parameters** list is auto-derived from Ask nodes when you save a workflow. This registry describes what data the agent is designed to collect — useful for templates and reporting.

The workflow toolbar shows a preview: `Parameters: Event date (date*), Venue (text*), …`

---

## Templates

### Platform templates vs workspace templates

| Type | Scope | Created by | Where to find |
|------|-------|------------|---------------|
| **Platform template** | All users | Data Mansion | Create agent page, grouped by sector |
| **Workspace template** | Your workspace only | You | Create agent page → "Your workspace templates" |

Platform templates include `agent_defaults` (tone, welcome message, brand guidelines, description) that are copied to the new agent on creation.

### Saving your own templates

From any agent's **Workflow** tab:

1. Build or customize your flow on the canvas.
2. Enter a name in the **Template name** field in the toolbar.
3. Click **Save as template**.

This saves the current steps, graph, and derived parameters to your workspace. Other team members can then create new agents from it via **Create agent → Your workspace templates**.

Workspace templates do **not** automatically update agents that were already created from them — each agent gets an independent copy at creation time.

### When to use templates

- **Platform template** — Fastest start for a known industry (events, salon, dental, etc.).
- **Workspace template** — You perfected a flow for one client or location and want to clone it.
- **Blank agent** — Unique use case with no close match.

---

## Integrations

Workflow integration nodes will not work until connections are set up.

Go to **Settings → Integrations** (`/console/settings/integrations`):

| Integration | Used by | Setup summary |
|-------------|---------|---------------|
| **Google Calendar** | Calendar nodes | OAuth — connect your Google account |
| **WhatsApp** | WhatsApp nodes | Phone Number ID + access token; webhook registration |
| **Telegram** | Telegram nodes | Bot token from @BotFather |
| **WooCommerce** | WooCommerce nodes | Shop URL + REST consumer key/secret |

After connecting, return to the workflow builder. Integration nodes show a **Connection** dropdown populated with your workspace connections.

A reminder appears above the workflow canvas: *"Calendar / WhatsApp steps need integrations connected first."*

---

## End-to-end workflow: from creation to live

Follow this checklist for a new agent:

```
1. Create agent (template or blank)
        ↓
2. Workflow tab — review/customize flow → Save workflow
        ↓
3. Personality & Brand — display name, welcome message, colors, guidelines
        ↓
4. Knowledge (optional) — upload FAQs, policies, product docs
        ↓
5. Safety — review blocked topics if needed
        ↓
6. Settings → Integrations — connect any required services
        ↓
7. Workflow tab — assign connections on integration nodes → Save again
        ↓
8. Set status to Active
        ↓
9. Test chat — walk through the full flow
        ↓
10. Deploy — copy widget embed or API example
```

### Testing tips

- Save the workflow before testing.
- Set agent status to **Active** (Draft agents may not run workflows in Test chat).
- Walk through each Ask step — verify variables appear correctly in subsequent Say nodes.
- Test If/Else branches with different answers.
- For calendar/WhatsApp/WooCommerce steps, confirm the integration connection is selected on each node.

---

## Common workflow patterns

### Qualify → Quote → Hand off

```
Start → Ask (need) → Ask (budget) → Get quote → Say (quote summary) → Hand off
```

Used in: Event Professionals, many service templates.

### Qualify → Calendar → Confirm

```
Start → Ask (date) → Ask (service type) → Google Calendar (check) → Say (available slots) → Google Calendar (book) → Say (confirmed)
```

Used in: Wellness & Aesthetics, Co-working & Meeting Rooms.

### Diagnose → Product match → Contact

```
Start → Ask (problem) → WooCommerce (search) → Say (product list) → Ask (contact) → Hand off
```

Used in: Retail & Trade Supplies.

### Triage → Alert staff → Book routine

```
Start → Ask (symptoms) → If/Else (emergency?) → Yes: WhatsApp (staff alert) + Hand off
                                                    → No: Ask (preferred date) → Google Calendar → Say (booked)
```

Used in: Dental & Veterinary.

---

## Inbox and handoff

When a workflow reaches a **Hand off to human** node:

1. The visitor sees your handoff message.
2. The conversation is queued in **Console → Inbox**.
3. A team member opens the thread and clicks **Take over** to reply manually.

Use handoff for complex cases, payment discussions, or anything the automated flow should not handle.

---

## Frequently asked questions

**Do I need a workflow if I only want a FAQ bot?**

No. You can create a blank agent, skip the workflow (or leave the default), upload knowledge, and rely on RAG + system prompt. Workflows are for structured multi-step processes (booking, quoting, triage).

**Can one agent have multiple workflows?**

Currently each agent has one **Main flow** workflow. Use If/Else branching for different paths within a single flow.

**Why doesn't my workflow run in Test chat?**

Check: (1) workflow saved, (2) agent status is **Active**, (3) Start node is connected to at least one step.

**Can I edit a platform template after creating an agent?**

Yes. The template is copied at creation time. Changes to your agent's workflow do not affect the original platform template.

**What happens if I delete an Ask node that other nodes reference?**

Messages using `{{that_field}}` will show empty values. Update Say/WhatsApp templates and If/Else conditions after renaming or removing fields.

**What's the difference between workflow messages and AI chat?**

Workflow **Say** nodes send deterministic (or templated) messages as part of the graph. Outside workflow steps, or when the workflow completes, the agent uses the LLM with knowledge + system prompt for free-form replies.

**Which currency does pricing use?**

Legacy **Calculate price** defaults to MYR. **Get quote** uses whatever currency you specify in the prompt and pricing context.

---

## Glossary

| Term | Definition |
|------|------------|
| **Agent** | A configured AI assistant with personality, knowledge, workflow, and deploy keys |
| **Workflow** | A visual graph of conversation steps attached to one agent |
| **Node / Step** | A single action in the workflow (ask, say, if/else, integration, etc.) |
| **Variable** | A piece of data collected or computed during a conversation |
| **Parameter** | A registered data field (derived from Ask nodes) describing what the agent captures |
| **Template** | A reusable workflow + defaults package used to spawn new agents |
| **Integration** | An external service connection (calendar, messaging, e-commerce) |
| **Handoff** | Transferring a conversation from the agent to a human in Inbox |
| **Widget key** | Public identifier used to embed the agent on a website or call the chat API |
| **Workspace** | Your team's container for agents, templates, integrations, and billing |

---

## Quick reference — Console URLs

| Action | URL |
|--------|-----|
| Dashboard | `/console` |
| New agent | `/console/agents/new` |
| Agent detail | `/console/agents/{agent-id}` |
| Agent workflow tab | `/console/agents/{agent-id}?tab=workflow` |
| Integrations | `/console/settings/integrations` |
| Inbox | `/console/inbox` |
| User guide (HTML) | `/docs/agents-workflows-templates` |
| User guide (raw MD) | `/docs/user-guide-agent-creation-workflows-templates.md` |

---

*Last updated for Data Mansion Console — agents, workflow builder, and template platform.*