AgentFabric | Enterprise Multi-Agent Framework in TypeScript

A production-grade, multi-agent orchestration system built with Next.js, Drizzle ORM, and PostgreSQL. This system decomposes user goals into structured sequential workflows, coordinates specialized agents executing typed tools, streams results in real time, and persists all execution telemetry.

It is the TypeScript-based sibling of the Python AgentFabric | Enterprise Multi-Agent Framework in TypeScript, implementing the same core architectural rigor but optimized for modern web environments with Server-Sent Events (SSE) and full relational database schema enforcement.

---

Core Operating Philosophy & Workflow

The system is designed around a structured execution loop where tasks are planned by a centralized Orchestrator and run by isolated Specialist Agents with explicit boundaries.

graph TD
    User([User Goal]) -->|Post Request| API[/api/runs]
    API -->|Init Run & Save| DB[(PostgreSQL)]
    API -->|Stream Connection| SSE[SSE Route: /api/runs/:id/stream]
    SSE -->|Run Orchestrator| Orchestrator{Orchestrator Agent}
    Orchestrator -->|Generate Plan JSON| DB
    Orchestrator -->|Yield 'plan' event| SSE
    Orchestrator -->|Sequential Loop| Loop[For each Plan Step]
    Loop -->|Start Step| Agent[Agent: Researcher / Coder / Writer / Critic]
    Agent -->|Execute Tools| Tools[Tools: web_search / code_exec / summarise / calculator]
    Tools -->|Return Result| Agent
    Agent -->|Execute LLM Call| Agent
    Agent -->|Save Step & Tool Calls| DB
    Agent -->|Yield 'step_done' & 'tool_call' events| SSE
    Loop -->|Next Step| Loop
    Loop -->|Loop Finished| Final[Finalize Run]
    Final -->|Update status: completed| DB
    Final -->|Yield 'final' answer| SSE

Loading

Detailed Execution Phase:

1. Goal Input: The user submits a goal via the interactive dashboard UI (AgentOSShell.tsx).
2. Initialization: The backend initializes a new run record in PostgreSQL, sets its status to queued, and redirects the client to the live execution view.
3. SSE Connection: The UI opens an EventSource connection to the /api/runs/[id]/stream endpoint, starting the backend execution runner.
4. Dynamic Planning: The Orchestrator uses LLM intelligence to evaluate the user goal and generate a serialized plan consisting of a series of agent tasks (e.g., researcher $\rightarrow$ coder $\rightarrow$ writer $\rightarrow$ critic).
5. Sequential Execution: The orchestrator iterates through the plan steps. For each step:
   • Context Propagation: The executing agent receives the original user goal and a summary of all outputs generated by previous agents in the sequence.
   • Tool Interaction: Agents interact with their environment by invoking typed functions (e.g., searching web pages, executing generated code snippets).
   • Audit Trails: Every tool execution, input parameter, response payload, duration in milliseconds, and token usage count is stored in the database.
6. Streaming & Updates: Throughout the execution, step metrics, tool calls, logs, and agent summaries are streamed back to the client using Server-Sent Events (SSE) for a fluid, real-time UI experience.
7. Finalization: The run is updated in PostgreSQL as completed (or failed in case of error) and the final verified markdown response is presented in the UI.

---

Technology Stack

The project leverages a modern, typesafe stack designed for performance, modularity, and rapid local iteration:

• Framework & UI: Next.js (v16+) with the App Router, React 19, Tailwind CSS for fluid glassmorphic styling, and Lucide React for crisp vector iconography.
• Database & ORM: PostgreSQL (runs and steps table schemas) integrated via the pg client driver, structured and queried using Drizzle ORM, with Drizzle Kit managing migrations and DB visual inspections.
• AI Orchestration: OpenAI Node SDK for model completions, supporting modular model injection (gpt-4o-mini, gpt-4o, etc.).
• Agnostic Mock Mode: A local deterministic fallback engine that detects the absence of an API key and serves mock LLM responses. This allows you to launch, test, and run the entire interface and DB pipeline completely offline!

---

System Requirements

To run this application locally, verify your system meets the following specifications:

• Operating System: Windows 10/11, macOS, or Linux.
• Runtime: Node.js v18.x or higher (v20+ recommended) with npm or yarn/pnpm.
• Database: A local or cloud-hosted instance of PostgreSQL v14 or higher (e.g., Supabase, Neon, or local Docker container).
• API Configuration: An active OpenAI API Key (optional for the local mockup engine, but required to process real LLM completions).

---

Project Structure

The project has been organized to separate the database layer, agent logic, UI components, and API routing:

