README.md

metadata

title: Agentic Workflow Node Lab
emoji: 🤖
colorFrom: indigo
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false

Agentic Workflow Lab

A deliberately small educational workflow simulator. Build a graph with Input, AI Worker, Decision Rules, Human Review, Simulated Tool, and Output nodes, then send one item through it at a time. Actions and integrations are simulations only.

Local setup (Conda + VS Code)

1. Install Miniconda and Node.js 20+.

2. In this folder, create the environment:

   conda env create -f environment.yml
   conda activate workflow-lab
   cp .env.example .env
   

3. Put your server-side API key in .env. The browser never receives it.

4. In VS Code, run Tasks: Run Task → Start app, or use two terminals:

   uvicorn backend.main:app --reload --port 8000
   cd frontend && npm install && npm run dev
   

Open http://localhost:5173. The frontend proxies /api calls to FastAPI.

LLM settings

The backend uses the OpenAI Python SDK and supports OpenAI-compatible endpoints:

OPENAI_API_KEY=...
OPENAI_MODEL=gpt-4.1-mini
# OPENAI_BASE_URL=https://your-compatible-endpoint/v1

Without a key, the app runs in deterministic demo mode so the workflow UI can still be taught and tested.

How execution works

• Exactly one item enters through an Input node.
• Solid workflow connections determine what runs next.
• Purple dashed tool connections grant an AI Worker access to a Simulated Tool; they do not advance the workflow.
• AI Workers see each attached tool's name, description, expected input, and prior results. They decide at runtime whether to call a tool, may call up to five tools, and then produce their final work.
• Simulated Tools return prompt-generated information or simulated actions. They never invoke a real integration.
• Decision Rules return the ID of one connected target using route labels and explicit plain-English rules.
• Human Review is a dedicated node that pauses on the server; the learner replies in English, then execution resumes.
• Output ends the run and displays the accumulated result and event trace.
• Safety limits of 50 workflow steps and five tool calls per worker prevent accidental loops.

The two connection types

Input ──flow──> AI Worker ──flow──> Decision Rules ──flow──> Output
                    │
                    └──tool access (dashed)──> Simulated Tool

Select a workflow connection to give it a route label such as High risk or Standard response. Decision Rules uses these labels when applying its English rules.

Workflow JSON can be downloaded and loaded in the browser. The JSON stores the canvas, connections, node settings, and input text—never API keys.

Hugging Face Spaces deployment

Create a new Docker Space, upload this repository, and add OPENAI_API_KEY as a Space Secret. Optionally add OPENAI_MODEL and OPENAI_BASE_URL as variables/secrets. The included Dockerfile builds React and serves it from FastAPI on port 7860.

For Git-based deployment:

git remote add space https://huggingface.co/spaces/YOUR_NAME/YOUR_SPACE
git push space main

Do not commit .env; it is ignored.

Project map

backend/                 FastAPI API, execution engine, prompt templates
frontend/                React + React Flow visual editor
.vscode/tasks.json       one-click local development task
environment.yml          Conda environment
Dockerfile               Hugging Face Spaces build