> ## Documentation Index
> Fetch the complete documentation index at: https://agentcontrol-docs-add-source-code-notes-to-examples.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Support Agent

> Full example with multiple tools, PII protection, and toxicity detection.

<Info>
  The source code for this example is available on GitHub:
  [Customer Support Agent](https://github.com/agentcontrol/agent-control/tree/main/examples/customer_support_agent)
</Info>

This example demonstrates how to integrate the `agent-control` SDK into an existing application. It simulates a **Customer Support Agent** - a realistic enterprise scenario that shows the key patterns for protecting AI agents with server-defined controls.

## Why This Example?

* **Universally understood use case**: Customer support is familiar to everyone
* **Natural need for guardrails**: PII protection, prompt injection defense
* **Multiple operation types**: LLM calls + tool calls (database, knowledge base, tickets)
* **Enterprise-relevant**: Shows patterns real companies would use

## Quick Start

```bash theme={null}
# 1. Install SDK and evaluators (first time only)
pip install -e sdks/python -e evaluators

# 2. Start all services (database, server, UI, demo controls)
./examples/customer_support_agent/demo.sh start

# 3. Run the demo
python examples/customer_support_agent/run_demo.py
```

The `demo.sh start` command:

* Starts PostgreSQL database
* Runs migrations
* Starts the API server ([http://localhost:8000](http://localhost:8000))
* Starts the UI ([http://localhost:4000](http://localhost:4000))
* **Registers the agent with demo controls** (PII detection, prompt injection)

When you open the UI, you'll see the agent with controls already configured.

### Other Commands

```bash theme={null}
# Check status of all services
./examples/customer_support_agent/demo.sh status

# Stop all services
./examples/customer_support_agent/demo.sh stop

# Reset everything (deletes database, asks for confirmation)
./examples/customer_support_agent/demo.sh reset
```

## Prerequisites

### First-Time Setup

1. **Install the SDK and evaluators**:

   ```bash theme={null}
   pip install -e sdks/python
   pip install -e evaluators
   ```

2. **Install UI dependencies**:

   ```bash theme={null}
   cd ui
   pnpm install
   ```

### Manual Setup (alternative to demo.sh)

If you prefer to run services manually:

<Steps>
  <Step title="Start the database (requires Docker)">
    ```bash theme={null}
    cd server
    docker compose up -d
    ```
  </Step>

  <Step title="Run database migrations">
    ```bash theme={null}
    cd server
    make alembic-upgrade
    ```
  </Step>

  <Step title="Start the server (Terminal 1)">
    ```bash theme={null}
    cd server
    make run
    ```

    Server runs at [http://localhost:8000](http://localhost:8000)
  </Step>

  <Step title="Start the UI (Terminal 2)">
    ```bash theme={null}
    cd ui
    pnpm dev
    ```

    UI runs at [http://localhost:4000](http://localhost:4000)
  </Step>
</Steps>

## Running the Demo

After `demo.sh start`, the agent already has demo controls configured. Just run:

```bash theme={null}
python examples/customer_support_agent/run_demo.py
```

Test different scenarios:

```text theme={null}
You: Hello, I need help with a refund
Agent: I understand you'd like a refund. Let me look into your order...

You: /test-pii
Running PII Detection Tests...
(Messages with SSN patterns will be blocked)

You: /test-injection
Running Prompt Injection Tests...
(Injection attempts will be blocked)

You: /quit
Goodbye!
```

### Automated Mode

Run all test scenarios automatically:

```bash theme={null}
python examples/customer_support_agent/run_demo.py --automated
```

### Reset Agent Controls

To remove all controls from the agent (keeps the agent registered):

```bash theme={null}
python examples/customer_support_agent/run_demo.py --reset
```

### Adding Custom Controls

1. Open [http://localhost:4000](http://localhost:4000)
2. Click on "Customer Support Agent" in the list
3. Click "Add Control" to create additional controls

See [Example Controls](#example-controls-to-configure) below for configuration examples.

## Available Commands

| Command           | Description                                |
| ----------------- | ------------------------------------------ |
| `/help`           | Show all commands                          |
| `/test-safe`      | Run safe message tests                     |
| `/test-pii`       | Test PII detection (if control configured) |
| `/test-injection` | Test prompt injection detection            |
| `/lookup <query>` | Look up customer (e.g., `/lookup C001`)    |
| `/search <query>` | Search knowledge base                      |
| `/ticket`         | Create a test support ticket               |
| `/quit`           | Exit the demo                              |

## Key Concepts

### 1. SDK Initialization

Initialize once at application startup:

```python theme={null}
import agent_control

agent_control.init(
    agent_name="Customer Support Agent",
    agent_id="646d5dea-c2e6-4453-b446-7035482b38e4",
    agent_description="AI-powered customer support assistant",
)
```

This:

* Registers the agent with the server
* Fetches the assigned policy and controls
* Enables the `@control()` decorator

### 2. Protecting Functions

Use the `@control()` decorator on any function you want to protect:

```python theme={null}
from agent_control import control

@control()
async def respond_to_customer(message: str) -> str:
    response = await llm.generate(message)
    return response
```

The decorator:

* Calls the server with `check_stage="pre"` before execution (validates input)
* Calls the server with `check_stage="post"` after execution (validates output)
* Raises `ControlViolationError` if a control triggers with "deny" action

### 3. Handling Violations

Catch `ControlViolationError` to provide graceful fallbacks:

```python theme={null}
from agent_control import ControlViolationError

try:
    response = await respond_to_customer(user_message)
except ControlViolationError as e:
    # Control triggered - return safe fallback
    print(f"Blocked by: {e.control_name}")
    response = "I cannot help with that request."
```

### 4. Controls are Server-Side

**Important**: Controls are defined on the server via the UI, not in code.

This design provides:

* **Centralized management**: Security team controls policies without code changes
* **Instant updates**: Change controls without redeploying agents
* **Audit trail**: Server logs all control evaluations
* **Separation of concerns**: Developers focus on features, security team on policies

## Project Structure

```bash theme={null}
customer_support_agent/
├── README.md                 # This file
├── demo.sh                   # Start/stop/reset script
├── setup_demo_controls.py    # Creates agent and demo controls
├── support_agent.py          # Main agent with SDK integration
└── run_demo.py               # Interactive demo runner
```

### demo.sh

Manages the full demo lifecycle:

* `start` - Starts database, server, UI, and sets up demo controls
* `stop` - Stops all services
* `reset` - Deletes database and stops services
* `status` - Shows service status

### setup\_demo\_controls.py

Creates the demo agent with pre-configured controls:

* `block-ssn-in-output` - Blocks responses containing SSN patterns
* `block-prompt-injection` - Blocks common injection attempts
* `block-credit-card` - Blocks credit card numbers in input

### support\_agent.py

Contains:

* SDK initialization
* Mock services (LLM, database, knowledge base, tickets)
* Protected functions with `@control()` decorator
* `CustomerSupportAgent` class with error handling

### run\_demo.py

Contains:

* Interactive chat loop
* Test command handlers (`/test-pii`, `/test-injection`, etc.)
* Automated test scenarios

## Example Controls to Configure

The demo setup creates three controls automatically. Here are examples of additional controls you might add:

### PII Detection (Post-check on output)

```yaml theme={null}
name: block-pii-in-output
scope:
  step_types: ["llm_inference"]
  stages: ["post"]
selector:
  path: output
evaluator:
  name: regex
  config:
    pattern: '\d{3}-\d{2}-\d{4}'  # SSN pattern
action:
  decision: deny
  message: "Response contains PII (SSN pattern)"
```

### Prompt Injection (Pre-check on input)

```yaml theme={null}
name: block-prompt-injection
scope:
  step_types: ["llm_inference"]
  stages: ["pre"]
selector:
  path: input
evaluator:
  name: regex
  config:
    pattern: '(?i)(ignore.*instructions|system:|you are now)'
action:
  decision: deny
  message: "Potential prompt injection detected"
```

### Toxic Content (Pre-check on input)

```yaml theme={null}
name: block-toxic-input
scope:
  step_types: ["llm_inference"]
  stages: ["pre"]
selector:
  path: input
evaluator:
  name: galileo.luna2
  config:
    stage_type: local
    metric: input_toxicity
    operator: gt
    target_value: 0.8
action:
  decision: deny
  message: "Inappropriate content detected"
```

## Testing the Integration

1. **Without controls**: Run the demo without configuring any controls. All messages should pass through.

2. **With PII control**: Add a PII detection control, then run `/test-pii`. Messages with SSN patterns should be blocked.

3. **With injection control**: Add a prompt injection control, then run `/test-injection`. Injection attempts should be blocked.

## Next Steps

* Explore the [main examples](/examples/overview) for more integration patterns
* Read the [SDK documentation](/sdk/python-sdk)

## Overview

This example demonstrates a customer support agent protected by Agent Control with multiple controls:

* **PII blocking** — Prevents SSN and credit card numbers in responses
* **Toxicity detection** — Blocks toxic or harmful user messages via Luna-2
* **Tool restriction** — Limits which tools the agent can invoke

## Source Code

See the full example on GitHub: [Customer Support Agent](https://github.com/agentcontrol/agent-control/tree/main/examples/customer_support_agent/)