Agentic Workflow Engine - Phase 3 Complete! 🎉

A complete, enterprise-ready agentic workflow platform with visual builder, real-time monitoring, intelligent agents with memory, tool-calling capabilities, and advanced execution features.

🔐 Sign-in and browsing

• Without an account session, the app still supports the Marketplace (templates). Your saved workflows (GET /api/workflows) are empty until you sign in; the builder uses a local draft tab only.
• Workflow assistant (chat) supports an optional iteration limit per message (UI default 20); see docs/API_REFERENCE.md.
• Local dev login: Prefer REACT_APP_API_BASE_URL unset in frontend/.env.development so the UI talks to /api through the dev proxy. Optional DEV_BOOTSTRAP_USERNAME / DEV_BOOTSTRAP_PASSWORD in root .env create or reset a dev user on API startup — see docs/CONFIGURATION_REFERENCE.md.

🌟 Overview

Build complex multi-agent workflows where AI agents collaborate sequentially to accomplish tasks. Perfect for:

• Content creation pipelines (write, edit, review)
• Research and analysis workflows
• Data processing chains
• Automated decision-making systems

✨ Features

Phase 3 (Current) - LATEST!

• 🚀 WebSocket Streaming - Real-time execution monitoring
• 🧠 Agent Memory - Short-term and long-term memory with vector storage
• 🛠️ Tool Calling - Agents can execute functions and use tools
• 📊 Enhanced Monitoring - Live progress updates and detailed logging
• 📈 Analytics Dashboard - Execution metrics with interactive charts (success rates, duration trends, status distribution)
• 📥 Log Management - Download execution logs (text/JSON), filter and paginate logs
• 🛑 Execution Control - Cancel running executions

Phase 2 (Complete)

• ✨ Visual Workflow Builder - Drag-and-drop UI with React Flow
• ✨ Conditional Branching - If/else logic with multiple condition types
• ✨ Loop Support - For-each, while, and until loops
• ✨ Parallel Execution - Independent nodes run simultaneously
• ✨ Real-time Execution Viewer - Watch workflows execute live

Phase 1 (Complete)

• ✅ Sequential Workflow Execution - Agents execute in dependency order
• ✅ LLM-Powered Agents - Integrated with OpenAI (GPT-4, GPT-4o-mini, etc.)
• ✅ Node-Based Workflows - Visual graph representation of agent pipelines
• ✅ Input/Output Chaining - Data flows seamlessly between agents
• ✅ Execution Tracking - Complete logs and state management
• ✅ REST API - Full-featured API with OpenAPI documentation
• ✅ Persistent Storage - SQLite database (PostgreSQL-ready)
• ✅ Async Architecture - Non-blocking execution for scalability

🚀 Quick Start

Prerequisites

• Python 3.8+
• Node.js 18+ and npm
• OpenAI API key

One-Command Startup (Recommended)

# Setup (first time only)
pip install -r requirements.txt
cd frontend && npm install && cd ..
cp .env.example .env  # Then add your OpenAI API key

# Start both backend and frontend
./start.sh

Visit http://localhost:3000 to use the visual workflow builder!

Manual Startup

Terminal 1: Backend

python3 -m uvicorn backend.main:app --host 0.0.0.0 --port 8000

Backend runs at http://localhost:8000. (Running python main.py from the repo root only runs a PyCharm sample stub and does not start the API.)

Terminal 2: Frontend

cd frontend
npm start

Frontend runs at http://localhost:3000 (CRA dev server; API defaults to proxied /api).

Your First Visual Workflow

1. Open http://localhost:3000
2. Drag nodes from the left panel onto the canvas
3. Connect nodes by dragging between the handles (circles)
4. Configure nodes by clicking them (right panel)
5. Save your workflow (top toolbar)
6. Execute and watch it run!

CLI Examples (Phase 1 Style)

# Simple 2-agent workflow
python examples/simple_workflow.py

# 3-agent research pipeline
python examples/research_workflow.py

# Conditional branching (NEW!)
python examples/conditional_workflow.py

# Loop-based batch processing (NEW!)
python examples/loop_workflow.py

📚 Documentation

Quick Links

