rulego-components-ai

A Declarative AI Agent Development Framework

A declarative AI agent development framework built on the RuleGo rule engine. It can be used to develop standalone AI agents or serve as the foundation for building AI coding assistants like Claude Code / OpenClaw. It adopts the rule chain as agent design philosophy, embedding LLM reasoning capabilities into event-driven rule chain workflows. Through JSON declarative configuration, 10 AOP aspects, unified abstraction of four tool categories, and multi-dimensional session management, it enables building production-grade agent applications.

Full Documentation: Docs

Differences from Mainstream Frameworks

Core Features

• Rule Chain as Agent — Agents are defined declaratively in JSON and can be freely composed with other rule engine nodes (REST calls, JS filters, message queues, etc.) to build hybrid pipelines of AI reasoning and business orchestration
• 10 AOP Aspects — Covering the complete agent execution lifecycle (start/before/around/after/completed/pre-LLM/post-LLM/stream-chunk/pre-tool-call/post-tool-call), with PointCut condition matching and Order priority
• Unified Abstraction of Four Tool Categories — 4 atomic tools (bash/read/write/edit) form the perception-creation-execution-evolution capability loop; rule chain tools (expose any business process as a tool), sub-agent tools (multi-agent collaboration), MCP bidirectional protocol (client + server)
• Skill System — Compatible with the SKILL.md format used by Claude Code / OpenClaw and other AI coding assistants, supporting multi-directory aggregation, fingerprint caching, and automatic hot-reloading
• Multi-dimensional Session Management — 6 scopes (global/per-user/per-channel/per-thread/per-task), automatic LLM compression and intelligent pruning
• Runtime Model Switching — Session-level dynamic model switching via decorator chains; the same agent can use different models for different users
• ReAct Reasoning Loop — Supports synchronous/streaming execution, multimodal input, automatic retry
• MCP Bidirectional Protocol — Acts as both MCP client (consuming external tools) and MCP server (exposing rule chains as MCP tools)
• Intent Recognition — LLM classification and embedding vector similarity approaches
• OpenAI Compatible — Streaming response processor, standard Chat Completions API output

Module Structure

ai/
├── agent/          # Core ReAct agent node (type: ai/agent)
│   └── lite/       #   Same-type lightweight implementation of ai/agent
│                   #   (stdlib-only, no eino/sonic, compiles on 32-bit)
├── action/         # Simple LLM operation nodes
│                   #   - ai/llm       Text generation
│                   #   - ai/createImage Image generation
├── intent/         # Intent recognition nodes
│                   #   - ai/intent     LLM-based
│                   #   - ai/localIntent Embedding vector-based
├── aspect/         # AOP aspect framework
│   └── builtin/    #   Built-in aspects (logging, session, visualization)
├── config/         # Shared configuration types and model capability registry
├── constants/      # Constants (provider URLs, model names, timeouts)
├── embedding/      # Lightweight embedding client + cosine similarity
├── endpoint/       # MCP Server endpoint (rule chains exposed as MCP tools)
├── errors/         # Structured error codes (AgentError with Retryable)
├── mcp/            # MCP client node (calling remote MCP services)
├── processor/      # OpenAI-compatible streaming response processor
├── session/        # Session/conversation history management
├── tool/           # Tool registry + built-in tool implementations
│   ├── bash/       #   Shell command execution
│   ├── read/       #   File reading and search
│   ├── write/      #   File writing
│   ├── edit/       #   File editing (line-level, search-replace)
│   ├── browseruse/ #   Browser automation (chromedp)
│   ├── glob/       #   File pattern matching
│   ├── grep/       #   Content search (regex + literal)
│   ├── mcp/        #   MCP tool adapter (self + remote mode)
│   └── skill/      #   Skill invocation
├── utils/          # Utility functions
│   ├── contextx/   #   Type-safe Context Key
│   ├── image/      #   Image loading, Base64 conversion
│   ├── llm/        #   LLM response parsing
│   ├── doomloop/   #   Repeated tool-call doom loop detection
│   ├── token/      #   Token estimation and metrics collection
│   └── tool/       #   Tool parameter JSON Schema parsing
└── all/            # One-liner import for all components

Quick Start

Installation

go get github.com/rulego/rulego-components-ai

Import Components

Import all components in one line:

import _ "github.com/rulego/rulego-components-ai/all"

Import on demand:

import (
    _ "github.com/rulego/rulego-components-ai/agent"
    _ "github.com/rulego/rulego-components-ai/tool/bash"
    _ "github.com/rulego/rulego-components-ai/tool/read"
)

Minimal Example: Using an AI Agent in a Rule Chain

Here is a complete agent rule chain JSON configuration with the node type ai/agent:

{
  "ruleChain": {
    "id": "my-agent",
    "name": "My Assistant"
  },
  "nodes": [
    {
      "id": "s1",
      "type": "ai/agent",
      "configuration": {
        "url": "${global.llm.url}",
        "key": "${global.llm.key}",
        "model": "glm-5.1",
        "systemPrompt": "You are a helpful assistant.",
        "maxStep": 50,
        "params": {
          "temperature": 0.7
        },
        "tools": [
          {"type": "builtin", "name": "bash"},
          {"type": "builtin", "name": "read"},
          {"type": "builtin", "name": "write"}
        ]
      }
    }
  ]
}