project/
├── drizzle.config.json         # Drizzle configuration options
├── package.json                # TS project dependencies and run scripts
├── tsconfig.json               # TypeScript compilation compiler settings
├── env-example                 # Environment variables template
├── src/
│   ├── app/                    # Next.js App Router Page layouts & endpoints
│   │   ├── layout.tsx          # Main html boilerplate wrapper
│   │   ├── page.tsx            # Dashboard home page route
│   │   ├── globals.css         # Custom Tailwind directives and styles
│   │   ├── AgentOSShell.tsx    # Primary UI client dashboard component
│   │   └── api/
│   │       ├── health/         # DB and API health check endpoint
│   │       └── runs/           # Run creation, details, and SSE execution stream routes
│   │
│   ├── components/             # Reusable UI dashboard elements
│   │   ├── AgentIcon.tsx       # Colored agent badges
│   │   ├── LiveStream.tsx      # SSE event handler and log listener
│   │   ├── RunCard.tsx         # Historical run indicators in the sidebar
│   │   ├── StepPanel.tsx       # Segmented step data display panels
│   │   └── MarkdownRenderer.tsx# Clean syntax-highlighting compiler
│   │
│   ├── db/                     # Relational database layer
│   │   ├── index.ts            # Client pooling instantiation
│   │   └── schema.ts           # Drizzle schema (runs, steps tables and enums)
│   │
│   └── lib/
│       └── agents/             # The micro-agent intelligence engine
│           ├── types.ts        # Shared TypeScript typings and interfaces
│           ├── llm.ts          # Core completion helper + mock engine fallback
│           ├── tools.ts        # Typed tools (search, sandbox code execution, math)
│           ├── orchestrator.ts # Orchestrator sequential planner
│           ├── researcher.ts   # Information gathering specialist
│           ├── coder.ts        # Script composition and validation specialist
│           ├── writer.ts       # Synthesizer and prose content compiler
│           └── critic.ts       # Assessment and validation specialist

Component Breakdown

File / Component	Role / Production Principle
drizzle.config.json	Configures Drizzle schemas, output migrations folder, and DB credentials.
schema.ts	Strictly-typed database schema mapping runs and steps tables, with enums and relationships.
index.ts (DB)	Global database pool connection setup, reusing connections in Next.js development mode.
types.ts	Centralized TypeScript declarations for agents, contexts, step summaries, and tool execution.
llm.ts	Single interface for LLM completions with transparent token usage metrics and automated deterministic mock fallbacks.
tools.ts	Registry of sandboxed simulations and mathematical validators.
orchestrator.ts	The central planner agent that uses LLM planning to structure, record, and dispatch agent runs sequentially.
AgentOSShell.tsx	The central dashboard web application with real-time reactive streaming, interactive goal triggers, and historical run panels.

---

Getting Started

1. Configure the Environment

Clone this repository and create a .env file in the root directory based on the env-example template:

# Core APIs
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini

# Database Connection
DATABASE_URL=postgresql://username:password@localhost:5432/migentic_db

Note

If you do not provide an OPENAI_API_KEY, the application automatically defaults to Mock Mode. You can still input goals, generate plans, stream steps, and view outputs, all running against your database!

2. Install Dependencies

Install all required Node modules using your preferred package manager:

npm install

3. Setup the Database

Push your Drizzle schema declarations directly to your PostgreSQL database:

npm run db:push

If you want to view or manage your tables visually in your browser, spin up the Drizzle Studio interface:

npm run db:studio

4. Run the Development Server

Launch the local Next.js development server:

npm run dev

Open your browser and navigate to http://localhost:3000 to interact with the dashboard.

---

Extension Paths (Future Improvements)

To scale the TypeScript Micro-Agentic system to a complex production scale, consider implementing the following upgrades:

• Robust Sandbox Code Execution: Upgrade the simple simulated JS executor inside src/lib/agents/tools.ts to execute inside secure micro-containers using third-party environments like E2B Sandboxes or isolated WASM containers.
• Vectorized Memory Store: Upgrade the previousSteps memory array into a long-term semantic search interface. Store embeddings using pgvector directly inside your PostgreSQL database to query contextual memory based on relevance.
• Integrate Production Search APIs: Replace the simulated web-search logic with a paid API key from Tavily API or Serper API to extract real-time web context with rich markdown source links.
• Multi-Modal Document Intake: Implement a file attachment wizard on the Next.js frontend supporting PDF, Word, and Image uploads, routing inputs to image vision models and document parsers.
• Observability and Tracing: Integrate open-source tracing libraries like LangSmith or Langfuse into src/lib/agents/llm.ts to log detailed step traces, cost audits, and latency graphs.
• Human-in-the-Loop Validation: Introduce validation stages where the Orchestrator pauses execution streams, prompting the user via websockets or API endpoints to approve, edit, or reject the plan before proceeding to the next agent.