# Parlant Framework - Complete Breakdown

> **TL;DR**: Parlant is an open-source framework that makes AI chatbots actually follow your rules. Instead of hoping your AI behaves correctly, Parlant *ensures* it does through a smart system of guidelines, journeys, and verification checks.

---

## What Problem Does Parlant Solve?

If you've ever built an AI chatbot, you know the frustration:

- The AI ignores your carefully written instructions
- It makes up information (hallucinations)
- It behaves inconsistently - great one moment, terrible the next
- It goes off-topic when it shouldn't

**Parlant's philosophy**: "Stop fighting prompts, teach principles."

Instead of stuffing everything into one giant system prompt and hoping for the best, Parlant uses a structured approach where rules are *enforced*, not just *suggested*.

---

## How It Works (The Big Picture)

Think of Parlant like a smart traffic controller for AI conversations:

```
Customer Message
      ↓
┌─────────────────────────┐
│  Guideline Matcher      │ ← "Which rules apply right now?"
└─────────────────────────┘
      ↓
┌─────────────────────────┐
│  Tool Caller            │ ← "Do I need to look something up?"
└─────────────────────────┘
      ↓
┌─────────────────────────┐
│  Response Generator     │ ← "Draft a reply following the rules"
└─────────────────────────┘
      ↓
┌─────────────────────────┐
│  Coherence Checker      │ ← "Did I actually follow all the rules?"
└─────────────────────────┘
      ↓
Final Response to Customer
```

The key insight: Parlant **verifies** the AI followed the rules before sending a response. If it didn't, it corrects the output automatically.

---

## Core Concepts Explained

### 1. Guidelines (The Rules)

Guidelines are the heart of Parlant. Instead of one massive prompt, you create small, focused rules like:

| Condition (When) | Action (Do This) |
|------------------|------------------|
| Customer asks about refunds | Explain our 30-day policy, offer to start process |
| Customer seems frustrated | Acknowledge feelings, offer to escalate to human |
| Customer mentions competitor | Highlight our unique features, don't badmouth them |

**Why this is smart**: Parlant only loads the *relevant* guidelines for each conversation. If someone's asking about shipping, the refund rules stay out of the way.

**How matching works**:
1. Each guideline's condition is converted into a mathematical representation (vector embedding)
2. When a customer sends a message, Parlant compares the meaning of that message against all guidelines
3. Only the most relevant guidelines get activated

### 2. Journeys (The Roadmap)

Journeys are like flowcharts for conversations. They define the path a customer should take:

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Greeting   │ ──→ │ Understand   │ ──→ │   Resolve    │
│              │     │   Problem    │     │   Issue      │
└──────────────┘     └──────────────┘     └──────────────┘
                            │
                            ↓
                     ┌──────────────┐
                     │  Escalate to │
                     │    Human     │
                     └──────────────┘
