# 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_agent
    description: "Handles order status, tracking, and cancellations."
    permission: write
    tools:
      - get_order_status
      - cancel_order
    personality:
      tone: friendly
      greeting: "I can help with your order. What is your order number?"
      escalation_message: "I'm escalating this to a human agent now."

  - name: refund_agent
    description: "Processes refund requests."
    permission: write
    tools:
      - process_refund
      - check_refund_eligibility
    personality:
      tone: empathetic
      greeting: "I'm the refund specialist. How can I help?"
      escalation_message: "I need to escalate this refund request."

  - name: general_agent
    description: "Answers general questions and FAQs."
    permission: read
    tools:
      - search_faq
      - 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.
- `admin` -- requires human approval and is logged for audit.

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

### `personality` (optional)
Customizes agent behavior:
- `tone` -- `friendly`, `formal`, `empathetic`, `technical`
- `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 | Description |
|----------|-------------|
| `ecommerce` | Orders, refunds, shipping, product questions |
| `saas` | Account management, billing, technical support |
| `generic` | General-purpose FAQ and escalation |

Example:
```bash
TEMPLATE_NAME=ecommerce 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 by calling the `escalate` tool. 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.