AI Agent Automation

Local-first workflow automation for AI agents

Build, run, inspect, replay, and expose AI-powered workflows from your own infrastructure.

Last commit

Documentation · Docker Guide · Workflow Engine · Privacy · Issues

Quick Start · First Workflow · Configuration · Troubleshooting · Contributing

AI Agent Automation demo

Overview

AI Agent Automation is a self-hosted workflow engine for building and operating AI-driven automations. It combines a visual workflow builder, agent configuration, deterministic task execution, document RAG, semantic memory, tool integrations, workflow APIs, and execution observability.

It is built for developers who want inspectable automation instead of a black-box chatbot or hosted SaaS dependency.

Local-first
Run the platform with your own MongoDB, provider keys, workers, and infrastructure.

Inspectable
Every workflow run becomes a task with step inputs, outputs, logs, status, and replay controls.

AI-native
Agents can use provider-specific models, memory, document retrieval, and automation tools.

What You Can Build

Workflow Automation Create visual workflows with LLM, HTTP, delay, file, email, browser, document, condition, switch, parallel, join, approval, and agent call nodes.	Agent Workspaces Configure agents with provider, model, role, instructions, semantic memory, and tool capabilities.
Document Intelligence Upload documents, chunk and embed them, then chat with source attribution and retrieval controls.	Agent Teams Build multi-agent teams with a visual team builder, war room chat, session logs, and A2A webhook support.
Workflow APIs Expose workflows through public endpoints with custom slugs and optional API-key authentication.	Operations Dashboard Track live workflow status, execution trends, task timelines, logs, metrics, and workflow insights.

Architecture At A Glance

flowchart LR

    User["User / Browser"] --> Frontend["Next.js Frontend"]
    External["External Apps"] --> API

    Frontend --> Proxy["Nginx / Docker Proxy"]
    Proxy --> API["Express REST API"]

    API <--> DB[("MongoDB")]

    API --> Worker["Worker Runtime"]
    Worker --> AI["AI Engine"]
    Worker --> Tools["Tool Registry"]

    Worker --> Socket["Socket.IO"]
    Socket --> Frontend

    AI --> Providers["OpenAI • Groq • Gemini • Ollama • Hugging Face"]

    Tools --> Integrations["Email • HTTP • Browser • File • GitHub • Slack • Discord"]

    Scheduler["Cron Scheduler"] --> Worker

Module	Responsibility
Frontend	Workflow builder, dashboard, agents, documents, memory, teams, settings, logs, and insights.
API	Authentication, REST APIs, workflow management, webhooks, scheduling, templates, and business logic.
MongoDB	Stores users, workflows, tasks, agents, documents, semantic memory, schedules, logs, telemetry, and settings.
Worker Runtime	Polls pending tasks, executes workflow graphs, handles branching, retries, approvals, and records execution results.
AI Engine	Semantic memory, document retrieval (RAG), MCP, provider adapters, and agent collaboration.
Tool Registry	Executes integrations such as HTTP, Email, Browser, File, GitHub, Slack, and Discord tools.
Scheduler	Creates workflow tasks from cron schedules.
Realtime	Streams workflow progress and task updates through Socket.IO.

Getting Started

Choose the setup that best fits your needs.

Setup	Recommended For
🐳 Docker Quick Start	New users, self-hosting, demos, and running the complete platform with minimal setup.
🛠️ Local Development	Contributors and developers who want faster backend/frontend iteration.

Quick Start with Docker (Recommended)

Docker Compose starts the complete platform, including:

MongoDB Replica Set
Backend API
Worker Runtime
Frontend
Nginx Reverse Proxy

Best for	New users, demos, integrated testing, and self-hosted deployments.
Requires	Git, Docker Compose, and at least one LLM provider API key or a local Ollama instance.
Frontend	`http://localhost:3000`

1. Clone the Repository

git clone https://github.com/vmDeshpande/ai-agent-automation.git
cd ai-agent-automation/infra
cp .env.example .env

2. Configure Environment

Edit infra/.env:

JWT_SECRET=change-this-to-a-long-random-string

# Configure one or more providers
OPENAI_API_KEY=
GROQ_API_KEY=
GEMINI_API_KEY=
HF_API_KEY=

# Local Ollama (optional)
OLLAMA_HOST=http://host.docker.internal:11434

3. Start the Platform

docker compose up --build

Open:

http://localhost:3000

Useful Commands

docker compose ps
docker compose logs -f backend worker frontend
docker compose down

Remove all containers and MongoDB data:

docker compose down -v

Local Development

Run the services directly on your machine for faster development.

Note

MongoDB must be available with Replica Set support enabled. You can run MongoDB locally or start only MongoDB using Docker while running the backend, worker, and frontend natively.

Terminal	Service	Default URL
1️⃣	Backend API	`http://localhost:5000`
2️⃣	Worker Runtime	Background Service
3️⃣	Frontend	`http://localhost:3000`

1. Clone the Repository

git clone https://github.com/vmDeshpande/ai-agent-automation.git
cd ai-agent-automation

2. Start the Backend

cd backend

npm install

cp .env.example .env

npm run dev

Backend API:

http://localhost:5000

3. Start the Worker

Open a new terminal:

cd backend

npm run worker

The worker executes workflow tasks. Workflow execution will not function unless the worker is running.

4. Start the Frontend

Open another new terminal:

cd frontend

npm install

npm run dev

Frontend:

http://localhost:3000

Project Structure During Local Development

Terminal 1 → Backend API
Terminal 2 → Worker Runtime
Terminal 3 → Frontend
MongoDB   → Replica Set

First Workflow

After the app is running:

