Name	Name	Last commit message	Last commit date
Latest commit History 90 Commits
.agents/skills	.agents/skills
.amp	.amp
old_docs	old_docs
packages	packages
scripts	scripts
tasks	tasks
.env.example	.env.example
.gitignore	.gitignore
.npmrc	.npmrc
AGENTS.md	AGENTS.md
DESIAGENT_CODE_REFERENCE.md	DESIAGENT_CODE_REFERENCE.md
DESIAGENT_FILE_TRANSFORMATION.md	DESIAGENT_FILE_TRANSFORMATION.md
DESIAGENT_IMPLEMENTATION_CHECKLIST.md	DESIAGENT_IMPLEMENTATION_CHECKLIST.md
DESIAGENT_PLAN_README.md	DESIAGENT_PLAN_README.md
DESIAGENT_PLAN_SUMMARY.md	DESIAGENT_PLAN_SUMMARY.md
DESIAGENT_REFACTORING_PLAN.md	DESIAGENT_REFACTORING_PLAN.md
DESIAGENT_START_HERE.md	DESIAGENT_START_HERE.md
IMPLEMENTATION_PLAN.md	IMPLEMENTATION_PLAN.md
INDEX.md	INDEX.md
JS_API_SDK_GUIDE.md	JS_API_SDK_GUIDE.md
README.md	README.md
agents.csv	agents.csv
agents.json	agents.json
all.txt	all.txt
create-and-execute-dag.sh	create-and-execute-dag.sh
create-dag.sh	create-dag.sh
createGoal.sh	createGoal.sh
do-dag-experitments.sh	do-dag-experitments.sh
execute-dag.sh	execute-dag.sh
get-tool.sh	get-tool.sh
goals.json	goals.json
lostfiles.txt	lostfiles.txt
openapi.yaml	openapi.yaml
package.json	package.json
pnpm-lock.yaml	pnpm-lock.yaml
pnpm-workspace.yaml	pnpm-workspace.yaml
stats.md	stats.md
stripURL.sh	stripURL.sh
talk.wav	talk.wav
task.sh	task.sh
test-dag-route.sh	test-dag-route.sh
test-dag-tracking.sh	test-dag-tracking.sh
test-dag-with-file.sh	test-dag-with-file.sh
test-sse.html	test-sse.html
test-sse.sh	test-sse.sh
test-suspended-state.sh	test-suspended-state.sh
tmp	tmp
web.txt	web.txt

Async Agent System

A monorepo-based autonomous agent system that runs persistent, background AI agents with multi-provider LLM support (OpenAI, OpenRouter, Ollama), featuring DAG-based task execution and a modern web interface.

Features

🤖 Autonomous Agents - LLM-powered decision making with tool selection
🔄 DAG Execution - Directed Acyclic Graph task decomposition and parallel execution
⏰ Scheduled Tasks - Cron-based scheduling with timezone support
💾 Persistent State - SQLite database maintains state across restarts
🛠️ Tool System - Extensible tool registry (web search, fetch, file ops, webhooks, email)
🎯 Goal-Oriented - High-level objectives drive multi-step autonomous plans
🔌 Multi-Provider LLM - Support for OpenAI, OpenRouter, and Ollama (local models)
🌐 Web Dashboard - Modern SvelteKit interface for monitoring and management
📡 Real-time Events - Server-Sent Events (SSE) for live execution updates
✅ Tool Calling Validation - Startup checks ensure model compatibility

Architecture

┌─────────────────────────────────────────────────────────┐
│ Clients │
├──────────┬──────────────┬──────────────┬───────────────┤
│ CLI │ Web App │ REPL │ API Client │
│ │ (SvelteKit) │ │ (JS/Python) │
└────┬─────┴──────┬───────┴──────┬───────┴───────┬───────┘
 │ │ │ │
 └────────────┴──────────────┴───────────────┘
 │
 ┌───────▼────────┐
 │ Backend API │
 │ (Fastify) │
 └───────┬────────┘
 │
 ┌──────────────────┼──────────────────┐
 │ │ │
 ┌────▼────┐ ┌─────▼─────┐ ┌─────▼─────┐
 │ DAG │ │ Agent │ │ Tool │
 │Scheduler│ │ Runtime │ │ Registry │
 └────┬────┘ └─────┬─────┘ └───────────┘
 │ │
 │ ┌────────────┘
 │ │
 ┌────▼────▼───┐
 │ SQLite DB │
 │ (Drizzle) │
 └─────────────┘

Quick Start

Prerequisites

Node.js >= 18.0.0
pnpm >= 8.0.0
One of:
- OpenAI API key
- OpenRouter API key
- Ollama running locally

Installation

# Clone the repository
git clone https://github.com/ugmurthy/asyncAgent.git
cd asyncAgent
# Install dependencies
pnpm install
# Set up environment
cp .env.example .env
# Edit .env with your LLM provider settings
# Build all packages
pnpm build

Configuration

Edit .env with your preferred LLM provider:

For OpenAI:

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o

For OpenRouter:

LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=sk-or-your-key-here
OPENROUTER_MODEL=anthropic/claude-3.5-sonnet

For Ollama (Local):

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=mistral

Start the System

# Start backend in development mode
pnpm dev
# Start web application (in another terminal)
pnpm --filter @async-agent/webapp dev

Backend API: http://localhost:3000
Web Dashboard: http://localhost:5173

Project Structure

