Agents

Create and configure specialist agents that process emails with AI intelligence.

Overview

Agents are the heart of ExecAssist's email processing system. Each agent is a specialized AI worker configured with specific instructions, tools, and an LLM model. Agents receive emails from monitored mailboxes and take intelligent action.

Agent Architecture

The SuperAgent System

ExecAssist uses a two-tier agent architecture:

Incoming Email
    ↓
SuperAgent (Router)
    ↓ Analyzes content, sender, context
    ↓
Routes to Best Specialist Agent
    ↓
Specialist Agent Processes Email
    ↓
Response/Action Taken

SuperAgent:

• Receives all incoming emails
• Analyzes email content and metadata
• Routes to the most appropriate specialist
• Handles fallback when no specialist matches

Specialist Agents:

• Focus on specific domains (support, sales, HR, etc.)
• Have tailored instructions and tools
• Process emails end-to-end

Creating an Agent

Step 1: Navigate to Agents

Go to Build > AI Agents > Agents and click Add Agent. This opens a dedicated form page for creating the agent.

Step 2: Basic Configuration

Field	Description	Example
Name	Descriptive name	"Customer Support Agent"
Description	Brief purpose description	"Handles customer inquiries and issues"
Status	Active or inactive	Active

Step 3: Select Model

Choose the LLM model for this agent:

Model	Best For
Claude Haiku	Simple tasks, high volume
Claude Sonnet	General purpose, balanced
Claude Opus	Complex reasoning
GPT-4	Complex tasks
GPT-3.5	Simple, cost-effective

Step 4: Configure Parameters

Parameter	Description	Recommended
Temperature	Creativity level (0-1)	0.7 for support, 0.3 for factual
Max Tokens	Response length limit	1000-2000
Top P	Response diversity	0.9

Step 5: Write Instructions

Instructions (system prompt) are the most important part of agent configuration. They define:

• Agent's role and personality
• How to handle different situations
• What information to use
• When to escalate

Instruction Template

## Role
You are a [role] for [company]. Your primary responsibility is to [main task].

## Guidelines
1. [Guideline 1]
2. [Guideline 2]
3. [Guideline 3]

## Response Style
- Be [tone] and [style]
- Keep responses [length guidance]
- Use [formatting preferences]

## Important Rules
- Never [prohibited action]
- Always [required action]
- When unsure, [fallback behavior]

## Tool Usage
- Use [tool] when [condition]
- Search knowledge base before [action]
- Escalate when [criteria]

Example: Customer Support Agent

## Role
You are a customer support specialist for TechCorp. Your primary responsibility is to help customers resolve issues and answer questions about our products.

## Guidelines
1. Always greet customers warmly and professionally
2. Search the knowledge base before responding to ensure accuracy
3. If you cannot resolve an issue, escalate to human support
4. Follow up on any commitments made in previous emails

## Response Style
- Be friendly but professional
- Keep responses concise but complete
- Use bullet points for multiple items
- Include relevant links when helpful

## Important Rules
- Never share internal pricing or confidential information
- Always verify customer identity for account-related requests
- When unsure about a policy, escalate rather than guess

## Tool Usage
- Use search_knowledge_base for product questions
- Use lookup_employee to find the right internal contact
- Use request_human_input for:
  - Refund requests over $100
  - Legal or compliance issues
  - Angry or threatening customers

Step 6: Assign Tools

Select the tools this agent can use. Tools are organized by category, and you can expand each category to see available tools.

Essential for most agents:

• reply_to_email - Send responses
• request_human_input - Request human input or approval

Information gathering:

• search_knowledge_base - Look up information
• lookup_employee - Find employee data
• lookup_vip - Check VIP status

Specialized:

• Calendar tools for scheduling agents
• SQL tools for data retrieval
• API tools for integrations

Subscription Tier Gating

Some tools require a higher subscription tier. Tools that are unavailable on your current plan are:

• Disabled (cannot be selected)
• Shown with an "Upgrade" badge indicating the required tier

If you need access to gated tools, upgrade your subscription through Admin > Account > Subscription.

Step 7: Configure Sender Restrictions

The Sender Restrictions tab controls which email senders this agent is allowed to process. This is a security feature that helps prevent agents from processing emails from unauthorized sources.

Restriction Modes

Mode	Description
Anyone	Process emails from any sender (default)
Internal Only	Only process emails from senders within your organization's verified domains
Custom	Define specific rules for allowed senders

