This guide introduces how to develop agent applications based on the RuleGo AI agent framework.

Core Advantage: JSON Declarative, Real-time Effect

Most AI agent frameworks (such as Eino, LangChain) require writing code to define agents. RuleGo's core difference is: just write JSON, no Go code needed, changes take effect in real-time.

Eino Approach: Write Go Code

Taking the Eino framework as an example, creating an agent with tools requires writing Go code that must be compiled before running:

// 1. Create model
chatModel, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
    Model:  "gpt-4o",
    APIKey: os.Getenv("OPENAI_API_KEY"),
})

// 2. Create tool
weatherTool, _ := tool.NewInvokableTool(&weatherToolInfo, weatherFunc)

// 3. Create agent, inject tools
agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Model: chatModel,
    ToolsConfig: adk.ToolsConfig{
        ToolsNodeConfig: compose.ToolsNodeConfig{
            Tools: []tool.BaseTool{weatherTool, calculatorTool},
        },
    },
})

// 4. Create Runner, execute
runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})
iter := runner.Query(ctx, "How's the weather in Beijing?")

Every time you modify the agent configuration (change model, add tools, modify prompts), you need to modify code -> compile -> redeploy.

RuleGo Approach: Write JSON

The same agent in RuleGo only requires a JSON configuration:

{
  "ruleChain": {"id": "weather-agent", "name": "Weather Assistant"},
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [{
      "id": "node_agent",
      "type": "ai/agent",
      "name": "Weather Assistant",
      "configuration": {
        "url": "https://ai.gitee.com/v1",
        "key": "${global.api_key}",
        "model": "GLM-5",
        "systemPrompt": "You are a weather assistant that can query weather information.",
        "tools": [
          {"type": "builtin", "name": "bash", "config": {"workDir": "/data/workspace"}}
        ]
      }
    }]
  }
}

Changes take effect in real-time after modification, no service restart needed. Update the JSON via API or visual editor, and the agent immediately uses the new configuration.

Comparison Summary

Dimension	Eino (Go Code)	RuleGo (JSON Declarative)
Definition method	Write Go code	Write JSON configuration
Change effect	Modify code -> compile -> deploy	Modify JSON -> real-time effect
Development barrier	Requires Go development skills	Understanding JSON is sufficient
Visual editing	Requires Eino DevOps tools	Native support for rule chain visual editor
Session management	Need to implement yourself	Built-in SessionAspect, ready to use
Aspect mechanism	5 callbacks (OnStart/OnEnd, etc.)	10 aspect interfaces, complete AOP system
Tool ecosystem	Need to implement tool.BaseTool interface in Go	Built-in 8 tools + MCP protocol auto-discovery
Multi-agent orchestration	Code orchestration graph/chain	Rule chain declarative orchestration, sub-agents as tools
Model switching	Build-time binding, immutable	Runtime dynamic switching, session-level model selection
Business integration	Requires additional development	Native rule engine, seamless integration with business logic

In short: Eino is an LLM programming framework for Go developers, RuleGo is an agent runtime for everyone.

Quick Start

1. Start the Service

package main

import (
    "github.com/rulego/rulego"
    agentaspect "github.com/rulego/rulego-components-ai/aspect"
    agentsession "github.com/rulego/rulego-components-ai/session"
)

func main() {
    // 1. Create RuleGo configuration
    ruleConfig := rulego.NewConfig(rulego.WithDefaultPool())

    // 2. Inject global variables (for ${global.xxx} references)
    ruleConfig.Properties.PutValue("root_dir", "/data")
    ruleConfig.Properties.PutValue("api_key", "sk-xxx")

    // 3. Create rule engine pool
    pool := rulego.NewRuleEnginePool(ruleConfig)

    // 4. Initialize session management + register aspects
    sessionMgr := agentsession.NewManager(agentsession.NewMemoryStorage(), nil)
    agentaspect.RegisterAspect("session", agentsession.NewBuiltinSessionAspect(sessionMgr))

    // 5. Load agent JSON (supports loading from file, database, API)
    pool.Load(ruleConfig, "weather-agent", agentJSON)

    // 6. Execute
    msg := rulego.NewMsg("USER_INPUT", "How's the weather in Beijing?", rulego.TEXT, nil)
    pool.OnMsg("weather-agent", msg)
}

