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

# Escalation Rules

> Define when your agent should hand off to humans

Escalation rules define conditions under which your agent should stop and hand off the conversation to a human agent.

{/* Screenshot: Escalation rules tab showing list of rules with names and status */}

## What are Escalation Rules?

Escalation rules identify situations where human judgment is needed:

* Customer is upset or threatening
* Question involves legal, compliance, or security
* Issue is too complex for automation
* Customer explicitly requests a human
* VIP or high-value customer needs attention

## Creating Escalation Rules

<Steps>
  <Step title="Navigate to Guardrails">
    Go to **Train → Guardrails** and select the **Escalation Rules** tab.
  </Step>

  <Step title="Click Create Rule">
    Click **Create Escalation Rule**.

    {/* Screenshot: Create escalation rule dialog/drawer */}
  </Step>

  <Step title="Name Your Rule">
    Give it a descriptive name:

    * Good: "Angry Customer Escalation", "Legal Question Detection"
    * Avoid: "Rule 1", "Escalation"
  </Step>

  <Step title="Define Trigger">
    Configure what causes this rule to trigger.

    {/* Screenshot: Trigger configuration showing detection method selection */}
  </Step>

  <Step title="Configure Response">
    Define what happens when triggered:

    * Message to send to customer
    * Internal note content
    * Routing rules
  </Step>

  <Step title="Test">
    Use the built-in playground to verify detection.
  </Step>

  <Step title="Save">
    Save and activate the rule.
  </Step>
</Steps>

## Detection Methods

### AI-Based Detection

Use natural language to describe when to escalate:

{/* Screenshot: AI detection prompt configuration */}

**Example prompts:**

```
Escalate when the customer expresses significant frustration 
or anger about the service, especially if they mention:
- Wanting to cancel their account
- Threatening negative reviews
- Repeated issues without resolution
- Being a long-time customer who is disappointed
```

```
Escalate when the conversation involves legal topics including:
- Contract terms or disputes
- Liability questions
- Threats of legal action
- Requests for legal documentation
```

**Strengths:**

* Handles nuanced situations
* Adapts to context
* No need to predict every phrase

### Keyword Detection

Trigger on specific words or phrases:

{/* Screenshot: Keyword list configuration */}

**Example keywords:**

```
cancel, cancellation, lawsuit, lawyer, attorney, 
speak to human, talk to person, manager, supervisor,
unacceptable, furious, terrible service, worst experience
```

**Strengths:**

* Fast and predictable
* Easy to understand and audit
* Good for specific trigger words

### Regex Detection

Match complex patterns:

**Example patterns:**

```
# Phone numbers
\b\d{3}[-.]?\d{3}[-.]?\d{4}\b

# Credit card numbers (trigger for security)
\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b

# Email addresses in specific domains
\b[\w.-]+@competitor\.com\b
```

**Strengths:**

* Precise pattern matching
* Good for structured data
* Catches variations

### Combining Methods

Use multiple detection methods together:

```
Trigger escalation when:
- AI detects customer frustration AND
- (Keywords include "cancel" OR "refund") AND
- Conversation is longer than 5 messages
```

## Configuring Escalation Response

### Customer Message

What the agent sends to the customer when escalating:

{/* Screenshot: Customer message template editor */}

**Example:**

```
I understand this is important to you, and I want to make sure 
you get the best help possible. I'm connecting you with a 
member of our team who can assist you directly.

You can expect to hear from them within [timeframe]. 
Thank you for your patience!
```

### Internal Note

Context for the human agent:

```
## Escalation Summary

**Reason:** Customer expressed frustration about repeated billing issues

**Context:**
- Customer has contacted support 3 times about this issue
- Previous resolutions did not work
- Customer mentioned considering cancellation

**Conversation Summary:**
[Auto-generated summary]

**Recommended Action:**
Review billing history and consider goodwill gesture
```

### Routing (if applicable)

Where to route the escalated conversation:

* Specific team or queue
* Priority level
* Assignment rules

## Example Escalation Rules

### Angry Customer

| Setting       | Value                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------- |
| **Name**      | Angry Customer Escalation                                                                         |
| **Detection** | AI-based                                                                                          |
| **Prompt**    | Escalate when customer expresses significant frustration, anger, or threatens to leave            |
| **Message**   | "I can see this has been frustrating. Let me connect you with someone who can help resolve this." |

### Legal Questions

| Setting       | Value                                                                       |
| ------------- | --------------------------------------------------------------------------- |
| **Name**      | Legal Question Detection                                                    |
| **Detection** | Keyword + AI                                                                |
| **Keywords**  | lawyer, attorney, lawsuit, legal, contract dispute                          |
| **Prompt**    | Escalate questions about legal matters, liability, or contract terms        |
| **Message**   | "For legal matters, I'll connect you with someone who can properly assist." |

### VIP Customer

| Setting       | Value                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------ |
| **Name**      | VIP Customer Handling                                                                            |
| **Detection** | Attribute-based                                                                                  |
| **Condition** | Customer tier = "Enterprise"                                                                     |
| **Message**   | "Thank you for being a valued customer. I'm connecting you with your dedicated support contact." |

### Human Request

| Setting       | Value                                                                |
| ------------- | -------------------------------------------------------------------- |
| **Name**      | Explicit Human Request                                               |
| **Detection** | Keyword                                                              |
| **Keywords**  | speak to human, talk to person, real person, human agent, live agent |
| **Message**   | "Of course! I'm connecting you with a member of our team now."       |

## Testing Escalation Rules

{/* Screenshot: Escalation rule playground with test input and result */}

Use the built-in playground:

1. Open the escalation rule
2. Enter test messages
3. See if the rule triggers
4. Adjust detection criteria as needed

**Test scenarios to try:**

* Messages that should clearly trigger
* Messages that should clearly not trigger
* Edge cases and borderline situations

## Assigning to Agents

<Steps>
  <Step title="Open Agent Configuration">
    Go to **Build → Agents** and click on an agent.
  </Step>

  <Step title="Go to Guardrails Tab">
    Select the **Guardrails** tab.
  </Step>

  <Step title="Select Escalation Rules">
    Check the rules that should apply to this agent.
  </Step>

  <Step title="Save">
    Save the agent configuration.
  </Step>
</Steps>

## Best Practices

* **Test thoroughly** before activating
* **Start broader, then refine** — better to escalate too much initially
* **Review regularly** — analyze which rules trigger most
* **Balance sensitivity** — too sensitive = too many escalations
* **Provide context** — good internal notes help human agents

## Next Steps

<CardGroup cols={2}>
  <Card title="Restrictions" icon="ban" href="/guardrails/restrictions">
    Set hard limits on agent behavior
  </Card>

  <Card title="Guardrails Overview" icon="shield" href="/guardrails/overview">
    Back to overview
  </Card>
</CardGroup>