Agent Workflow Platform

An intelligent automation platform that converts natural language commands into scheduled, multi-step agent workflows. Users describe business processes in plain English — e.g., "read my daily emails, find receipts, and upload them to Google Drive" — and the platform orchestrates execution across integrated services.

Demo

Architecture

NestJS microservices (TypeScript) + Python services (FastAPI/LangGraph) communicating via NATS JetStream
Next.js frontend with real-time WebSocket updates
PostgreSQL (Prisma ORM) for persistence
Kubernetes namespace-per-customer isolation with CronJob scheduling

┌─────────────┐     ┌──────────────┐     ┌──────────────────┐
│   Frontend   │────▶│  API Gateway │────▶│  NATS JetStream   │
│  (Next.js)   │     │  (REST BFF)  │     │  (Event Bus)      │
└──────┬───────┘     └──────────────┘     └────────┬──────────┘
       │                                           │
       │ WebSocket                    ┌────────────┼────────────────┐
       ▼                              ▼            ▼                ▼
┌──────────────┐   ┌──────────────┐ ┌────────┐ ┌───────────┐ ┌──────────┐
│  WebSocket   │   │  Onboarding  │ │ Agent  │ │ Scheduler │ │  Agent   │
│  Service     │   │  Service     │ │Builder │ │ Service   │ │ Runtime  │
└──────────────┘   └──────────────┘ │  (Py)  │ └───────────┘ │   (Py)   │
                                    └────────┘               └──────────┘

Prerequisites

Node.js >= 20
Python >= 3.11
Docker & Docker Compose
Minikube (for K8s deployment)
kubectl

Quick Start (Docker Compose)

1. Clone and install dependencies

cd agent-workflow-builder
cp .env.example .env
npm install

2. Start everything via Docker Compose

docker compose up --build

3. Run database migrations

cd libs/prisma-client
npx prisma generate
npx prisma migrate deploy
cd ../..

4. Access the application

Service	URL
Frontend	http://localhost:3000
API Gateway	http://localhost:3001/api/v1
WebSocket	ws://localhost:3002/ws
NATS Monitoring	http://localhost:8222

Node.js SDK

The @agent-workflow/sdk package (packages/sdk/) provides a typed client for the platform.

Setup

import { AgentWorkflowClient } from '@agent-workflow/sdk';

const client = new AgentWorkflowClient({
  apiKey: 'your-api-key',
  baseUrl: 'http://localhost:3001/api/v1',
  endUserId: 'end-user-123',
});

Parameter	Required	Description
`apiKey`	Yes	Workspace API key (from org creation)
`baseUrl`	No	REST API URL (default: `http://localhost:3001/api/v1`)
`endUserId`	No	Default end-user ID for commands and connections

Create agents

// Via natural language
const { commandId } = await client.agents.submitCommand(
  'find invoices from my gmail and upload to gdrive',
);

Manage agents and runs

// List all agents
const agents = await client.agents.list();

// Get a specific agent
const agent = await client.agents.get('agent-id');

// Trigger a run
const { runId } = await client.runs.trigger('agent-id');

// List runs for an agent
const runs = await client.runs.list('agent-id');

// Resume a paused run (after OAuth)
await client.runs.resume('agent-id', 'run-id', 'connection-id');

Connections

// Register an end-user connection (after OAuth)
await client.connections.complete(
  'google-mail',       // providerConfigKey
  'nango-conn-abc',    // connectionId
);

// Check connection status
const status = await client.connections.check('google-mail', 'conn-id');

Real-time WebSocket events

// Connect to the WebSocket server
await client.connect();

// Agent lifecycle events
client.on('agent:created', (e) => {
  console.log('Agent created:', e.name, e.agentId);
});

client.on('agent:scheduled', (e) => {
  console.log('Agent scheduled:', e.cronJobName, e.nextRunAt);
});

// Run lifecycle events
client.on('run:started', (e) => {
  console.log('Run started:', e.runId);
});

client.on('run:step_completed', (e) => {
  console.log(`Step ${e.stepIndex} completed:`, e.stepName);
});

client.on('run:paused', (e) => {
  console.log('Run paused — needs OAuth for:', e.providerConfigKey);
  // Show OAuth card to user, then resume:
  // await client.runs.resume(e.agentId, e.runId, connectionId);
});

client.on('run:resumed', (e) => {
  console.log('Run resumed:', e.runId);
});

client.on('run:succeeded', (e) => {
  console.log('Run completed:', e.summary);
});

client.on('run:failed', (e) => {
  console.error('Run failed:', e.error);
});

// Unsubscribe from a specific event
client.off('run:started', handler);

// Disconnect when done
client.disconnect();

Available WebSocket events

Event	Payload fields
`agent:created`	`agentId`, `name`, `scheduleCron`, `status`
`agent:scheduled`	`agentId`, `cronJobName`, `nextRunAt`
`run:started`	`agentId`, `runId`, `startedAt`
`run:step_completed`	`agentId`, `runId`, `stepIndex`, `stepName`
`run:paused`	`agentId`, `runId`, `reason`, `providerConfigKey`, `actionName`, `pausedAt`
`run:resumed`	`agentId`, `runId`, `resumedAt`
`run:succeeded`	`agentId`, `runId`, `summary`
`run:failed`	`agentId`, `runId`, `error`

