A visual AI agent builder and execution platform — create, configure, connect, and run autonomous AI agents on a node-based canvas with real-time streaming.
- Overview
- Features
- Tech Stack
- Getting Started
- Project Structure
- Core Concepts
- Agent Engine
- API Reference
- UI Components
- Configuration
- Roadmap
- Contributing
- License
Agent Studio OS is a Figma-like visual platform for building, configuring, and running autonomous AI agents. Users create agents from templates or natural language descriptions, connect them into multi-step workflows on a visual canvas, and watch them execute in real-time with live streaming updates.
The platform implements the four foundational brains of an agentic system:
- Planner — "What should I do next?"
- Executor — "Do the thing"
- Memory — "What have I done?"
- Evaluator — "Am I done or nah?"
All AI capabilities are powered by Groq via its OpenAI-compatible chat API.
- React Flow-powered node graph with drag-and-drop agent placement
- Custom animated agent nodes with real-time status indicators (idle, running, success, error)
- Animated edges connecting agents into execution workflows
- Minimap, controls, and background grid
- Auto-layout for newly created agents
- Natural language agent creation — describe what you want, AI designs the agent config
- Intelligent tool selection, personality assignment, and step budgeting
- Three-step wizard: Describe → Review Config → Deploy
- Server-Sent Events (SSE) for real-time agent execution updates
- Step-by-step visualization: 🧠 Planning → ⚙️ Executing → 📊 Result
- Progress bar with current step tracking
- Kill switch to stop runaway agents
- Full agent configuration panel: name, goal, personality
- Tool toggles (Search, Write, Code, Browser) with visual badges
- Memory settings (short-term / long-term)
- Execution controls (max steps slider, auto-run toggle)
- Output format selector (text, JSON, markdown)
- Research Agent — search and synthesize information
- Content Writer — generate articles and marketing copy
- Code Assistant — write, review, and debug code
- Business Analyst — analyze data and generate insights
- Kill switch — instantly stop any running agent
- Max steps — configurable execution limit (1–20 steps)
- Step-based execution — no infinite loops, agents can pause and resume
- Auto/Manual modes — full auto-run or step-by-step human oversight
- All agents, runs, and steps are persisted to SQLite via Prisma ORM
- Full run history with step-by-step audit trail
- Agent configurations survive server restarts
| Category | Technology | Version |
|---|---|---|
| Framework | Next.js (App Router) | 16 |
| Language | TypeScript | 5 |
| Runtime | Bun | latest |
| Styling | Tailwind CSS | 4 |
| UI Components | shadcn/ui (New York) | latest |
| Database | Prisma + SQLite | 6.11 |
| State Management | Zustand | 5 |
| Visual Canvas | @xyflow/react (React Flow) | 12 |
| Animations | Framer Motion | 12 |
| AI Provider | Groq chat completions | OpenAI-compatible |
| Icons | Lucide React | latest |
| Forms | React Hook Form + Zod | 7.60 / 4 |
| Notifications | Sonner | 2 |
| Data Fetching | TanStack React Query | 5 |
| Reverse Proxy | Caddy | — |
- Bun runtime installed
- Node.js 18+ (for compatibility)
# Clone the repository
git clone https://github.com/doj-scraper/devAgenticOS.git
cd devAgenticOS
# Install dependencies
bun install
# Set up the database
bun run db:push
# Start the development server
bun run devThe app runs on port 3000 and is exposed via Caddy on port 81.
Create a .env file in the project root:
DATABASE_URL="file:./db/custom.db"
GROQ_API_KEY="your-groq-api-key"
GROQ_MODEL="llama-3.3-70b-versatile"The agent planner and evaluator call Groq directly through the OpenAI-compatible /chat/completions endpoint.
| Script | Command | Description |
|---|---|---|
dev |
bun run dev |
Start dev server on port 3000 |
lint |
bun run lint |
Run ESLint checks |
db:push |
bun run db:push |
Push Prisma schema to database |
db:generate |
bun run db:generate |
Generate Prisma client |
db:migrate |
bun run db:migrate |
Run database migrations |
db:reset |
bun run db:reset |
Reset the database |
my-project/
├── prisma/
│ └── schema.prisma # Database schema (Agent, AgentRun, Step)
├── db/
│ └── custom.db # SQLite database file
├── public/
│ ├── agent-studio-hero.png # Hero image
│ └── logo.svg # Z.ai logo
├── src/
│ ├── app/
│ │ ├── globals.css # Tailwind + dark theme + React Flow overrides
│ │ ├── layout.tsx # Root layout (fonts, metadata, Toaster)
│ │ ├── page.tsx # Home page → renders AgentStudio
│ │ └── api/
│ │ └── agent/ # 8 API route handlers
│ │ ├── build/ # AI agent builder
│ │ ├── create/ # Create agent
│ │ ├── list/ # List agents
│ │ ├── run/ # Start agent run
│ │ ├── runs/ # Get run history
│ │ ├── stop/ # Stop running agent
│ │ ├── stream/ # SSE streaming endpoint
│ │ └── update/ # Update agent config
│ ├── components/
│ │ ├── agent/
│ │ │ ├── agent-studio.tsx # Main 3-panel layout
│ │ │ ├── agent-canvas.tsx # React Flow visual canvas
│ │ │ ├── agent-sidebar.tsx # Left sidebar panel
│ │ │ ├── agent-inspector.tsx # Right config panel
│ │ │ ├── agent-run-view.tsx # Live execution view
│ │ │ ├── agent-node.tsx # Custom React Flow node
│ │ │ └── agent-builder-wizard.tsx # AI builder dialog
│ │ └── ui/ # 38+ shadcn/ui components
│ ├── lib/
│ │ ├── utils.ts # cn() helper
│ │ ├── db.ts # Prisma client singleton
│ │ └── agent/
│ │ ├── agent.ts # Agent engine (main loop, SSE, kill switch)
│ │ ├── types.ts # TypeScript type definitions
│ │ ├── planner.ts # AI planner + agent builder
│ │ ├── tools.ts # Tool execution layer
│ │ ├── memory.ts # In-memory agent memory
│ │ └── evaluator.ts # Goal completion evaluator
│ ├── store/
│ │ └── agent-store.ts # Zustand global state
│ └── hooks/
│ ├── use-mobile.ts # Mobile breakpoint hook
│ └── use-toast.ts # Toast state management
├── Caddyfile # Reverse proxy configuration
├── next.config.ts # Next.js configuration
├── tailwind.config.ts # Tailwind configuration
└── package.json # Dependencies and scripts
Every agent in Agent Studio OS operates with four cognitive components:
The decision-making brain. Given a goal, conversation context, available tools, and a personality, the planner uses an LLM to decide the next action — which tool to use and what input to provide.
Input: Goal + Memory + Tools + Personality
Output: { tool: "search" | "write" | "code" | "browser" | "finish", input: "..." }
The action layer. Takes a planned action and executes it using the appropriate tool. Currently supports:
- Search — Find information (simulated, ready for real API)
- Write — Generate text content (simulated, ready for LLM generation)
- Code — Generate and execute code (simulated, ready for sandboxed execution)
- Browser — Browse and interact with web pages (simulated, ready for browser automation)
- Finish — Mark the task as complete
Tracks what the agent has done. Each step records the action taken and its result. Memory is keyed by runId for concurrent execution support.
MemoryEntry = { step, action, result, timestamp }
Determines whether the agent's goal has been accomplished. Checks if the last action was "finish" or uses an LLM to evaluate based on the full history.
Every agent is defined by a standardized configuration:
type AgentConfig = {
name: string; // Display name
goal: string; // What the agent should accomplish
personality?: string; // Behavioral style
tools: ("search"|"write"|"code"|"browser")[]; // Available actions
memory: {
shortTerm: boolean; // Step-by-step context
longTerm: boolean; // Persistent knowledge (future)
};
loop: {
maxSteps: number; // Safety limit
autoRun: boolean; // Autonomous vs. manual
};
outputs: {
format: "text" | "json" | "markdown"; // Output type
};
};Instead of a blocking while loop, agents execute one step at a time. This is critical for SaaS:
- ✅ Can pause and resume
- ✅ Won't crash the server with long-running loops
- ✅ Each step is persisted to the database
- ✅ Events stream to the UI in real-time
- ✅ Kill switch works between steps
User clicks "Run"
│
▼
POST /api/agent/run ──► Creates AgentRun record
│ Starts runAgent() async
▼
runAgent() loop:
│
├── Emit "thinking" event
├── Call planner() → get next action
├── Emit "plan" event (action decision)
├── Emit "action" event (executing...)
├── Call execute() → get result
├── Save step to database
├── Emit "result" event
├── Call evaluator() → done?
│ ├── YES → Emit "done", update DB status
│ └── NO → Continue loop (with 500ms safety delay)
│
▼
SSE stream delivers all events to frontend in real-time
| Type | Color | Meaning |
|---|---|---|
status |
Gray | General status update |
thinking |
Gray | Agent is planning |
plan |
Purple | Agent decided on an action |
action |
Blue | Agent is executing a tool |
result |
Green | Tool returned a result |
error |
Red | Something went wrong |
done |
Green | Run completed |
- Max Steps — Configurable limit (1–20) prevents infinite loops
- Kill Switch —
POST /api/agent/stopinstantly terminates a run - Step Delay — 500ms between steps prevents server overload
- Active Run Tracking — In-memory
Setof active run IDs - DB Persistence — Every step is saved; runs survive interruptions
- Error Handling — Failed runs update status to "failed" in database
Create a new agent from a configuration object.
// Request
{
"name": "Research Agent",
"goal": "Find and analyze market trends",
"personality": "analytical and thorough",
"tools": ["search", "write"],
"shortTermMemory": true,
"longTermMemory": false,
"maxSteps": 10,
"autoRun": true,
"outputFormat": "markdown"
}
// Response
{
"id": "clx...",
"name": "Research Agent",
"goal": "Find and analyze market trends",
...
}List all agents with run counts.
Update an agent's configuration. Supports partial updates.
// Request
{
"id": "clx...",
"name": "Updated Name",
"tools": ["search", "write", "code"]
}Generate an agent configuration from natural language.
// Request
{
"userInput": "I want an agent that writes blog posts about AI and posts to Twitter",
"save": true
}
// Response
{
"config": {
"name": "AI Content Creator",
"goal": "Write and schedule blog posts about AI...",
"personality": "creative and engaging writer",
"tools": ["search", "write"],
"memory": { "shortTerm": true, "longTerm": true },
"loop": { "maxSteps": 8, "autoRun": true },
"outputs": { "format": "markdown" }
},
"agent": { "id": "clx...", "name": "AI Content Creator" }
}Start an agent run. Creates a run record and begins async execution.
// Request
{ "agentId": "clx..." }
// or
{ "goal": "Quick one-off task" }
// Response
{
"runId": "clx...",
"agentId": "clx...",
"status": "running",
"config": { "name": "...", "goal": "...", "tools": [...], "maxSteps": 10 }
}SSE endpoint for real-time execution events.
data: {"type":"status","message":"Agent \"Research Agent\" starting..."}
data: {"type":"thinking","message":"Planning step 1...","step":0}
data: {"type":"plan","message":"Decided to use search: Find market trends","step":0,"data":{"tool":"search","input":"Find market trends"}}
data: {"type":"action","message":"Executing search...","step":0}
data: {"type":"result","message":"Found relevant information...","step":0}
data: {"type":"done","message":"Goal accomplished!","step":0}
Stop a running agent immediately.
// Request
{ "runId": "clx..." }
// Response
{ "success": true, "runId": "clx...", "status": "stopped" }Query runs with optional filters.
| Parameter | Description |
|---|---|
?runId=xxx |
Get specific run with all steps |
?agentId=xxx |
Get all runs for an agent |
| (none) | Get all recent runs (50 max) |
┌─────────────────────── Top Bar ───────────────────────┐
│ ⚡ Agent Studio OS │ 3 agents │ ☰ Toggle Panels │
└────────────────────────────────────────────────────────┘
┌── Sidebar ──┐ ┌──────── Canvas ────────┐ ┌ Inspector ┐
│ 240px │ │ React Flow │ │ 300px │
│ │ │ • Agent Nodes │ │ │
│ Agent List │ │ • Animated Edges │ │ Name │
│ Templates │ │ • Minimap │ │ Goal │
│ AI Builder │ │ • Controls │ │ Tools │
│ Run History │ │ │ │ Memory │
│ │ │ [OR Run View when │ │ Steps │
│ │ │ agent is executing] │ │ Output │
└─────────────┘ └────────────────────────┘ └───────────┘
| Token | Value | Usage |
|---|---|---|
| Background | #0B0F17 |
Main background |
| Panel | #111827 |
Panels and cards |
| Panel2 | #0F172A |
Sidebars |
| Border | #1F2937 |
All borders |
| Text | #E5E7EB |
Primary text |
| Muted | #9CA3AF |
Secondary text |
| Accent | #7C3AED |
Primary accent (purple) |
| Success | #22C55E |
Completed states |
| Danger | #EF4444 |
Error states |
| Warning | #F59E0B |
Code tool color |
| Status | Visual Effect |
|---|---|
| Idle | Dim border, gray status pill |
| Running | Purple pulsing glow, spinning loader |
| Success | Green border, checkmark icon |
| Error | Red border, alert icon |
model Agent {
id String @id @default(cuid())
name String
goal String
personality String @default("helpful assistant")
tools String @default("search,write,code") // comma-separated
shortTermMemory Boolean @default(true)
longTermMemory Boolean @default(false)
maxSteps Int @default(10)
autoRun Boolean @default(true)
outputFormat String @default("markdown")
graphData String? // JSON for React Flow state
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
runs AgentRun[]
}
model AgentRun {
id String @id @default(cuid())
agentId String
agent Agent @relation(fields: [agentId], references: [id], onDelete: Cascade)
status String @default("pending") // pending|running|completed|failed|stopped
result String?
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
steps Step[]
}
model Step {
id String @id @default(cuid())
runId String
run AgentRun @relation(fields: [runId], references: [id], onDelete: Cascade)
stepNum Int
tool String // search|write|code|browser|finish
input String
result String
createdAt DateTime @default(now())
}- Real Tool Implementations — Wire search to web search API, write to LLM generation, code to sandboxed execution
- Long-Term Memory — Vector embeddings with similarity search for persistent agent knowledge
- Agent Graph Persistence — Save/load React Flow canvas layouts per agent
- Drag-and-Drop Agent Creation — Drag templates from sidebar directly onto canvas
- Multi-Step Planning — Generate full execution plans before starting, not just one action at a time
- Output Rendering — Render agent results as formatted markdown, code blocks, or structured data
- Multi-Agent Workflows — Sequential and parallel agent execution with data passing between nodes
- Graph Execution Engine — Topological sort of agent DAG, parallel branch execution
- Human Approval Mode — Gate risky actions (email, payments, API calls) behind user confirmation
- Agent Marketplace — Publish, share, clone, and sell agent configurations
- Self-Reflection Loop — Agent reviews its own work, identifies mistakes, retries failed steps
- Plugin System — User-defined tools with sandboxed execution (isolated VM threads)
- Authentication — NextAuth.js integration with user-scoped agents and runs
- Real-Time Collaboration — Multiplayer canvas (teams building agents together)
- Streaming Token Output — ChatGPT-style typing animation for agent responses
- Voice Output — TTS integration for agents that "talk back"
- Stripe Monetization — Subscription tiers (Free: 2 agents, Pro: unlimited, Premium: advanced tools)
- Performance Analytics — Dashboard showing agent success rates, step efficiency, cost tracking
- Custom LLM Models — Let users choose between different AI models for planning and evaluation
- Webhook Triggers — Agents triggered by external events (cron, webhooks, integrations)
- Deployment — One-click deploy agents as API endpoints or scheduled tasks
- Mobile Responsive — Collapsible panels and touch-friendly canvas interactions
- Agent That Builds Agents — Meta-agent that creates specialized agents on demand
- Auto-Hustle Agent — Finds flipping opportunities on marketplaces
- SEO Blog Agent — Generates ranked articles automatically
- Business-in-a-Box Agent — Enter an idea → get branding, landing page copy, pricing strategy
- Multi-Agent Live View — Watch multiple agents communicate and collaborate in real-time
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Use TypeScript throughout with strict typing
- Follow the existing component structure (shadcn/ui + Tailwind)
- Keep the dark theme consistent with the design tokens
- All LLM calls must use the Groq adapter in
src/lib/agent/groq.ts - API routes should return proper error responses
- Run
bun run lintbefore submitting
MIT
Built with ⚡ on Groq