ZeroGraph: a lightweight AI agent programming framework

General Introduction

ZeroGraph is a lightweight open source framework designed for AI agent programming, developed in TypeScript, with only 300 lines of code (~10KB) and no dependencies. It is based on nodes (Node) and flow (Flow) architecture , support for rapid construction of efficient AI agent workflow . ZeroGraph provides type safety and strong IDE support , suitable for developers to create from simple greetings to complex multi-agent collaboration tasks . Based on the MIT license, the project is well documented, rich in examples, and easy to get started with, making it ideal for a wide range of research and development scenarios.

Function List

• Node and Flow Architecture : Modular task processing and flow orchestration through the Node and Flow classes.
• Lightweight design : Only 300 lines of code, no dependencies, runs efficiently and without vendor lock-in.
• type safety : TypeScript native support with full type-checking and IDE hints.
• Batch support : Processing multiple pieces of data through a BatchNode improves processing efficiency.
• asynchronous operation : AsyncNode support, suitable for asynchronous tasks such as network requests.
• Agent Programming : Support for complex workflows such as multi-agent collaboration, retrieval augmentation generation (RAG), etc.
• Rich Examples : Provides sample code from basic to advanced, such as greetings, search, and multi-agent collaboration.

Using Help

Installation process

ZeroGraph is developed in TypeScript and requires Node.js and npm/yarn to be installed, here are the installation steps:

1. environmental preparation
   • Make sure to install Node.js (recommended 16+) and npm/yarn.
   • Validate the environment:

     node -v
     npm -v
     

   • Optional: Install TypeScript to support type checking:

     npm install -g typescript
     

2. Install ZeroGraph
   Use npm to install:

   npm install @u0z/zero-graph
   

   or use yarn:

   yarn add @u0z/zero-graph
   

3. Verify Installation
   Create a simple TypeScript file (e.g. test.ts) and run the following code:

   import { Node, Flow } from '@u0z/zero-graph';
   console.log("ZeroGraph installed successfully!");
   

   Compile and run:

   tsc test.ts
   node test.js
   

   If a success message is output, the installation was done correctly.

Main Functions

1. Node and Flow

At the heart of ZeroGraph are Node and Flow, with Node handling a single task and Flow orchestrating multiple nodes. Steps:

• Defining Nodes : Create an inheritance Node class that contains the prep(Prepare data),exec(execution logic) and post(store results) method. Example:

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;
}
}

• Creating Streams : Connect the node with Flow and run it:

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

2. Batch Processing

BatchNode is suitable for processing multiple pieces of data. Operation steps:

• Defining batch nodes ::

class BatchProcessor extends BatchNode {
exec(item: any): any {
return `Processed: ${item}`;
}
}

• Running a batch stream ::

const batchFlow = new BatchFlow(new BatchProcessor());
const items = ['item1', 'item2', 'item3'];
batchFlow.run(items).then(results => console.log(results));

3. Asynchronous operations (Async Support)

AsyncNode supports asynchronous tasks such as API calls. Operational steps:

• Defining Asynchronous Nodes ::

class AsyncProcessor extends AsyncNode {
async execAsync(input: any): Promise<any> {
return new Promise(resolve => setTimeout(() => resolve(`Processed: ${input}`), 1000));
}
}

• Running an asynchronous stream ::

const asyncFlow = new AsyncFlow(new AsyncProcessor());
const shared = { input: 'test' };
asyncFlow.runAsync(shared).then(() => console.log(shared.result));

4. Multi-agent collaboration

ZeroGraph supports multi-agent workflows. Operational steps:

• Defining multiple nodes : Create multiple Node classes to handle different tasks.
• connection node : By next method specifies the jump logic between nodes:

class NodeA extends Node {
exec(input: any): string {
return input ? 'success' : 'error';
}
}
class NodeB extends Node {
exec(input: any): string {
return 'Task B done';
}
}
const nodeA = new NodeA();
const nodeB = new NodeB();
nodeA.next(nodeB, 'success');
const flow = new Flow(nodeA);
flow.run({ input: true });

5. Example code use

ZeroGraph provides a wealth of examples in the examples/ Catalog. Operating Procedure:

• clone warehouse ::

git clone https://github.com/u-0-z/zero-graph.git
cd zero-graph

• running example : Enter examples/ directory to run a specific example:

cd examples/hello-world
npm install
ts-node index.ts

• Examples include basic greetings (hello-world), search agents (agent), content generation (workflow), batch processing (batch), asynchronous operations (async), retrieval enhancement generation (rag), and multi-agent collaboration (multi-agent).

caveat

• TypeScript Configuration : Ensure that the project contains tsconfig.json, recommended settings:

{
"compilerOptions": {
"target": "ES6",
"module": "commonjs",
"strict": true
}
}

• Document Access : The full documentation is located at docs/ Catalog covering core concepts, design patterns, and API references.
• Community Support : Check GitHub Issues or submit a new issue if you encounter problems.

application scenario

1. AI Agent Rapid Prototyping
   ZeroGraph's lightweight design lends itself to rapid prototyping of AI agents. For example, developers can create a search agent that combines web APIs to enable real-time information retrieval.
2. Automated workflows
   In content generation or data processing scenarios, ZeroGraph orchestrates multi-node workflows, such as automating article generation or processing batch data.
3. Education and Research
   Students and researchers can learn TypeScript and AI agent programming with ZeroGraph, with sample code suitable for teaching and experimentation.

QA

1. What is the difference between ZeroGraph and LangChain?
   ZeroGraph is only 300 lines of code and focuses on lightweight AI agent programming, with no dependencies and TypeScript natively, while LangChain is more complex and has a large amount of code (405K lines), making it suitable for large projects but with a performance overhead.
2. Need TypeScript experience?
   Basic JavaScript knowledge is sufficient to get started, and TypeScript's type-safety features are automatically prompted by the IDE, reducing the learning curve.
3. How do I debug my code?
   Use an IDE such as VS Code in conjunction with a TypeScript debugging tool. Run ts-node Execute the code and view the console output or log.
4. What complex tasks are supported?
   Supports multi-agent collaboration, retrieval-enhanced generation (RAG), and asynchronous workflows for scenarios such as search and content generation.