Step	Action
1	Register a user account.
2	Open Settings and confirm at least one LLM provider is configured.
3	Create an Agent and choose its provider and model.
4	Create a Workflow from scratch or from a template.
5	Add an LLM node and assign the workflow to your agent.
6	Run the workflow.
7	Open the generated Task and inspect step inputs, outputs, logs, and status.

If a workflow stays pending, the worker is probably not running.

Configuration

Common backend variables live in backend/.env.example. Docker variables live in infra/.env.example.

Variable	Required	Purpose
`JWT_SECRET`	Yes	Signs user authentication tokens. Use a long random value.
`MONGO_URI`	Yes	MongoDB connection string. Docker sets this for the internal Mongo service.
`MONGO_ROOT_USER`	Yes (Docker)	MongoDB root username for Docker initialization.
`MONGO_ROOT_PASSWORD`	Yes (Docker)	MongoDB root password for Docker initialization.
`MONGO_APP_USER`	Yes (Docker)	MongoDB application username with least-privilege access to `ai-agent` database.
`MONGO_APP_PASSWORD`	Yes (Docker)	MongoDB application password for `MONGO_APP_USER`.
`OPENAI_API_KEY`	Optional	OpenAI models and embeddings.
`GROQ_API_KEY`	Optional	Groq-hosted models.
`GEMINI_API_KEY`	Optional	Google Gemini models and embeddings.
`HF_API_KEY`	Optional	Hugging Face models and embeddings.
`OLLAMA_HOST`	Optional	Local Ollama endpoint, such as `http://localhost:11434` locally or `http://host.docker.internal:11434` in Docker.
`EMAIL_HOST`, `EMAIL_PORT`, `EMAIL_USER`, `EMAIL_PASS`, `EMAIL_FROM`	Optional	Email tool configuration.
`MCP_ENABLED`, `MCP_CONFIG_PATH`, `MCP_CONFIG_JSON`, `MCP_SERVER_URL`	Optional	MCP integration configuration.
`GITHUB_TOKEN`, `SLACK_WEBHOOK_URL`, `DISCORD_WEBHOOK_URL`	Optional	Integration tool credentials.
`TELEMETRY_ENABLED`, `DISABLE_ALL_ANALYTICS`	Optional	Controls optional telemetry.

Do not commit .env files or secrets.

Project Structure

backend/
  server.js
  src/
    agents/       workflow runner, executor, handlers, event broker
    controllers/  API controllers
    models/       Mongoose models
    routes/       Express routes
    services/     domain services
    tools/        tool registry and tool implementations
    workflow/     node catalog and workflow helpers

frontend/
  src/app/        Next.js App Router pages
  src/components/ shared UI and workflow components
  src/context/    client state providers
  src/lib/        API client and helpers
  src/types/      TypeScript types

infra/
  docker-compose.yml
  nginx/

Development Commands

Command	Where	Purpose
`npm run lint`	repo root	Lint frontend and backend source.
`npm run format`	repo root	Format frontend and backend source.
`npm test`	`backend/`	Run Jest handler tests.
`npm run build`	`frontend/`	Build the Next.js frontend.

Documentation Map

Architecture	System overview and major components.
Workflow Engine	Runner, executor, task lifecycle, and step flow.
Workflow Builder	Graph builder conventions.
Workflow Variables	Interpolation and step output references.
Agent System	Agents, roles, execution, and memory.
Document RAG	Document upload, chunking, embeddings, and chat.
Custom Tools	Add a new automation tool.
MCP Integration	MCP setup and usage.
A2A	Agent-to-agent protocol and webhook flow.
Docker Deployment	Production-style Docker setup.
Privacy	Data handling and deployment responsibilities.
Telemetry	Optional telemetry behavior and controls.

Troubleshooting

Workflows stay pending

Start the worker:

cd backend
npm run worker

MongoDB transaction or replica-set errors

Use Docker Compose, or make sure your local MongoDB is running as a replica set.

cd infra
docker compose down -v
docker compose up --build

Port already in use

Change these values in infra/.env:

MONGO_PORT=27018
BACKEND_PORT=5001
FRONTEND_PORT=3001

The Docker frontend derives its backend URL from BACKEND_PORT; do not set NEXT_PUBLIC_API_URL manually for Docker deployments.

LLM calls fail

Confirm that the agent has a provider and model selected, and that the matching environment variable is set. For Ollama, confirm the host is reachable from the process making the call.

Email, Slack, Discord, or GitHub tools fail

Check the corresponding environment variables and inspect backend and worker logs:

cd infra
docker compose logs -f backend worker

Security And Privacy

Self-hosted	Workflow data, documents, logs, and memory are stored in your MongoDB deployment.
Secrets	Provider keys and integration credentials are read from environment variables.
Telemetry	Optional telemetry is designed not to collect prompts, workflow definitions, memories, uploaded documents, API keys, execution logs, or user identities.

Review docs/privacy.md before exposing a deployment to other users.

Contributing

Contributions are welcome. Good first areas include docs, workflow templates, UI polish, tests, and new tool integrations.

Read CONTRIBUTING.md before opening a pull request.

Helpful references:

License

Apache License 2.0. See LICENSE.

ai-agent-automation

Links

README

AI Agent Automation

Local-first workflow automation for AI agents

Overview

What You Can Build

Architecture At A Glance

Getting Started

Quick Start with Docker (Recommended)

1. Clone the Repository

2. Configure Environment

3. Start the Platform

Useful Commands

Local Development

1. Clone the Repository

2. Start the Backend

3. Start the Worker

4. Start the Frontend

Project Structure During Local Development

First Workflow

Configuration

Project Structure

Development Commands

Documentation Map

Troubleshooting

Security And Privacy

Contributing

License

Collected info