2. Define Agent (Pure JSON)

{
  "ruleChain": {
    "id": "weather-agent",
    "name": "Weather Assistant",
    "additionalInfo": {
      "description": "Smart assistant for querying weather information"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [
      {
        "id": "node_agent",
        "type": "ai/agent",
        "name": "Weather Assistant",
        "configuration": {
          "url": "https://ai.gitee.com/v1",
          "key": "${global.api_key}",
          "model": "GLM-5",
          "systemPrompt": "You are a weather assistant. Use the bash tool to execute curl commands to query the weather API.",
          "params": {"temperature": 0.7},
          "tools": [
            {"type": "builtin", "name": "bash", "config": {"workDir": "/data/workspace"}}
          ]
        }
      }
    ]
  }
}

3. Real-time Updates

After the agent is running, you can update the configuration via API at any time without restarting:

# Update agent configuration (takes effect in real-time)
curl -X PUT http://localhost:8080/api/v1/rules/weather-agent \
  -H "Content-Type: application/json" \
  -d '{"ruleChain":{...new JSON configuration...}'

You can also modify through the visual editor with drag and drop:

# Open visual editor
# https://editor.rulego.cc

Typical Scenario: Building a Coding Assistant

The following demonstrates how to build a coding assistant agent similar to Claude Code using JSON.

Step 1: Prepare the Workspace

/data/workspace/
  IDENTITY.md      -> "You are a coding assistant, proficient in Go and Python"
  AGENTS.md        -> Code style guidelines, commit conventions
  SOUL.md          -> Concise, secure, testable
  skills/
    code-review/
      SKILL.md     -> Code review skill definition
    test-gen/
      SKILL.md     -> Test generation skill definition

Step 2: Define Agent JSON

{
  "ruleChain": {
    "id": "coding-agent",
    "name": "Coding Assistant",
    "additionalInfo": {
      "description": "Coding agent with file read/write and command execution capabilities"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [{
      "id": "node_agent",
      "type": "ai/agent",
      "name": "Coding Assistant",
      "configuration": {
        "url": "https://ai.gitee.com/v1",
        "key": "${global.api_key}",
        "model": "GLM-5",
        "maxStep": 100,
        "systemPrompt": "${include(global.root_dir+'/workspace/IDENTITY.md')}\n${include(global.root_dir+'/workspace/AGENTS.md')}\nCurrent time: ${now()}",
        "params": {"temperature": 0.7, "maxTokens": 16384},
        "tools": [
          {"type": "builtin", "name": "bash", "config": {"workDir": "${global.root_dir}/workspace"}},
          {"type": "builtin", "name": "read", "config": {"workDir": "${global.root_dir}/workspace"}},
          {"type": "builtin", "name": "write", "config": {"workDir": "${global.root_dir}/workspace"}},
          {"type": "builtin", "name": "edit", "config": {"workDir": "${global.root_dir}/workspace"}},
          {
            "type": "builtin", "name": "skill",
            "config": {
              "globalDirs": ["${global.root_dir}/skills"],
              "localDirs": ["${global.root_dir}/workspace/skills"]
            }
          }
        ]
      }
    }]
  }
}

Step 3: Extend as Needed

Add a sub-agent (code review) — just add an entry to the tools array:

{"type": "agent", "targetId": "code-reviewer"}

Switch to a stronger model — modify the model field, takes effect in real-time:

"model": "deepseek-reasoner"

Add MCP tools — automatically discover tools from MCP Server:

{"type": "mcp", "config": {"server": "http://localhost:8080/mcp"}}

The entire process requires no Go code, no compilation, and no restart.

Workspace System

Each agent can have an independent workspace directory, defining behavior and memory through Markdown files:

workspace/
  IDENTITY.md      Agent identity, role, capability description
  AGENTS.md        Behavior rules, collaboration rules, task routing
  SOUL.md          Core values, behavioral principles
  TOOLS.md         Tool usage guidelines and notes
  USER.md          User profile and preferences
  MEMORY.md        Long-term memory (manually maintained important information)
  HEARTBEAT.md     Heartbeat task queue (agent proactively checks and executes)
  BOOTSTRAP.md     First-run bootstrap (auto-deleted after execution)
  memory/          Daily memory logs (YYYY-MM-DD.md)
  skills/          Agent private skills
  rules/           Custom rule chains

The system prompt dynamically loads these files through ${include()}. Agents can modify them using the write and edit tools, enabling self-evolution.

Multi-Agent Orchestration

Sub-agent Invocation

Add an agent type tool in tools, and the main agent can invoke sub-agents:

{
  "tools": [
    {"type": "agent", "targetId": "code-reviewer", "name": "code_review", "description": "Code review"},
    {"type": "agent", "targetId": "test-generator", "name": "generate_tests", "description": "Generate tests"}
  ]
}

The LLM automatically decides when to invoke which sub-agent based on tool descriptions. The sub-agent's output is returned to the main agent as a tool result for continued reasoning.

Pipeline Mode

Agent nodes combined with JS filters, REST API call nodes, and other nodes to build deterministic routing:

User input -> [ai/agent intent classification] -> [jsFilter routing] -> True: [restApiCall execute] -> [end]
                                                          -> False: [end conversation]

Custom Aspects

Aspects are pluggable middleware that inject custom logic at different stages of agent execution. The application layer implements aspect interfaces in Go code and registers them to take effect automatically.

Command Interception (Around Aspect)

Intercept commands like /help, /model without consuming Tokens:

type CommandAspect struct{}

func (c *CommandAspect) Order() int { return 5 }
func (c *CommandAspect) New() aspect.Aspect { return &CommandAspect{} }
func (c *CommandAspect) PointCut(ctx context.Context, point *aspect.AgentPoint) bool { return true }

func (c *CommandAspect) Around(ctx context.Context, point *aspect.AgentPoint,
    input *aspect.AgentInput, next aspect.AgentExecutor) (*aspect.AgentOutput, error) {
    lastMsg := input.OriginalMessages[len(input.OriginalMessages)-1]
    if strings.HasPrefix(lastMsg.Content, "/") {
        result := handleCommand(lastMsg.Content)
        return &aspect.AgentOutput{Content: result, SkippedAI: true, IsSuccess: true}, nil
    }
    return next(ctx, input)
}

// Register
agentaspect.RegisterAspect("command", &CommandAspect{})

Session Management (Built-in Aspect)

The framework has a built-in SessionAspect that automatically manages conversation history after registration:

sessionMgr := agentsession.NewManager(agentsession.NewMemoryStorage(), nil)
agentaspect.RegisterAspect("session", agentsession.NewBuiltinSessionAspect(sessionMgr))

For more aspect examples, see [Aspect Framework](./04.Aspect Framework.md).

Skill System

Skills are defined as Markdown files. Agents invoke them by name through the skill tool:

---
name: code-review
description: Review code quality and provide improvement suggestions
---

# Code Review

Review specified code, focusing on: security, performance, readability.

## Steps
1. Use the read tool to read code files
2. Analyze code structure and potential issues
3. Output review report

Skills support two-level directories:

• Global skills (globalDirs): Shared by all agents
• Local skills (localDirs): Specific to individual agents

Agents can also create new skills in the skills/ directory using the write tool, enabling self-learning.

Related Documentation

• Overview — Framework positioning and core concepts
• [Architecture Design](./01.Architecture Design.md) — Layered architecture details
• [Agent Node](./02.Agent Node.md) — ReAct node concepts and advanced features
• Agent Component — Complete configuration reference for ai/agent component
• [Tool System](./03.Tool System.md) — Tool configuration and extension
• [Aspect Framework](./04.Aspect Framework.md) — Aspect interfaces and custom development
• [Session Management](./05.Session Management.md) — Session configuration and storage extension
• [Orchestration Examples](./07.Orchestration Examples.md) — Node orchestration patterns and examples
• [Application Case Study](./08.Application Case Study.md) — Complete smart assistant platform case study