```

**Key point**: Journeys aren't rigid scripts. The AI follows them as a guide while still adapting to how the customer actually behaves.

**When to use what**:
- **Journeys** → Complex multi-step interactions (like troubleshooting a technical issue)
- **Guidelines** → Simple, context-specific adjustments (like "always be polite about returns")

### 3. Context Variables (The Memory)

Context variables give your AI awareness about who it's talking to:

- Customer's name
- Their account status (VIP, new, etc.)
- Previous purchases
- Open support tickets

These can be **static** (set once) or **dynamic** (pulled fresh from your database during the conversation).

### 4. Glossary (The Dictionary)

Teach your AI domain-specific language:

| Term | Meaning |
|------|---------|
| "ARR" | Annual Recurring Revenue |
| "Churn" | When a customer cancels |
| "SKU" | Stock Keeping Unit - product identifier |

This ensures consistent terminology across all conversations.

### 5. Canned Responses (The Templates)

For critical information that must be *exactly* right, use templates:

> "Your order #{{order_id}} was shipped on {{ship_date}} via {{carrier}}. Track it here: {{tracking_url}}"

**Why this matters**: The AI can't hallucinate tracking numbers if it's pulling from a template with real data.

### 6. Tools (The Connections)

Tools let your AI actually *do* things:

- Look up order status in your database
- Check inventory levels
- Create support tickets
- Process refunds

**Important**: In Parlant, tools are tied to guidelines. A tool only runs when its associated guideline is matched. This creates a clear chain of "why did that happen?"

---

## The Self-Critique Mechanism

This is Parlant's secret weapon:

1. **Generate**: The AI drafts a response based on active guidelines
2. **Verify**: A separate check compares the draft against all the rules it was supposed to follow
3. **Correct or Approve**: If something's wrong, fix it. If it's good, send it.

This catches mistakes *before* the customer ever sees them.

---

## Technical Details

### Installation

```bash
pip install parlant
```

### Requirements

- Python 3.10 or higher
- Works with Python 3.10, 3.11, 3.12, 3.13, 3.14

### Supported AI Models

Parlant is model-agnostic and works with:
- OpenAI (GPT-4, etc.)
- Anthropic (Claude)
- Google (Gemini)
- Meta (Llama)
- Others via API

### Running the Server

```bash
parlant-server
```

This starts the Parlant server at `http://localhost:8800` with a built-in playground for testing.

### Architecture Layers

Parlant separates concerns into three layers:

| Layer | What It Does | Examples |
|-------|--------------|----------|
| **Policy** | Defines behavior | Guidelines, Journeys |
| **Tools/Variables** | Provides context & actions | APIs, database lookups |
| **Model** | Generates responses | OpenAI, Claude, Gemini |

This separation means you can change your AI model without rewriting your business logic.

---

## Why Use Parlant Over Other Frameworks?

| Challenge | Traditional Approach | Parlant Approach |
|-----------|---------------------|------------------|
| AI ignores instructions | Rewrite prompt, hope for best | Guidelines enforced via matching + verification |
| Hallucinations | Add "don't make things up" to prompt | Canned responses with real data |
| Inconsistent behavior | Accept it | Self-critique mechanism catches issues |
| Debugging issues | "Why did it say that??" | Full explainability - see which guidelines triggered |
| Scaling complexity | Prompt becomes unmanageable | Modular guidelines, only relevant ones loaded |
| Version control | Copy-paste prompts | Everything is code-native, Git-friendly |

---

## Use Cases

Parlant shines in scenarios where **getting it right matters**:

### Financial Services
- Compliance requirements
- Accurate account information
- Risk-appropriate recommendations

### Healthcare
- HIPAA compliance
- Accurate medical terminology
- Appropriate escalation paths

### E-commerce
- Order status accuracy
- Return policy consistency
- Product information precision

### Legal Tech
- Document review guidance
- Regulatory compliance
- Audit trail requirements

---

## Key Links

| Resource | URL |
|----------|-----|
| GitHub | https://github.com/emcie-co/parlant |
| Documentation | https://www.parlant.io/docs/ |
| Tutorial | https://www.parlant.io/docs/tutorial/getting-started/ |
| PyPI Package | https://pypi.org/project/parlant/ |
| Discord Community | https://discord.gg/duxWqxKk6J |

---

## Quick Stats

- **License**: Apache 2.0 (fully open source, commercial-friendly)
- **Current Version**: 3.0.4 (as of November 2025)
- **GitHub Stars**: 17,000+
- **Active Developers**: 10,000+
- **Author**: Yam Marcovitz / Emcie Co.

---

## Bottom Line

If you're building customer-facing AI agents and need them to be **reliable**, **consistent**, and **explainable**, Parlant is worth serious consideration. It trades the "prompt and pray" approach for structured, verifiable behavior control.

The learning curve is real - you'll need to think about your agent's behavior as guidelines and journeys rather than one big prompt. But for production systems where mistakes cost money (or trust), that structure pays off.
