feat: Design & Implement Core Application Agent with LangGraph

[braden-seaborn]

Description

Design and develop the primary application agent responsible for automating scholarship application workflows. This agent will analyze forms, make decisions, and execute actions via the Playwright browser in AI Orchestrator.

Background

With the streaming service integrated, we can now build the intelligent agent that controls the automation. This issue focuses specifically on the Application Agent - the core agent that handles individual scholarship applications from start to finish.

Phase 1: Design Document (Required Before Implementation)

Design Deliverable

Create a comprehensive design document using draw.io that includes:

1. Agent Architecture Diagram

• Agent components and their responsibilities
• Integration points with AI Orchestrator/Playwright
• Communication flow with LangGraph
• Data flow between agent and user profile/application models

2. Application Workflow State Machine

• LangGraph state nodes for each application phase:
  • Initial page analysis
  • Form field identification
  • Field mapping to user profile
  • Data input execution
  • Document upload handling
  • Review and submission
  • Confirmation capture
• Transitions between states
• Decision points and branching logic
• Error states and recovery paths

3. Decision Logic Flow

• How the agent determines field types (text, dropdown, file upload, etc.)
• Strategy for handling ambiguous or unknown fields
• Fallback mechanisms when automation fails
• When to request user intervention

4. Tool Integration Map

• Playwright actions the agent can call (click, type, select, upload)
• Browser inspection tools for form analysis
• Profile data retrieval from backend
• Application status updates to database

5. Error Handling & Recovery

• Common failure scenarios and responses
• Retry logic and limits
• User notification triggers
• State rollback mechanisms

Design Questions to Answer

• What is the agent's step-by-step execution flow?
• How does the agent handle multi-page applications?
• What information does the agent need from user profile?
• How does the agent communicate progress to the frontend?
• What are the stopping/pause conditions?
• How does manual user takeover work during automation?

Phase 2: Implementation

Core Application Agent

• Implement LangGraph state machine based on approved design
• Build agent prompt and system instructions
• Create tool definitions for Playwright actions
• Implement state persistence and checkpointing
• Add logging and debugging capabilities

Integration Points

• Connect to Weave's Playwright browser instance
• Retrieve user profile data from backend
• Update application status in real-time
• Send progress updates to frontend via WebSocket/SSE

Testing Requirements

• Unit tests for individual agent functions
• Integration tests with mock scholarship forms
• End-to-end test on real scholarship platform
• Error scenario testing

Acceptance Criteria

• Design document created in draw.io with all required diagrams
• Design reviewed and approved by team
• Application agent successfully completes sample application
• Agent correctly maps user profile fields to form inputs
• Agent handles common error cases gracefully
• Agent state persists and can resume after interruption
• Real-time progress visible in frontend
• User can take manual control at any point

Technical Stack

• LangGraph: State machine and agent orchestration
• LangChain: Tool calling and prompt management
• OpenRouter: LLM for decision-making (GPT-4 recommended)
• Integration: Weave Playwright browser automation

Deliverables

1. Design Document (draw.io file + exported PNG/PDF)
   • Location: docs/designs/application-agent-design.drawio
2. Implementation Code
   • Location: backend/agents/application_agent.py
   • LangGraph definitions: backend/agents/graphs/application_graph.py
3. Documentation
   • Agent behavior documentation
   • Configuration guide
   • Troubleshooting guide

Dependencies

• Blocked by: Streaming Service Integration (feat: Integrate Browser Streaming Service with AI Orchestrator Service #32)