AutoStream Conversational AI Agent

This conversational AI agent is built for AutoStream, a SaaS product providing automated video editing tools for content creators. The agent supports casual conversations, RAG-powered knowledge retrieval for pricing and policies, and high-intent lead capture via tool execution.

1. Setup and Run Locally

Prerequisites

• Python 3.9+
• A Google API Key for Google Generative AI (Gemini 1.5 Flash is used for optimal speed and reliability).

Installation Instructions

1. Clone or navigate to the repository directory.
2. Install the required dependencies:

   pip install -r requirements.txt

3. Set up your environment variable. Add your Google API key to .env or run:

   export GOOGLE_API_KEY="your_google_api_key_here"

4. Run the Full Stack App:

   ./dev.sh

   This will concurrently spin up the FastAPI backend (port 8000) and the Vite React UI (port 5173). Open http://localhost:5173 in your browser.

2. Architecture Explanation

Why LangGraph? To achieve high fidelity against the project constraints—specifically deterministic tool execution and strictly classifying user intents—I chose LangGraph over standard conversational frameworks. A standard black-box ReAct loop is often prone to premature tool execution, hallucinations, or forgetting critical context during multi-turn interactions. By implementing a state machine with explicit processing nodes (such as a classifier_node for intent detection, an inquiry_node for handling RAG and general queries, and a lead_capture_node for high-intent scenarios) and utilizing a conditional edge router based on structured LLM outputs, we successfully decouple the routing logic from the text generation. This ensures that the agent follows a predictable flow, strictly enforcing boundaries between casual chat, policy retrieval, and lead generation without bleeding instructions across contexts.

State Management: State is managed robustly across conversation turns using LangGraph's TypedDict structure (AgentState). The graph retains a running list of messages (using the add_messages reducer to maintain chat history) for conversational context, the current classified intent, and a lead_info dictionary. When the user's intent shifts to high_intent, the agent references its internal lead_info state to determine which required fields (name, email, platform) are missing. Because both intent extraction and state modification are explicitly handled at the classifier step, the lead extraction state safely and accurately accumulates these values sequentially over multiple conversational turns. This prevents duplicate questions and provides a natural, human-like data collection process.

---

3. WhatsApp Deployment Question (Webhooks Integration)

How I would integrate this agent with WhatsApp using Webhooks:

To deploy this local memory-based agent to a production WhatsApp numbers (via Twilio or Meta Graph API), I would adopt a stateful, event-driven web integration.

1. Webhook Endpoint: I'd deploy a FastAPI application that receives incoming POST requests from the WhatsApp API.
2. Payload Parsing: The request would be parsed to extract the user's phone number (acting as the LangGraph thread_id) and text message.
3. Graph Execution: Using LangGraph's persistence (e.g., MemorySaver checkpointer or PostgreSQL schema), we invoke the agent using the specific thread_id. This retains the exact lead_info state and message history across incoming HTTP hits.
4. Sending Responses: Once LangGraph outputs a new system/AI message, the backend fires a POST response back utilizing the WhatsApp Messages endpoint, immediately replying to the user inline.