Build the SDK

cd packages/sdk && npx tsc

Example: Chat App

A standalone Next.js chat application (examples/chat-app/) that demonstrates the full agentic workflow with a real-time chat UI.

Features:

Real-time WebSocket events (agent creation, step progress, pauses, completions)
OAuth connection cards with connect/resume flow
Tool execution results with syntax-highlighted JSON
Animated thinking indicators and step progress
Chat history sidebar with connection status

Running the Chat App

Prerequisites: The platform services must be running (via Docker Compose or individually).

# 1. Navigate to the chat app
cd examples/chat-app

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.local.example .env.local
# Edit .env.local and set your workspace API key:
#   AGENT_WORKFLOW_API_KEY=your-workspace-api-key
#   NEXT_PUBLIC_API_KEY=your-workspace-api-key

# 4. Build the SDK (required — the chat app depends on it)
cd ../../packages/sdk && npx tsc && cd ../../examples/chat-app

# 5. Start the dev server
npm run dev

The chat app runs on http://localhost:3100.

Variable	Description
`AGENT_WORKFLOW_API_KEY`	Workspace API key (server-side SDK calls)
`AGENT_WORKFLOW_API_URL`	Platform API URL (default: `http://localhost:3001/api/v1`)
`AGENT_WORKFLOW_WS_URL`	Platform WebSocket URL (default: `ws://localhost:3002/ws`)
`NEXT_PUBLIC_WS_URL`	WebSocket URL for browser (default: `ws://localhost:3002/ws`)
`NEXT_PUBLIC_API_KEY`	API key for browser WebSocket auth

LLM-Powered Agent Planner

The agent-builder service uses Claude (via LangGraph) to parse natural language commands into structured execution plans. The planner dynamically discovers available integrations and actions from the tool registry.

How it works:

User submits a natural language command
LLM calls list_integrations to discover available connectors
LLM calls search_tools to find actions for each relevant connector
LLM calls check_connection to verify the end user's connections
LLM calls submit_plan with a structured execution plan
Plan is validated against the tool registry and passed to the runtime

Set the key in .env:

OPENAI_API_KEY=openai_api_key

Project Structure

agent-workflow-builder/
├── libs/                        # Shared TypeScript libraries
│   ├── shared-types/            # Event payloads, DTOs, enums
│   ├── nats-client/             # NATS JetStream NestJS module
│   ├── prisma-client/           # Prisma schema + service
│   ├── integration-provider/    # Proxy action registry + declarative config
│   ├── auth/                    # API key guard
│   └── observability/           # OpenTelemetry + pino logger
├── packages/
│   └── sdk/                     # Node.js SDK (@agent-workflow/sdk)
├── services/                    # Backend microservices
│   ├── api-gateway/             # REST API (NestJS, port 3001)
│   ├── onboarding-service/      # Org lifecycle (NestJS)
│   ├── agent-builder-py/        # LLM planner + agent creation (Python/LangGraph)
│   ├── agent-runtime-py/        # Workflow step execution (Python)
│   ├── scheduler-service/       # K8s CronJob management (NestJS)
│   ├── websocket-service/       # Real-time events (NestJS, port 3002)
│   └── shared-py/               # Shared Python library (models, NATS, Nango client)
├── templates/
│   └── proxy-actions/           # JSON proxy action template files
├── frontend/web/                # Next.js admin app (port 3000)
├── examples/
│   └── chat-app/                # Agentic chat UI example (port 3100)
├── deploy/
│   ├── helm/                    # Helm umbrella chart
│   └── k8s/                     # Kustomize manifests
├── docker-compose.yml           # Full stack local dev
└── docker-compose.infra.yml     # Postgres + NATS only

Tech Stack

Component	Technology
Frontend	Next.js 15, Tailwind CSS
Backend (TS)	NestJS 10
Backend (Py)	FastAPI, LangGraph
LLM Planner	Claude (Anthropic)
Event Bus	NATS JetStream
Database	PostgreSQL 16 + Prisma
Auth	API Key + Firebase (frontend)
SDK	TypeScript (Node.js)
Orchestration	Kubernetes
Container	Docker

TODO

Support other integration providers (beyond Nango)
Enable scheduler service
Kubernetes support
Enrich templates/proxy-actions/ with more integration templates
Usage documentation
Support Bring Your Own LLM
Support Bring Your Own RAG

This was built with help from Claude Code.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Agent Workflow Platform

Demo

Architecture

Prerequisites

Quick Start (Docker Compose)

1. Clone and install dependencies

2. Start everything via Docker Compose

3. Run database migrations

4. Access the application

Node.js SDK

Setup

Create agents

Manage agents and runs

Connections

Real-time WebSocket events

Available WebSocket events

Build the SDK

Example: Chat App

Running the Chat App

LLM-Powered Agent Planner

Project Structure

Tech Stack

TODO

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Agent Workflow Platform

Demo

Architecture

Prerequisites

Quick Start (Docker Compose)

1. Clone and install dependencies

2. Start everything via Docker Compose

3. Run database migrations

4. Access the application

Node.js SDK

Setup

Create agents

Manage agents and runs

Connections

Real-time WebSocket events

Available WebSocket events

Build the SDK

Example: Chat App

Running the Chat App

LLM-Powered Agent Planner

Project Structure

Tech Stack

TODO