Custom Restriction Rules

When using Custom mode, you can configure one or more rules. Emails are allowed if they match any of the defined rules (OR logic):

Rule Type	Description	Example
Allowed Domains	Accept emails from specific domains	@example.com, @partner.org
Allowed Emails	Accept specific email addresses	vip@customer.com
Allowed Title Patterns	Accept based on sender job titles (wildcards supported)	CEO, *Director*, VP *

Additional Security Options

Option	Description	Default
Require TO Field Position	Only process if agent's mailbox is in the TO field (not CC/BCC)	Off
Allow Thread Continuation	Allow replies in existing threads even if sender doesn't match rules	On
Require Email Authentication	Require emails pass SPF/DKIM/DMARC verification	Off

Note: Email authentication verification checks the email headers for SPF, DKIM, and DMARC authentication results. This helps prevent processing of spoofed emails.

Auto-Reply for Blocked Emails

When emails are blocked by sender restrictions, you can optionally send an automatic reply:

1. Enable Send Auto-Reply When Blocked
2. Configure the Subject (default: "Your message could not be processed")
3. Write a custom Message explaining why the email was not processed

This helps senders understand why they didn't receive a response from the agent.

Step 6.6: Configure Execution Limits

The Execution Limits tab controls how long an agent can run and how many actions it can take in a single execution.

Setting	Description	Default	Range
Max Tool Calls	Maximum number of tool calls per execution	20	1-100
Max Execution Time	Maximum execution duration in seconds	300	60-3600

When to adjust these limits:

• Increase Max Tool Calls for agents that need to perform many actions (e.g., processing multiple items, complex research)
• Increase Max Execution Time for agents using slow external APIs or performing complex reasoning
• Decrease limits to control costs and prevent runaway executions

Warning: Setting very high limits can result in expensive executions if an agent gets stuck in a loop or encounters unexpected situations.

Step 6.7: Configure Long-Running Tasks (Advanced)

For tasks that span multiple days or require the agent to wait for external events, enable long-running task support. This allows agents to pause their work and automatically resume later.

When to Use Long-Running Tasks

Long-running tasks are ideal for:

• Multi-day workflows - Projects that require work spread across several days
• Waiting for responses - Tasks where the agent needs to wait for someone to reply
• Scheduled follow-ups - Checking on status at specific intervals
• Complex research - Tasks that benefit from periodic resumption

Long-Running Task Settings

Setting	Description	Default
Enable Long-Running Tasks	Master toggle for multi-session support	Off
Enable Per-Tool Checkpoints	Save state after each tool call for automatic recovery	Off
Resume Interval (hours)	How long to wait before auto-resuming after timeout	1 hour
Max Sessions Per Task	Maximum number of resume sessions before abandoning	10

How It Works

1. Pause and Resume: When enabled, the agent gains access to the pause_and_schedule_resume tool. It can pause execution and schedule when to continue.

2. Automatic Checkpoints: If per-tool checkpoints are enabled, the agent's state is saved after each tool call. If execution is interrupted unexpectedly (e.g., timeout, error), it can automatically resume from the last checkpoint.

3. Session Continuity: When resuming, the agent receives context about:

   • What it was working on
   • How much time has passed
   • What its last action was
   • Any notes it left for itself

4. Session Limits: The Max Sessions Per Task setting prevents endless loops. Once reached, the task is abandoned and escalated.

Example: Research Agent

A research agent configured with long-running tasks enabled might:

1. Receive a request to research a topic
2. Gather initial information
3. Pause execution with a note: "Initial research complete. Resume in 24 hours to check for new publications."
4. Resume the next day to continue research
5. Compile findings and respond

Instructions for Long-Running Agents

When writing instructions for agents with long-running task support, include guidance on:

## Long-Running Task Guidelines
- Use pause_and_schedule_resume when you need to wait for external events
- Leave detailed notes about your progress and next steps
- Schedule resume times based on when information is likely to be available
- If you've been working on this for several sessions, summarize progress so far
- Escalate if you're unable to make progress after multiple sessions

Note: Long-running task settings are in the Execution Limits tab of the agent configuration form.

Using Sample Agent Templates

When creating a new agent, you can start from a template:

1. Click the Use a template dropdown
2. Select a sample agent template
3. The form auto-fills with pre-configured instructions, settings, and tool assignments
4. Customize as needed for your use case

