DelReact Agent Framework Documentation

Overview

DelReact Agent is an extensible TS/JS framework for building intelligent AI agents that can autonomously plan, reason, and act to accomplish complex, multi-step tasks.

tl;dr: DelReact is like a super-smart libraries for your code/product extension. It can think, plan, and use tools to finish big jobs all by itself. You just tell it what you want, and it figures out the steps, finds answers, and gets things done—kind of like a person who can read, search, and solve problems for you. It learns and adapts as it works, so you don’t have to do everything by hand.

See What is AI Agent for complete concept overview

Quick Start

Installation & Setup

# minimum nodejs version >= 18.0.0
# other minimum environment: npm >= 8.0.0, Typescript >= 4.7 (for TS projects), internet connection for LLM/tool APIs
npm i delreact-agent
# npm i dotenv

Set up environment variables:

# .env
GEMINI_KEY=your_gemini_api_key  # Pick One or Both
OPENAI_KEY=your_openai_api_key  # Pick One or Both

Basic Usage

import dotenv from "dotenv";
import { ReactAgentBuilder } from "delreact-agent";

dotenv.config();

const agent = new ReactAgentBuilder({
  openaiKey: process.env.OPENAI_KEY,  // example using openai
  useEnhancedPrompt: true
})
.init({
  selectedProvider: 'openai',
  model: 'gpt-4o-mini',
  maxTasks: 8,
})
.build();

const result = await agent.invoke({
  objective: "What is GDP of second winner on 2022 World Cup?",
  outputInstruction: "Present it in structured sections: Summary, GDP, Year, Country"
});

console.log(result.conclusion);
// Summary: The question asks for the GDP of the runner-up in the 2022 FIFA World Cup.\n\nGDP: $2.924 trillion\n\nYear: 2022\n\nCountry: France\n

• ReactAgentBuilder Reference - Quick start examples

Example Use Cases

Content Creation

const result = await agent.invoke({
  objective: "Create hooks and captions for Instagram Post about Indonesia Corruption this past month. Focusing on big cases.",
  outputInstruction: "1-2 paragraphs caption, with emotional hooks in markdown format Bahasa Indonesia. Just content without any discussions"
});

Business Analysis API

const result = await agent.invoke({
  objective: "Analyze competitor pricing strategies in the Accounting SaaS market in Indonesia recently",
  outputInstruction: "A JSON format object with properties: summary, insights, recommendations"
});

Finance Analysis Report

const result = await agent.invoke({
  objective: "Research and analyze CDIA Stock News Indonesia?",
  outputInstruction: "Present it in structured sections: Summary, Key Insights, Industry Insight, Market Impact, Future Outlook"
});

DelReact Agent Core Components

1. ReactAgentBuilder

The main orchestration class that manages the agent workflow.

Key Features:

• Multi-provider LLM support (Gemini, OpenAI, Openrouter)
• Session management and tracking
• Built-in error handling and recovery
• Dynamic task replanning

2. Tool System

Registry-based tool management with dynamic availability and MCP integration.

Key Features:

• Dynamic tool registration and availability
• Config-aware tool injection
• Structured schema validation with Zod
• Built-in tools: web search, content fetching, prompt enhancement
• MCP (Model Context Protocol) support for external tool servers

Add custom tools to enhance agent capabilities:

const customTool = createAgentTool({
  name: "custom-calculator",
  description: "Perform custom calculations",
  schema: {
    operation: { type: "string", description: "Type of calculation" },
    values: { type: "array", description: "Input values" }
  },
  async run({ operation, values }) {
    // Tool implementation
    return { result: "calculation result" };
  }
});

const agent = new ReactAgentBuilder({
  geminiKey: process.env.GEMINI_KEY,
  ...
})
.addTool([customTool])
.init(...)
.build();

🔧 Tool System Reference 🔧 MCP Reference

3. Core Agent Pipeline

The framework uses a 5-stage workflow:

1. Enhance Prompt (optional) - Improves user prompts for clarity and precision
2. Task Breakdown - Decomposes objectives into executable tasks
3. Action Execution - Processes individual tasks with available tools
4. Task Replanning - Dynamically adjusts remaining tasks based on progress
5. Completion - Synthesizes results into final output

