# Agent Configuration Guide

## Overview

Smart Support agents are defined in `backend/agents.yaml`. Each agent is a
specialist with a specific role, permission level, and set of tools it can call.

## agents.yaml Structure

```yaml
agents:
  - name: order_lookup
    description: "Looks up order status and tracking information."
    permission: read
    tools:
      - get_order_status
      - get_tracking_info
    personality:
      tone: "friendly and informative"
      greeting: "I can help you check your order status!"
      escalation_message: "Let me connect you with our support team."

  - name: order_actions
    description: "Performs order modifications like cancellations."
    permission: write
    tools:
      - cancel_order
    personality:
      tone: "careful and reassuring"
      greeting: "I can help you with order changes."
      escalation_message: "I'll connect you with a specialist."

  - name: discount
    description: "Applies discounts and generates coupon codes."
    permission: write
    tools:
      - apply_discount
      - generate_coupon

  - name: fallback
    description: "Handles general questions and unclear requests."
    permission: read
    tools:
      - fallback_respond
```

## Fields

### `name` (required)
Unique identifier used for routing. Must be alphanumeric with underscores.

### `description` (required)
Plain-text description of what this agent handles. Used by the supervisor to route
user messages to the right agent. Be specific.

### `permission` (required)
Controls the interrupt threshold:
- `read` -- no interrupt required. Agent can act immediately.
- `write` -- requires human approval via interrupt before executing tools.

### `tools` (required)
List of tool names this agent can use. Tools are registered in `backend/app/agents/`.
Each tool name must match a registered LangChain tool.

Available built-in tools:
- `get_order_status` -- look up order details
- `get_tracking_info` -- get shipping/tracking info
- `cancel_order` -- cancel an order (write)
- `apply_discount` -- apply a discount code (write)
- `generate_coupon` -- generate a new coupon (write)
- `fallback_respond` -- generic fallback response

### `personality` (optional)
Customizes agent behavior:
- `tone` -- free-text description of the agent's communication style
- `greeting` -- opening message injected at session start
- `escalation_message` -- message sent when the agent escalates

## Built-in Templates

Use `TEMPLATE_NAME` environment variable to load a pre-built agent configuration:

| Template | Filename | Description |
|----------|----------|-------------|
| `e-commerce` | `templates/e-commerce.yaml` | Orders, shipping, discounts |
| `saas` | `templates/saas.yaml` | Account management, billing, support |
| `fintech` | `templates/fintech.yaml` | Financial services support |

Example:
```bash
TEMPLATE_NAME=e-commerce uvicorn app.main:app
```

## Adding New Agents

1. Add agent definition to `agents.yaml`.
2. Register any new tools in `backend/app/agents/`.
3. Restart the backend.

The supervisor will automatically route to the new agent when the user's intent
matches the agent's description.

## Agent Routing Logic

1. User sends a message.
2. The LLM supervisor classifies the intent against all agent descriptions.
3. If unambiguous, the matching agent is invoked directly.
4. If ambiguous (multiple plausible agents), the system asks a clarification question.
5. If multi-intent, agents are invoked sequentially.

## Escalation

Any agent can trigger escalation. This:
1. Sends a webhook notification (if `WEBHOOK_URL` is configured).
2. Marks the conversation with `resolution_type = escalated`.
3. Sends the agent's `escalation_message` to the user.