Sample agent templates are managed in Admin > Global Admin > Sample Agents.

Step 8: Save and Test

1. Click Save to create the agent
2. The form page closes and returns you to the agents list
3. Assign to a mailbox for testing
4. Send test emails to verify behavior
5. Review executions and adjust instructions

Testing Agents with Chat

For existing agents, you can test behavior interactively without sending emails using the built-in Test Chat feature.

Opening the Chat Panel

1. Navigate to Build > AI Agents > Agents
2. Click on an existing agent to open the edit form
3. Click the Test Chat button in the form header
4. A chat panel slides in from the right side of the screen

Using the Chat Panel

The chat panel provides a real-time testing interface:

• Send messages - Type in the input field and press Enter (or click Send)
• View streaming responses - Watch the agent's response appear token-by-token
• Multi-turn conversations - Continue the conversation with follow-up messages
• Tool usage indicators - See when the agent uses tools during its response

Chat Panel Features

Feature	Description
Real-time streaming	Responses appear as they're generated, token by token
Tool execution	View which tools the agent calls during processing
Connection status	Indicator shows SignalR connection state
New conversation	Start fresh conversations without closing the panel
Keyboard shortcuts	Escape to close, Enter to send, Shift+Enter for newlines

Viewing Chat Execution Logs

Chat conversations create execution logs just like email processing:

1. Go to Operations > Activity > Agent Executions
2. Filter by the agent you tested
3. Chat executions appear alongside email executions
4. Click any execution to view the detailed timeline

The execution details show:

• Full conversation context sent to the LLM
• Token-by-token response generation
• Tool calls and their results
• Timing and cost metrics

When to Use Test Chat vs. Test Emails

Scenario	Recommended Approach
Quick instruction testing	Test Chat
Testing email-specific features	Send test email
Iterating on prompts	Test Chat
Testing VIP handling	Send test email
Validating tool usage	Test Chat
Testing sender restrictions	Send test email

Note: Test Chat bypasses email-specific features like sender restrictions, VIP detection, and thread handling. For complete integration testing, send actual test emails.

AI-Assisted Instruction Improvement

Using the Improve Feature

1. Write initial instructions
2. Click Improve with AI
3. Review suggested improvements
4. Accept, modify, or reject suggestions
5. Iterate until satisfied

What AI Improves

• Clarity and specificity
• Edge case handling
• Tool usage guidance
• Tone and style consistency
• Error prevention

Managing Agents

Agent List View

The agents page organizes agents into tabs:

Tab	Description
Agents	Standard email processing agents
SMEs	Subject Matter Expert agents (specialized knowledge agents)
Test Agents	Agents with "test" in their name (for development/testing)
Deleted	Soft-deleted agents (read-only archive)

The agents table shows:

• Name - Agent identifier
• Description - Brief summary
• Model - Assigned LLM model
• Status - Active/Inactive
• Mailbox - Assigned monitored mailbox
• Tools - Number of assigned tools

Editing Agents

1. Click on an agent row or the edit icon
2. This opens the agent's form page
3. Modify configuration as needed
4. Click Save

Note: Changes take effect immediately for new executions. In-progress executions use the previous configuration.

Cloning Agents

To create a new agent based on an existing one:

1. Click the clone icon (copy) next to an agent
2. A new agent form opens pre-filled with the source agent's configuration
3. Give the new agent a unique name
4. Make any desired modifications
5. Click Save

Deactivating Agents

1. Edit the agent
2. Set status to Inactive
3. Save

Inactive agents won't process new emails but remain in the system for reference.

Deleting Agents

1. Click the delete icon
2. Confirm deletion

When you delete an agent:

• The agent is soft-deleted (not permanently removed)
• It moves to the Deleted tab
• Any assigned mailboxes are automatically unassigned
• All execution history and logs are preserved
• The agent can be viewed in read-only mode from the Deleted tab

Note: Soft delete preserves agent configuration and execution history for audit purposes. Deleted agents cannot be restored through the UI.

Viewing Deleted Agents

1. Navigate to the Deleted tab
2. Click on any deleted agent to view its configuration
3. The agent opens in read-only mode with a "DELETED - Read Only" badge
4. You can review all settings but cannot make changes

Agent History

Every time an agent is edited, the previous version is automatically archived. This allows you to:

