smart-support/docs/agent-config-guide.md

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

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:

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.