AI Agents for Email

The email system uses AI agents to handle incoming emails intelligently. Each agent has its own personality, system prompt, and can be assigned to specific workflows or used as defaults.

Agent Concepts

What is an Email Agent?

An email agent is an AI assistant configured to handle email conversations. Each agent has:

• System Prompt: Defines the agent's personality, role, and behavior
• Name: Used in email signatures
• Email Signature: Optional custom signature text appended to emails
• Default Settings: Can be set as default for email channel or all channels

Agent Selection Priority

When an email arrives, the system selects an agent in this order:

1. Workflow-Assigned Agent: If a workflow has an assistant_id, that agent is used
2. Routing Rules: If routing rules match the email content/intent, the target agent is selected
3. Default Email Agent: The agent marked as is_default_email = true for the tenant
4. General Default: The agent marked as is_default = true (fallback)

Agent Assignment

Once an agent is selected:

• The agent is assigned to the conversation
• Assignment is recorded in email_agent_assignments table
• The conversation's assistant_id is updated
• All responses from that conversation use the assigned agent

Configuring Agents for Email

Setting Up an Email Agent

1. Navigate to Assistants page
2. Create or edit an assistant
3. Configure the agent:
   • Name: This will appear in email signatures
   • System Prompt: Define how the agent should respond to emails
   • Email Signature: Optional custom signature (company info, contact details, etc.)
   • Default for Email: Check to make this the default email agent

Email Signature Format

Email signatures are automatically generated with:

1. Random Signoff: One of: Thanks, Cheers, Best, Regards, Sincerely, Warm regards, Best regards, Kind regards, Thank you, Take care
2. Agent Name: The name configured for the agent
3. Custom Signature: Optional text from the agent's email signature field

Example signature:

Best regards,
Sarah Johnson
Customer Success Manager
Acme Corp
support@acme.com

System Prompt Best Practices

When writing system prompts for email agents:

• Be Specific: Clearly define the agent's role and expertise
• Set Tone: Specify professional, friendly, technical, etc.
• Include Context: Reference business information, services, policies
• Define Boundaries: What the agent can and cannot do
• Provide Examples: Show desired response style

Example:

You are Sarah, a customer success manager for Acme Corp, a web hosting company.
You are friendly, professional, and solution-oriented. You help customers with:
- Account questions
- Billing inquiries
- Technical support escalations
- Service recommendations

Always be empathetic and aim to resolve issues quickly. If you cannot help,
politely escalate to the appropriate team.

Workflows with Agents

Assigning Agents to Workflows

When creating or editing a workflow, you can assign a specific agent:

1. In the workflow form, select an Agent from the dropdown
2. This agent will handle all emails matching that workflow
3. The agent uses the workflow context as guidance (not as a template)

How Agents Use Workflows

Workflows provide guidance to agents, not rigid templates:

• Workflow Context: Business information, services, pricing (used as reference)
• Response Template: Tone and structure guidance (agent adapts naturally)
• Workflow Steps: Instructions for what to do (extract info, create tickets, etc.)

The agent generates natural, conversational responses while following workflow guidance.

Example: Sales Workflow with Agent

Workflow Context:

We offer three hosting plans:
- Starter: $29/month (10GB storage, 100GB bandwidth)
- Professional: $79/month (100GB storage, 1TB bandwidth)
- Enterprise: $199/month (unlimited storage and bandwidth)

Agent Response (not template):

Hi John,

Thanks for your interest in our hosting services! Based on your needs for a small business website, I'd recommend our Professional plan at $79/month. It includes 100GB storage and 1TB bandwidth, which should be perfect for your requirements.

Would you like me to set up a trial account so you can test it out?

Best regards,
Sarah Johnson
Customer Success Manager

Agent Handoffs

When Handoffs Happen

Agents can hand off emails to other agents when:

• Routing Rules Match: A routing rule detects specific keywords or intents
• Specialization Needed: The current agent determines another agent is better suited
• Escalation Required: Complex issues need specialized expertise

Routing Rules for Email

Create routing rules to automatically hand off emails:

1. Navigate to Routing Rules page
2. Create a rule with:
   • Trigger Keywords: Words that indicate a handoff is needed
   • Trigger Intent: Intent classification (sales, support, billing, technical)
   • Target Agent: The agent to hand off to
   • Channels: Include "email" in the channels list

