🧠 SentinelFlow: Autonomous Agentic Workflows

This repository contains a Proof of Concept (POC) for a long-running AI supervisor that oversees an e-commerce order from creation to completion.

The system relies on Durable Execution to allow an AI agent to run, make decisions, sleep for extended periods, and wake up securely without losing its memory or state if the server restarts.

🏗 Architecture & Tech Stack

1. Temporal (Docker): Handles the durable execution. It manages the long-running workflows, timers, and signals. If an agent goes to sleep for 3 days waiting for a package to be delivered, Temporal guarantees it will wake up on time.
2. FastAPI (Python): The backend API that bridges the frontend to Temporal and the PostgreSQL database.
3. Next.js (React): The frontend user interface for creating supervisor templates, monitoring live order runs, and injecting events.
4. Supabase (PostgreSQL): Stores the supervisor templates, run metadata, and the activity logs generated by the AI agent.
5. Groq / Gemini (LLM): The intelligence layer. The agent is fed the order context, its past memory, available tools, and recent events to autonomously decide what action to take next.

---

🚀 How the System Works Under the Hood

1. Initialization: When a new order run is created via the UI, FastAPI inserts a record into Supabase and starts a new Temporal Workflow.
2. First Run: The AI agent is immediately invoked. It reviews the new order, logs its initial reasoning, updates its compact memory, and decides how long to sleep (e.g., 60 minutes) to wait for an update.
3. Event Interruption: Real-world events (like payment_failed or shipment_delayed) can be injected via the API/UI. These are sent as Signals to the Temporal workflow.
4. Agent Wake-Up: The workflow instantly interrupts the agent's sleep. The agent is given the new event, its past memory, and the order context.
5. Tool Usage: The AI analyzes the event and uses tools (e.g., message_payments_team, message_customer) to handle the issue. It updates its reasoning and goes back to sleep.
6. Termination & Summary: Once the order lifecycle is complete (or manually terminated), a final Temporal activity runs to summarize the entire history, generating a structured report of actions taken, learnings, and recommendations.

---

🛠 Setup & Installation

Prerequisites

• Docker & Docker Compose (for Temporal)
• Python 3.10+
• Node.js 18+
• A Supabase Project (PostgreSQL)
• Groq / Gemini API Keys

1. Environment Setup

Create a .env file in the root directory:

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
DATABASE_URL=postgresql://postgres:password@db.your-project.supabase.co:5432/postgres

# Temporal
TEMPORAL_HOST=localhost:7233
TEMPORAL_NAMESPACE=default
TEMPORAL_TASK_QUEUE=order-supervisor

# LLM Keys
GROQ_API_KEY=your-groq-key
GEMINI_API_KEY=your-gemini-key

# App
NEXT_PUBLIC_API_URL=http://localhost:8001

Create a .env.local in the frontend/ directory:

NEXT_PUBLIC_API_URL=http://localhost:8001

2. Database Initialization

Run the contents of schema.sql in your Supabase SQL Editor. Make sure to disable Row Level Security (RLS) on the tables (supervisors, runs, activity_log) or provide appropriate policies.

3. Start Temporal

docker-compose up -d

The Temporal UI will be available at http://localhost:8233

4. Start the Backend API

cd backend
python -m venv venv
source venv/Scripts/activate  # Or venv/bin/activate on Mac/Linux
pip install -r requirements.txt
uvicorn main:app --reload --port 8001

5. Start the Temporal Worker

In a new terminal window:

cd backend
source venv/Scripts/activate
python worker.py

6. Start the Frontend

In a new terminal window:

cd frontend
npm install
npm run dev

---

🧪 How to Test the System Manually

You can test the full capabilities of the autonomous supervisor via the Next.js frontend (http://localhost:3000).

Step 1: Create a Supervisor Persona

1. Navigate to the Supervisors page.
2. Create a new supervisor (e.g., "Strict Payment Supervisor").
3. Set the base instruction (e.g., "Monitor orders. If a payment fails, escalate immediately.") and choose the Wake Aggressiveness.

Step 2: Start an Order Run

1. Go to the Order Runs page and click + New Run.
2. Enter an Order ID (e.g., ORD-12345) and select your new supervisor.
3. Click Start Run.

Step 3: Monitor the Autonomous Agent

1. Click on the newly created run to open its Timeline.
2. You will see the agent's initial thoughts:
   • 🧠 Reasoning: Acknowledging the new order.
   • 😴 Sleep: Setting a timer to check back later.
   • The Memory Summary box will reflect the current state.

Step 4: Inject a Real-World Event

1. Use the Inject Event panel on the right.
2. Select an event like payment_failed and click Send Event.
3. Watch the Timeline update live:
   • 📡 The Event is received.
   • ⚡ The AI takes Action (e.g., messaging the payments team).
   • 🧠 The AI logs its updated Reasoning.
   • 😴 The AI sets a new Sleep timer based on the urgency of the issue.

Step 5: Manual Override

1. Use the Add Instructions panel.
2. Type a manual command: "The customer is angry, cancel the order immediately."
3. The AI will instantly wake up, read your instruction, and adjust its behavior accordingly.

Step 6: Review the Final Summary

1. Click the red ⏹ Terminate button at the top right.
2. Scroll to the bottom of the page to see the Final Summary. This is an AI-generated retrospective of the entire order lifecycle, detailing actions taken and future recommendations.