• GETTING_STARTED.md - Step-by-step guide for beginners
• PHASE3.md - Phase 3 features: WebSockets, Memory, Tools (NEW!)
• PHASE2.md - Visual builder and advanced control flow
• QUICKSTART.md - Detailed setup and CLI usage
• ARCHITECTURE.md - System architecture and design
• docs/EXECUTION_SYSTEM_ARCHITECTURE.md - Detailed execution system architecture
• docs/CONFIGURATION_REFERENCE.md - Complete configuration guide (NEW!)
• docs/TROUBLESHOOTING.md - Common issues and solutions (NEW!)
• docs/NODE_TYPES_REFERENCE.md - Complete node types reference (NEW!)
• WORKFLOW_EXAMPLES.md - Pattern library and use cases
• frontend/README.md - Frontend development guide

Interactive Docs

• Visual Builder - http://localhost:3000 (when frontend is running)
• API Docs - http://localhost:8000/docs (when backend is running)

🎯 Example Workflows

Phase 3 Examples (LATEST!)

Complete Phase 3 Demo

python examples/phase3_demo.py

Demonstrates WebSocket streaming, memory, and tool calling

Phase 2 Examples

Conditional Branching

python examples/conditional_workflow.py

Analyzes sentiment → Routes to positive/negative responder

Loop Processing

python examples/loop_workflow.py

Processes multiple topics → Combines results

Phase 1 Examples

Simple Story Writer (2 agents)

python examples/simple_workflow.py

Writer → Editor → Polished Story

Research Assistant (3 agents)

python examples/research_workflow.py

Researcher → Analyzer → Summarizer → Final Report

🏗️ Project Structure

cursor-test/
├── main.py                    # Application entry point
├── requirements.txt           # Dependencies
├── verify_setup.py           # Setup verification
├── test_api.py               # API tests
│
├── frontend/                  # Create React App UI (React 18, styled-components, Redux)
│   └── README.md             # Frontend stack, proxy, styling, build output
│
├── backend/
│   ├── models/               # Pydantic schemas & types
│   ├── database/             # SQLAlchemy ORM & connection
│   ├── engine/               # Workflow execution engine
│   ├── agents/               # Agent implementations
│   └── api/                  # FastAPI routes
│
└── examples/
    ├── simple_workflow.py    # 2-agent example
    └── research_workflow.py  # 3-agent example

🔧 Testing

# Test API connectivity (server must be running)
python test_api.py

# Manual API testing
curl http://localhost:8000/health

📖 API Overview

Workflows

• POST /api/workflows - Create a workflow
• GET /api/workflows - List all workflows
• GET /api/workflows/{id} - Get workflow details
• DELETE /api/workflows/{id} - Delete a workflow

Execution

• POST /api/workflows/{id}/execute - Execute a workflow
• GET /api/executions/{id} - Get execution details

🎨 Workflow Concepts

A workflow consists of Nodes (agents) connected by Edges:

[Start] → [Agent 1] → [Agent 2] → [Agent 3] → [End]
           ↓           ↓           ↓
        Research    Analysis    Summary

Each agent:

• Receives input from previous agents or workflow variables
• Processes with an LLM (configurable model, temperature, prompts)
• Produces output for the next agent

🔮 Roadmap

• ✅ Phase 1: Core engine, sequential execution, REST API
• ✅ Phase 2: Visual builder, conditionals, loops, parallel execution
• ✅ Phase 3: WebSockets, agent memory, tool calling
• 📋 Phase 4: Templates, collaboration, advanced debugging
• 📋 Phase 5: Enterprise (SSO, RBAC, audit logs, governance)

🤝 Contributing

This is Phase 1 of a multi-phase project. The architecture is designed for extensibility:

• Add new agent types by extending BaseAgent
• Support new LLM providers in the agent layer
• Implement custom node types via the registry pattern

📝 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Built with:

• FastAPI - Modern web framework
• SQLAlchemy - SQL toolkit and ORM
• Pydantic - Data validation
• OpenAI - LLM API
• React + Create React App - Visual builder UI
• styled-components - Component styling (see frontend/README.md)

---

Ready to build? Start with: python verify_setup.py