Example rule:

• Trigger Keywords: ["refund", "cancel", "billing issue"]
• Trigger Intent: "billing"
• Target Agent: "Billing Specialist"
• Channels: ["email"]

Handoff Process

When a handoff occurs:

1. Current agent generates a handoff message
2. Conversation is transferred to the new agent
3. Handoff message is queued and sent with delay
4. Handoff history is recorded in conversation metadata
5. Future emails in the conversation use the new agent

Handoff Guardrails

To prevent excessive handoffs and ensure a smooth customer experience, the system includes configurable guardrails:

Maximum Handoffs Per Conversation

• Limits the total number of times a conversation can be transferred between agents
• Default: 3 handoffs per conversation
• Range: 1-10
• Prevents conversations from being passed around indefinitely

Cooldown Period

• Prevents rapid successive handoffs
• Two settings:
  • Minimum Messages: Number of messages required before next handoff (default: 2)
  • Minimum Minutes: Time in minutes required before next handoff (default: 5)
• Both conditions must be met before another handoff is allowed

Loop Prevention

• Prevents handoff loops (e.g., Agent A → Agent B → Agent A → Agent B)
• Checks if target agent was used in the last 2 handoffs
• Default: Enabled
• Prevents frustrating back-and-forth transfers

Time-Based Limits (Optional)

• Maximum handoffs per hour per conversation
• Prevents excessive handoffs within a short time window
• Default: No limit (null)
• Can be set to any positive number (e.g., 2 handoffs per hour)

Configuring Guardrails

1. Navigate to Handoff Settings page
2. Scroll to Guardrail Settings section
3. Configure each setting:
   • Maximum Handoffs Per Conversation: Set limit (1-10)
   • Cooldown Settings: Set minimum messages and minutes
   • Prevent Handoff Loops: Toggle on/off
   • Maximum Handoffs Per Hour: Set limit or leave empty for no limit
4. Click Save Settings

Guardrail Behavior

When a handoff would violate a guardrail:

• The handoff is prevented
• An error message explains why (e.g., "Maximum handoffs per conversation reached (3)")
• The conversation remains with the current agent
• The customer continues with the same agent without interruption

This ensures customers aren't frustrated by excessive transfers while still allowing necessary handoffs for specialized assistance.

Conversational AI Without Workflows

When No Workflow Matches

If an email doesn't match any workflow:

• System selects default email agent or general assistant
• Agent uses conversational AI with:
  • Agent's system prompt
  • Email context library entries
  • Cross-channel conversation history
  • Business information from tenant config
• Agent generates natural, helpful response
• Response is still queued with delay

Best Practices

• Set Default Email Agent: Always have a default email agent configured
• Use Context Library: Add business information to context library for all agents
• Monitor Conversations: Review agent responses and adjust system prompts
• Test Handoffs: Verify routing rules work correctly

Response Timing

Natural Delays

All email responses are queued with a 5-15 minute random delay to:

• Appear more human-like
• Avoid immediate automated responses
• Give agents time to "think" about responses

Queue Processing

• Email queue worker processes queued emails every 2 minutes
• Emails are sent when their scheduled time arrives
• Failed sends are retried with exponential backoff (max 3 retries)

Monitoring Agent Performance

View Agent Assignments

In Email Conversations page:

• See which agent handled each conversation
• View handoff history if agents were transferred
• Review agent signatures in email previews

Agent Assignment History

The email_agent_assignments table tracks:

• Which agent was assigned
• When the assignment happened
• Why the agent was selected (workflow_match, intent_based, handoff, default, routing_rule)

Best Practices

1. Create Specialized Agents: Different agents for sales, support, billing, etc.
2. Use Descriptive Names: Agent names appear in signatures, make them professional
3. Keep System Prompts Updated: Update prompts as business needs change
4. Test Agent Responses: Send test emails to verify agent behavior
5. Monitor Handoffs: Review handoff patterns to optimize routing rules
6. Customize Signatures: Add company info, titles, contact details to signatures

Next Steps

• Workflows Guide - Learn about workflow configuration
• Routing Rules - Set up agent handoffs
• Troubleshooting - Resolve agent issues