be5c84bcff
README: - Remove duplicated agent config, safety, security sections (covered by docs) - Add ux_design_system.md and safety.py to project structure and doc links - Convert doc links to descriptive table agent-config-guide.md: - Replace fictional agents/tools with real ones from agents.yaml - Remove nonexistent 'admin' permission level (only read/write) - Fix template names (e-commerce, saas, fintech) - List all available built-in tools openapi-import-guide.md: - Fix /result -> /classifications endpoint - Fix POST /approve to show no request body - Remove nonexistent 'admin' access type - Update response examples to match actual API demo-script.md: - Fix agent names (order_agent -> order_lookup) - Replace fictional refund scenario with real lookup+cancel flow ARCHITECTURE.md: - Fix langgraph-supervisor version (v1.1 -> 0.0.12+) docker-compose.yml: - Expose postgres on port 5433 for local dev
117 lines
3.6 KiB
Markdown
117 lines
3.6 KiB
Markdown
# 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.
|