ZeroGraph TS: A 300-Line TypeScript Framework for AI Agent Coding

ZeroGraph TypeScript is a minimalist LLM framework designed specifically for building AI agents. As a direct TypeScript port of PocketFlow, its primary objective is to advance agent-oriented programming by stripping away unnecessary bloat.

The entire framework consists of just 300 lines of code—roughly 10KB. It carries zero dependencies and avoids vendor lock-in entirely. By providing full type safety and native IDE support, it facilitates "Agentic Coding," where AI tools like Cursor can assist in generating new agent logic. It is fast, lightweight, and strikes a balance between capability and simplicity.

The architecture relies on Nodes to handle individual tasks and Flows to orchestrate them. Batch processing and asynchronous operations are supported out of the box.

Lightweight: 300 lines, 10KB total size. No fluff, no dependencies, and no lock-in.

Native TypeScript: Full type safety ensures your IDE understands every interaction.

Agentic Coding: Built to let AI agents build other agents, significantly accelerating productivity.

Installation

Install via npm or yarn:

npm install @u0z/zero-graph

or

yarn add @u0z/zero-graph

Quick Start

Define a node, wrap it in a flow, and execute.

import { Node, Flow } from '@u0z/zero-graph';

class GreetingNode extends Node {
  prep(shared: any): string {
    return shared.name || 'World';
  }

  exec(name: string): string {
    return `Hello, ${name}!`;
  }

  post(shared: any, prepRes: string, execRes: string): void {
    shared.greeting = execRes;
  }
}

const flow = new Flow(new GreetingNode());
const shared = { name: 'TypeScript' };
flow.run(shared);
console.log(shared.greeting); // "Hello, TypeScript!"

Nodes

A Node is the fundamental building block of the framework. Three methods handle the workload:

• prep: Retrieves data from shared storage.
• exec: Executes the core logic.
• post: Saves the results and determines the next step.

class MyNode extends Node {
  prep(shared: any): any {
    return shared.input;
  }

  exec(prepResult: any): any {
    return processData(prepResult);
  }

  post(shared: any, prepRes: any, execRes: any): string {
    shared.result = execRes;
    return 'default';
  }
}

Flows

Flows connect nodes together, allowing you to turn complex tasks into manageable sequences.

const nodeA = new NodeA();
const nodeB = new NodeB();
const nodeC = new NodeC();

nodeA.next(nodeB, 'success');
nodeA.next(nodeC, 'error');

const flow = new Flow(nodeA);
flow.run(shared);

Other Features

Batch Processing: Subclass BatchNode, implement exec for a single item, and execute using BatchFlow.

Async Support: Subclass AsyncNode, implement execAsync, and utilize AsyncFlow.runAsync.

Examples

The examples directory demonstrates several common patterns:

• Hello World: Basic node and flow configuration.
• Agent: A research agent integrated with web search.
• Workflow: A multi-step content generation pipeline.
• Batch Processing: Handling multiple items simultaneously.
• Async Operations: Managing non-blocking workflows.
• RAG: Implementing retrieval-augmented generation.
• Multi-Agent: Orchestrating agents that communicate with one another.

Documentation

Further resources are available for deeper implementation:

• Core Abstractions: Detailed guides on Node, Flow, and the Shared Store.
• Design Patterns: Implementation strategies for Agents, Workflows, RAG, and more.
• API Reference: Comprehensive documentation for all classes and functions.
• Migration Guide: Steps for moving from the Python-based PocketFlow to TypeScript.

Why ZeroGraph?

While most LLM frameworks are heavy and complex, ZeroGraph remains intentionally lean.

Building capable agents doesn't require a massive dependency tree; it requires clean abstractions and type safety. ZeroGraph delivers exactly that, and nothing more.