Agent Model & Lifecycle

Agents are AI-powered workers that process your emails independently. Each agent has a specific purpose and runs autonomously.

What is an Agent?

An agent is a configured AI worker that:

• Watches your inbox - Checks for new emails every 60 seconds
• Filters intelligently - Uses triggers to find relevant emails
• Takes actions - Executes configured actions using tools
• Learns context - References knowledge base and memory
• Runs independently - Works alongside other agents simultaneously

Agent Lifecycle

Agents move through distinct states:

Processing Flow

Here's how an agent processes emails:

1. Account Agent (60s timer)
   ↓
2. Fetch new emails from Gmail
   ↓
3. Fan out to all active agents
   ↓
4. Agent filters emails (trigger matching)
   ↓
5. Two-stage AI processing:
   ├─ Glance: Quick relevance check (cheap model)
   └─ Full: Detailed processing with tools (if relevant)
   ↓
6. Execute actions via tools
   ↓
7. Log results for review

Stage 1: Glance Filtering

The agent first uses a cheap AI model to quickly filter emails:

{
  "relevant": true,
  "reason": "Email matches trigger: support inquiry",
  "confidence": 0.95
}

This reduces processing costs by ~80% by only fully processing relevant emails.

Stage 2: Full Processing

If an email passes the glance filter, the agent:

1. Analyzes context - Reads email content, thread history, attachments
2. Searches knowledge base - Looks up relevant documents
3. Checks memory - Recalls past interactions with sender
4. Decides actions - Determines what tools to use
5. Executes tools - Calls tools in sequence (up to 10 steps)
6. Logs results - Records all actions for review

Tool Execution Example

Here's what happens when an agent processes a support email:

Input Email:

From: customer@example.com
Subject: Password reset request
Body: I need to reset my password for account jane@example.com

Agent Configuration:

• Trigger: subject contains: password reset
• Action: Search knowledge base for password reset process. Reply with instructions and label as 'support-resolved'

Tool Execution Sequence:

// Step 1: Search knowledge base
searchDocuments({
  query: "password reset process instructions"
})
// Returns: Password reset documentation

// Step 2: Reply to customer
reply({
  to: "customer@example.com",
  subject: "Re: Password reset request",
  body: "Here's how to reset your password: [instructions]"
})

// Step 3: Label the email
label({
  labelIds: ["support-resolved"]
})

Result: Customer receives automated response, email is labeled, agent logs all actions.

Agent Architecture

Account Agent (One Per Gmail Account)

• Fetches emails once per account
• Fans out to all active agents
• Manages Gmail API connections
• Runs on 60-second alarm schedule

Email Agents (One Per Agent Configuration)

• Receives emails via POST from Account Agent
• Independent processing per agent
• Agent-specific configuration and state
• Isolated tool execution

Benefits:

• ✅ One Gmail fetch → many agents (efficient)
• ✅ Independent scaling per agent
• ✅ Agent isolation (one failure doesn't affect others)
• ✅ Per-agent configuration and state

Multi-Agent Coordination

Multiple agents can process the same email:

Example: Support email arrives

• Support Triage Agent - Labels and routes to correct team
• Auto-Reply Agent - Sends acknowledgment
• Analytics Agent - Tracks response time metrics

All agents run independently and can act on the same email without conflicts.

Agent State Management

Agents maintain state in Durable Objects:

• Processing locks - Prevents duplicate processing
• Configuration cache - Fast access to agent settings
• Agent-specific state - Custom state per agent
• Last processed timestamp - Tracks processing history

Cost Optimization

The two-stage processing model saves costs:

Glance filtering uses a cheaper model (gpt-5-mini) to quickly identify relevant emails before expensive full processing.

Next Steps

• Learn about agent configuration →
• Understand triggers and actions →
• Explore available tools →
• See agent examples →