asyncAgent/
├── packages/
│ ├── backend/ # Fastify API + Agent Runtime
│ │ ├── src/
│ │ │ ├── app/ # Server and routes
│ │ │ ├── agent/ # DAG executor, planner, providers
│ │ │ ├── scheduler/ # DAG scheduling
│ │ │ ├── db/ # Database schema and migrations
│ │ │ └── events/ # Event bus for SSE
│ │ └── package.json
│ │
│ ├── webApp/ # SvelteKit Web Interface
│ │ ├── src/
│ │ │ ├── routes/ # File-based routing
│ │ │ └── lib/ # Components, stores, utilities
│ │ └── package.json
│ │
│ ├── shared/ # Shared types, schemas, utilities
│ │ ├── src/
│ │ ├── js-client/ # Auto-generated JS API client
│ │ └── python-client/ # Auto-generated Python API client
│ │
│ ├── cli/ # Command-line interface
│ ├── repl/ # Interactive REPL
│ └── tui/ # Terminal UI
│
├── openapi.yaml # API specification
├── .env.example # Environment template
├── pnpm-workspace.yaml # Workspace configuration
└── package.json # Root package

Available Tools

The agent runtime includes these built-in tools:

Tool	Description
`web_search`	Search the web using DuckDuckGo
`fetch_page`	Fetch and extract content from a URL
`fetch_urls`	Fetch multiple URLs in parallel
`write_file`	Write content to a file
`read_file`	Read content from a file
`send_webhook`	Send HTTP webhook requests
`send_email`	Send emails (requires SMTP configuration)

API Endpoints

Base URL: http://localhost:3000/api/v1

Core Endpoints

Endpoint	Description
`GET /health`	Health check
`GET /health/ready`	Readiness with LLM and scheduler status

Goals & Runs

Endpoint	Description
`POST /api/v1/goals`	Create a new goal
`GET /api/v1/goals`	List all goals
`POST /api/v1/goals/:id/run`	Trigger goal execution
`GET /api/v1/runs`	List all runs
`GET /api/v1/runs/:id/steps`	Get execution steps

DAG Operations

Endpoint	Description
`POST /api/v1/create-dag`	Create a DAG from goal text
`POST /api/v1/execute-dag`	Execute a DAG
`POST /api/v1/resume-dag/:id`	Resume a suspended DAG
`GET /api/v1/dags`	List all DAGs
`GET /api/v1/dag-executions`	List DAG executions
`GET /api/v1/dag-executions/:id/events`	Stream execution events (SSE)

Task Execution

Endpoint	Description
`POST /api/v1/task`	Execute a task with an agent
`GET /api/v1/tools`	List available tools
`GET /api/v1/agents`	List agents

See openapi.yaml for complete API specification.

Development

# Install dependencies
pnpm install
# Run backend in dev mode (hot reload)
pnpm dev
# Run web app in dev mode
pnpm --filter @async-agent/webapp dev
# Build all packages
pnpm build
# Run tests
pnpm test
# Clean all build outputs
pnpm clean
# Generate API clients from OpenAPI spec
pnpm generate

Database

# Generate migrations (after schema changes)
pnpm --filter backend db:generate
# Push schema changes to database
pnpm --filter backend db:push
# Open Drizzle Studio (DB GUI)
pnpm --filter backend db:studio

LLM Provider Support

OpenAI

Models: gpt-4, gpt-4-turbo, gpt-4o, gpt-3.5-turbo (1106+)
Validation: Whitelist check for tool calling support
Setup: Requires OPENAI_API_KEY

OpenRouter

Models: All models with function calling support
Validation: Runtime API check for capabilities
Setup: Requires OPENROUTER_API_KEY

Ollama (Local)

Models: mistral, mixtral, llama2 (tool support variants)
Validation: Sample tool call test at startup
Setup: Requires Ollama server running at OLLAMA_BASE_URL

The system validates tool calling support at startup and fails fast if the selected model is incompatible.

Example Use Case: AI News Monitor

Create a DAG that searches and summarizes AI news:

curl -X POST http://localhost:3000/api/v1/create-dag \
 -H "Content-Type: application/json" \
 -d '{
 "goal": "Search for the latest AI news, summarize the top 5 articles, and save to a markdown file",
 "schedule": "0 9 * * *",
 "timezone": "America/New_York"
 }'

The agent will autonomously:

Decompose the goal into a DAG of tasks
Search the web for recent AI news
Fetch and extract content from articles
Summarize findings using the LLM
Save results to a markdown file
Execute on schedule (daily at 9 AM ET)

Technology Stack

Backend

Fastify - Fast HTTP server with schema validation
Drizzle ORM - Type-safe SQLite ORM
node-cron - Job scheduling
OpenAI SDK - LLM integration
Pino - Structured logging

Web App

SvelteKit 5 - Full-stack framework
TailwindCSS - Utility-first CSS
bits-ui - Accessible UI components
Lucide Svelte - Icons

Shared

TypeScript - Type safety across packages
Zod - Runtime validation
pnpm workspaces - Monorepo management

Roadmap

Monorepo setup with pnpm workspaces
Multi-provider LLM abstraction layer
Shared types and schemas
Backend API structure
Database schema and migrations
DAG executor and planner
Tool registry and core tools
DAG scheduler with cron support
Auto-generated API clients (JS/Python)
Web dashboard (SvelteKit)
Real-time events (SSE)
Suspended state and resume functionality
CLI improvements
WebSocket support for bidirectional communication
Agent memory and learning
Plugin system for custom tools

License

MIT

Contributing

Contributions welcome! See AGENTS.md for development guidelines.

ugmurthy/asyncAgent

Folders and files

Latest commit

History

Repository files navigation