VWO Recording Analysis Agent System

A multi-agent system for analyzing VWO session recordings using the Agent SDK and MCP (Model Context Protocol) integration.

Architecture

The system follows a Planner-Worker architecture:

User Message
    ↓
Planner Agent
    - Classify intent
    - Select capability
    - Check required inputs
    - Ask ONE question if missing
    ↓
Worker Agent
    - Call get_recording_data_tool (MCP)
    - Analyze recordings
    - Produce insights
    ↓
User Response

Components

1. Planner Agent (agent/planner_agent.py)

• Purpose: Understand user intent and create execution plans

• Responsibilities:

  • Classify user requests related to session recordings
  • Select appropriate capabilities (session_analysis, journey_mapping, friction_identification)
  • Validate required inputs (time range, page/funnel, segment)
  • Ask clarifying questions if data is missing
  • Output structured JSON execution plan

• Output Format:

{
  "status": "need_clarification" | "ready_for_execution",
  "capabilities": ["session_analysis"],
  "required_inputs": {
    "start_time": "2026-01-20T00:00:00",
    "end_time": "2026-01-27T23:59:59",
    "limit": 50
  },
  "clarifying_question": "..." | null
}

2. Worker Agent (agent/worker_agent.py)

• Purpose: Execute analysis plans and produce insights

• Responsibilities:

  • Execute the requested recording_analysis capability
  • Call get_recording_data_tool via MCP
  • Analyze behavior patterns objectively
  • Produce concise, actionable responses

• Rules:

  • NEVER asks clarifying questions
  • NEVER changes scope or capability
  • NEVER mentions tools or internal steps
  • ONLY operates on provided inputs

3. MCP Client (agent/mcp_client.py)

• Purpose: Handle communication with VWO MCP server
• Endpoint: https://mcp.vwo.io/mcp?key={DEV_API_TOKEN}
• Tool: get_recording_data_tool

Tool Parameters:

{
  "start_time": str,      # Required: ISO format timestamp
  "end_time": str,        # Required: ISO format timestamp
  "limit": int,           # Optional: default 50
  "campaign_id": int,     # Optional: filter by campaign
  "segment_description": str  # Optional: filter by segment
}

4. Orchestrator (agent/orchestrator.py)

• Purpose: Coordinate the entire flow between agents
• Flow:
  1. Receives user message
  2. Runs Planner Agent to create execution plan
  3. If clarification needed → returns question to user
  4. If ready → runs Worker Agent with MCP tool access
  5. Returns final insights to user

Capabilities

The system supports three recording analysis capabilities:

1. session_analysis: Analyze individual session recordings for user behavior patterns
2. journey_mapping: Map user journeys across pages and funnels
3. friction_identification: Identify friction points and drop-off locations

Usage

Running the CLI

# Start the interactive chat
python -m cli.main chat

# With debug mode
python -m cli.main chat --debug

Example Interactions

Example 1: Missing time range

User: Show me sessions with high friction
Planner: What time range would you like to analyze? (e.g., last 7 days, specific dates)
User: Last 7 days
Worker: [Analyzes recordings and provides friction insights]

Example 2: Complete request

User: Analyze user journeys from Jan 20 to Jan 27 for campaign 12345
Planner: [Creates execution plan with all required inputs]
Worker: [Provides journey mapping insights]

Note: The CLI supports conversational flow. When the Planner asks a clarifying question, it's returned as a regular response. You can answer it in your next message, and the system will process your answer. Each message is treated independently, so provide complete information in your follow-up responses.

File Structure

agentic_app/
├── agent/
│   ├── __init__.py
│   ├── mcp_client.py          # MCP server communication
│   ├── planner_agent.py       # Intent classification & planning
│   ├── worker_agent.py        # Execution & analysis
│   ├── orchestrator.py        # Agent coordination
│   ├── runner.py              # Main entry point
│   └── output_contract.py     # Response data structures
├── cli/
│   └── main.py                # CLI interface
├── .env                       # Environment variables
└── requirements.txt

Environment Variables

Required in .env:

DEV_API_TOKEN=<your_vwo_api_token>
AZURE_OPENAI_API_KEY=<your_azure_key>
AZURE_OPENAI_ENDPOINT=<your_azure_endpoint>
AZURE_OPENAI_API_VERSION=2025-03-01-preview
OPENAI_AGENTS_DISABLE_TRACING=1

Key Design Decisions

1. Separation of Concerns: Planner handles intent/planning, Worker handles execution
2. MCP Integration: All MCP calls handled within agent/ folder via mcp_client.py
3. No Direct Tool Access: Planner never calls tools, only creates plans
4. Single Clarification: Planner asks ONE question at a time if data is missing
5. Structured Output: Planner outputs JSON for reliable parsing
6. Tool Registration: Worker agent registers MCP tool via Agent SDK's tool system

Error Handling

• Invalid JSON from Planner: Returns error message with raw output
• Missing Required Fields: Validation catches and reports specific issues
• MCP Server Errors: Wrapped and returned as user-friendly messages
• Insufficient Data: Worker states clearly without asking questions

Testing the System

You can test with queries like:

• "Show me sessions from last week"
• "Analyze user journeys for campaign 123"
• "Find friction points in the checkout funnel"
• "What are users doing on the homepage?"

The Planner will ask for missing information (time range, specific pages, etc.) before the Worker executes the analysis.