• Track all changes made to agent configurations over time
• See who made changes and when
• Review historical instructions if behavior changes unexpectedly
• Audit agent configuration for compliance purposes

Note: Agent history is stored in the database and is not currently visible through the UI. Contact your administrator for historical queries.

Agent Best Practices

Instruction Writing

1. Be specific - Vague instructions lead to inconsistent behavior
2. Provide examples - Show expected input/output pairs
3. Define boundaries - What should the agent NOT do?
4. Include fallbacks - What happens when the agent is uncertain?

Tool Assignment

1. Minimum necessary - Only assign tools the agent needs
2. Guide usage - Instructions should explain when to use each tool
3. Test combinations - Verify tools work together as expected

Model Selection

1. Match complexity - Simple tasks don't need expensive models
2. Consider cost - Balance quality vs. budget
3. Test and compare - Try different models and measure quality

Monitoring

1. Review executions - Regularly check agent performance
2. Track metrics - Monitor success rate, cost, response time
3. Act on feedback - Use user feedback to improve instructions
4. Iterate - Continuously refine based on real-world usage

Common Agent Types

Customer Support Agent

Purpose: Handle customer inquiries and issues

Key tools: reply_to_email, search_knowledge_base, request_human_input

Instructions focus:

• Product knowledge
• Support policies
• Escalation criteria

Scheduling Agent

Purpose: Handle meeting requests and calendar management

Key tools: check_calendar_availability, create_calendar_event, reply_to_email

Instructions focus:

• Scheduling preferences
• Buffer time requirements
• Priority handling

Triage Agent

Purpose: Route emails to appropriate handlers

Key tools: request_human_input, lookup_vip

Instructions focus:

• Classification criteria
• Routing rules
• Priority levels

Information Agent

Purpose: Answer questions using knowledge bases

Key tools: search_knowledge_base, reply_to_email

Instructions focus:

• Search strategies
• Response formatting
• Source citation

Troubleshooting

Agent Not Processing Emails

Symptoms: Emails arrive but no executions occur

Solutions:

1. Verify agent is active
2. Check mailbox subscription is active
3. Confirm agent is assigned to the mailbox
4. Review ignore rules that might be filtering emails

Poor Response Quality

Symptoms: Agent responses are wrong or unhelpful

Solutions:

1. Review and improve instructions
2. Add more examples and guidance
3. Consider upgrading to a more capable model
4. Check if knowledge base has needed information

Agent Errors

Symptoms: Executions fail with errors

Solutions:

1. Check execution details for error messages
2. Verify tool configurations are correct
3. Ensure LLM provider is working
4. Review recent changes to agent configuration

High Costs

Symptoms: Agent costs more than expected

Solutions:

1. Review token usage in executions
2. Optimize instructions (shorter = fewer tokens)
3. Consider a smaller model
4. Check for unnecessary tool calls

Emails Being Blocked by Sender Restrictions

Symptoms: Legitimate emails are not being processed

Solutions:

1. Check the agent's Sender Restrictions tab configuration
2. If using Internal Only, verify the sender's domain is in your organization
3. If using Custom mode:
   • Add the sender's domain to Allowed Domains
   • Or add the specific email to Allowed Emails
4. If Require Email Authentication is enabled, verify the sender's email passes SPF/DKIM/DMARC
5. If the agent is CC'd, check if Require TO Field Position is enabled
6. Check if Allow Thread Continuation is disabled for reply threads

Long-Running Task Issues

Symptoms: Long-running agent doesn't resume or completes unexpectedly

Solutions:

1. Check if the agent has "Enable Long-Running Tasks" turned on
2. Verify the execution hasn't reached the "Max Sessions Per Task" limit
3. Review the agent's instructions for proper use of pause_and_schedule_resume
4. Check the Scheduled Reminders page to see if a resume is pending
5. Look for errors in the execution logs that might have prevented checkpoint saving

Symptoms: Agent keeps resuming but making no progress

Solutions:

1. Review agent instructions - ensure it has clear guidance on when to escalate
2. Lower the "Max Sessions Per Task" limit to prevent endless loops
3. Add instructions to summarize progress and identify when the task is stuck
4. Consider disabling long-running tasks if the use case doesn't require it

Related Topics

• Tools
• LLM Providers
• Monitored Mailboxes
• Agent Executions
• Scheduled Reminders