Load and execute via Go code:

package main

import (
    "context"
    "fmt"

    _ "github.com/rulego/rulego-components-ai/all"
    "github.com/rulego/rulego/api/types"
    "github.com/rulego/rulego/rulego"
)

func main() {
    // 1. Create a RuleGo instance
    config := rulego.NewConfig()
    ruleEngine := rulego.NewRuleGo()

    // 2. Load the agent rule chain (JSON as above)
    chainJson := `{"ruleChain":{"id":"my-agent","name":"My Assistant"},"nodes":[{"id":"s1","type":"ai/agent","configuration":{"url":"https://open.bigmodel.cn/api/paas/v4","key":"your-api-key","model":"glm-5.1","systemPrompt":"You are a helpful assistant.","tools":[{"type":"builtin","name":"bash"}]}}]}`

    _, err := ruleEngine.OnLoad(chainJson, types.WithConfig(config))
    if err != nil {
        panic(err)
    }

    // 3. Send a message to the agent
    msg := rulego.NewMsg(0, "user", types.JSON, map[string]string{}, "What's the weather like today?")
    ruleEngine.OnMsg(msg, rulego.WithContext(context.Background()))

    // Note: In production, retrieve responses via callback or endpoint
    fmt.Println("Message sent")
}

Node Types

Two implementations share the type name ai/agent: the full version in agent (eino) and the lightweight version in agent/lite (stdlib-only, 32-bit platforms, failover, skills injection). When both packages are imported, the first one to register wins — the all bundle imports the eino version first; import agent/lite alone (or in 32-bit builds) to get the lightweight one. I/O contracts (request messages, SSE frames, metadata) are identical; see the comparison table below. The standalone type name ai/agentLite is retired.

ai/agent implementation comparison

Agent Configuration (ai/agent)

{
  "url": "https://open.bigmodel.cn/api/paas/v4",
  "key": "your-api-key",
  "model": "glm-5.1",
  "systemPrompt": "System prompt, supports ${variable} and ${include(\"/path/to/file\")} file references",
  "messages": [
    {"role": "user", "content": "Preset messages for scheduled task scenarios"}
  ],
  "images": ["https://example.com/image.png"],
  "params": {
    "temperature": 0.7,
    "topP": 0.9,
    "maxTokens": 4096,
    "responseFormat": "text",
    "extraFields": {
      "thinking_budget_tokens": 8192
    }
  },
  "maxStep": 50,
  "maxToolOutputLength": 5000,
  "maxRetries": 3,
  "tools": [
    {"type": "builtin", "name": "bash"},
    {"type": "rulechain", "name": "myChain", "targetId": "chain-001"},
    {"type": "agent", "name": "subAgent", "targetId": "sub-agent-001", "description": "Sub-agent"},
    {"type": "mcp", "name": "mcpTools", "config": {"serverUrl": "http://localhost:8080/mcp"}}
  ]
}

Tool Types

4 Atomic Tools

These 4 atomic tools form the agent’s capability loop: Perceive the environment → Create content → Execute operations → Evolve improvements.

Skill System

Skills are reusable capability units defined via SKILL.md files, compatible with the skill format used by Claude Code / OpenClaw and other mainstream AI coding assistants:

skills/
  code-review/
    SKILL.md
  refactor/
    SKILL.md

SKILL.md format (YAML frontmatter + Markdown):

---
name: code-review
description: Code review skill
---
Please perform a comprehensive code review, focusing on: security, performance, maintainability...

Features:

• Mainstream Format Compatible — Fully compatible with Claude Code’s SKILL.md format; reuse existing skill ecosystems directly
• Multi-directory Aggregation — Supports priority overlay of user directory > global directory; higher-priority skills override lower-priority ones
• Auto Hot-reload — FNV-1a fingerprint-based caching; automatically reloads on file changes without restart
• Multiple Execution Modes — inline (execute in current agent), fork (execute in independent sub-agent), fork_with_context (sub-agent with context)

Aspect Framework (AOP)

The aspect framework allows inserting cross-cutting concerns (logging, sessions, visualization, etc.) without modifying the agent’s core logic.

10 Aspect Interfaces

Built-in Aspects

Register Custom Aspects

import "github.com/rulego/rulego-components-ai/aspect"

// Register a global aspect
aspect.RegisterAspect("my_aspect", &MyAspect{})

Session Management

import agentsession "github.com/rulego/rulego-components-ai/session"

// Create an in-memory session manager
storage := agentsession.NewMemoryStorage()
manager := agentsession.NewManager(storage, &agentsession.SessionConfig{
    MaxMessages:   100,
    MaxTokenCount: 100000,
    Pruning: agentsession.PruningConfig{
        Enabled:         true,
        KeepRecentCount: 10,
    },
})

// Auto-integrate into agent via SessionAspect
sessionAspect := builtin.NewSessionAspect(manager, builtin.SessionAspectConfig{})
aspect.RegisterAspect("session", sessionAspect)

Session Scopes

Related Documentation

• RuleGo Docs — RuleGo rule engine documentation
• Eino Framework — Agent framework

License

Apache License 2.0