graph TD
    A[User Request] --> B[ReactAgentBuilder]
    B --> C[Enhance Prompt Agent]
    C --> D[Task Breakdown Agent]
    D --> E[Action Agent/Subgraph]
    E --> F[Task Replanning Agent]
    F --> G{More Tasks?}
    G -->|Yes| E
    G -->|No| H[Completion Agent]
    H --> I[Final Result]
    
    subgraph "State Management"
        J[AgentState]
        K[State Channels]
    end
    
    subgraph "Tool System"
        L[Tool Registry]
        M[Web Search]
        N[Content Fetching]
        O[Custom Tools]
    end
    
    subgraph "LLM Integration"
        P[Gemini AI]
        Q[OpenAI]
        R[Helicone Observability]
    end
    
    E -.-> J
    F -.-> J
    E --> L
    L --> M
    L --> N
    L --> O
    E -.-> P
    E -.-> Q
    P -.-> R
    Q -.-> R

4. Custom Workflow Agent

Build multi-agent workflows with specialized agents and RAG-powered knowledge integration.

import { ReactAgentBuilder } from "delreact-agent";

const builder = new ReactAgentBuilder({
  geminiKey: process.env.GEMINI_KEY,
  openaiKey: process.env.OPENAI_KEY,
});

// Create specialized agents
const ClassifierAgent = builder.createAgent({
  name: "IssueClassifier",
  model: "gemini-2.0-flash",
  provider: "gemini",
  description: "Categorize customer issues"
});

const SupportAgent = builder.createAgent({
  name: "CustomerSupport", 
  model: "gpt-4o-mini",
  provider: "openai",
  description: "Handle support with knowledge base",
  rag: {
    vectorFiles: ["./knowledge/support-docs.json"],
    embeddingModel: "text-embedding-3-small"
  }
});

// Build linear workflow
const workflow = builder.createWorkflow("CustomerService")
  .start(ClassifierAgent)
  .then(SupportAgent)
  .then(SummaryAgent)
  .build();

const result = await workflow.invoke({
  objective: "I can't log into my account"
});

Key Features:

• Multi-agent orchestration with sequential processing
• RAG integration for knowledge-enhanced responses
• 3-phase execution (Plan → Process → Validate) per agent
• Memory management for context-aware processing

🔧 Custom Workflow Reference

Configuration

Environment Variables

# Required: At least one LLM provider key
GEMINI_KEY=your_gemini_api_key
OPENAI_KEY=your_openai_api_key

# Optional: Helicone configuration
BRAVE_API_KEY=your_bravesearch_api_key
HELICONE_KEY=your_helicone_key

ReactAgentBuilder Configuration

const agent = new ReactAgentBuilder({
  geminiKey: process.env.GEMINI_KEY,
  openaiKey: process.env.OPENAI_KEY, // required at least one LLM provider key
  openrouterKey: process.env.OPENROUTER_KEY, // required at least one LLM provider key
  braveApiKey: process.env.BRAVE_API_KEY,  // For web search
  useEnhancedPrompt: true,  // Enable prompt enhancement
  memory: "in-memory",      // or "postgres", "redis"
  enableToolSummary: true   // LLM summary of tool results
})
.init({
  selectedProvider: "gemini",  // or "openai | openrouter"
  model: "gemini-2.5-flash"
})
.build();

// Runtime configuration updates
agent.updateConfig({
  selectedProvider: "openai",
  enableToolSummary: false
});

Monitoring & Observability

Built-in Session Tracking

Every execution generates a unique session ID for tracking:

const result = await agent.invoke({
  objective: "Task to track",
  sessionId: "custom-session-id"  // Optional
});

console.log("Session ID:", result.sessionId);

Helicone Integration

Automatic integration with Helicone for:

• Request/response logging
• Session correlation
• Performance monitoring
• Cost tracking

Contributing

Development Setup

1. Clone the repository
2. Install dependencies: npm install
3. Set up environment variables
4. Start demo: npm run demo

See Contributing Guide for further information

License & Commercial Use

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Commercial use of this software (including use in proprietary products, SaaS, or as part of a paid service) requires explicit written permission from the author/company.

Attribution in product documentation and source code is required for all uses. For commercial licensing, please contact Delegasi-Tech (or the repository owner).

Support

Documentation

📚 Complete Documentation Website - Full documentation with examples and guides

🤖 llm.txt - LLM-friendly complete documentation aggregation for AI assistants and Copilot

Local Documentation Files:

• ReactAgentBuilder Guide - Complete usage guide
• Tool System Guide - Custom tool development
• RAG Integration Guide - Full RAG setup and performance tuning

For Contributors:

• GitHub Pages Setup Guide - How to set up GitHub Pages for documentation deployment
• llm.txt Maintenance Guide - Guidelines for updating LLM-friendly documentation

For further disclaimer see NOTICE