本指南介绍如何基于 RuleGo AI 智能体框架开发智能体应用。

核心优势：JSON 声明式，实时生效

大多数 AI 智能体框架（如 Eino、LangChain）需要编写代码来定义智能体。RuleGo 的核心差异是：只需编写 JSON，无需写 Go 代码，修改后实时生效。

Eino 方式：编写 Go 代码

以 Eino 框架为例，创建一个带工具的智能体需要编写 Go 代码，编译后才能运行：

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

// 2. 创建工具
weatherTool, _ := tool.NewInvokableTool(&weatherToolInfo, weatherFunc)

// 3. 创建智能体，注入工具
agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Model: chatModel,
    ToolsConfig: adk.ToolsConfig{
        ToolsNodeConfig: compose.ToolsNodeConfig{
            Tools: []tool.BaseTool{weatherTool, calculatorTool},
        },
    },
})

// 4. 创建 Runner，执行
runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})
iter := runner.Query(ctx, "北京天气怎么样？")

每次修改智能体配置（换模型、加工具、改提示词），都需要改代码 → 编译 → 重新部署。

RuleGo 方式：编写 JSON

同样的智能体，RuleGo 只需一段 JSON 配置：

{
  "ruleChain": {"id": "weather-agent", "name": "天气助手"},
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [{
      "id": "node_agent",
      "type": "ai/agent",
      "name": "天气助手",
      "configuration": {
        "url": "https://ai.gitee.com/v1",
        "key": "${global.api_key}",
        "model": "GLM-5",
        "systemPrompt": "你是一个天气助手，可以查询天气信息。",
        "tools": [
          {"type": "builtin", "name": "bash", "config": {"workDir": "/data/workspace"}}
        ]
      }
    }]
  }
}

修改配置后实时生效，无需重启服务。 通过 API 或可视化编辑器更新 JSON，智能体立即使用新配置。

对比总结

维度	Eino（Go 代码）	RuleGo（JSON 声明式）
定义方式	编写 Go 代码	编写 JSON 配置
修改生效	改代码 → 编译 → 部署	修改 JSON → 实时生效
开发门槛	需要 Go 开发能力	理解 JSON 即可
可视化编辑	需要 Eino DevOps 工具	原生支持规则链可视化编辑器
会话管理	需自行实现	内置 SessionAspect，配置即用
切面机制	5 种回调（OnStart/OnEnd 等）	10 种切面接口，AOP 完整体系
工具生态	需 Go 实现 tool.BaseTool 接口	内置 8 种工具 + MCP 协议自动发现
多智能体编排	代码编排图/链	规则链声明式编排，子智能体即工具
模型切换	构建时绑定，不可变	运行时动态切换，会话级模型选择
与业务集成	需额外开发	原生规则引擎，与业务逻辑无缝集成

简单来说：Eino 是给 Go 开发者用的 LLM 编程框架，RuleGo 是给所有人用的智能体运行时。

快速开始

1. 启动服务

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. 创建 RuleGo 配置
    ruleConfig := rulego.NewConfig(rulego.WithDefaultPool())

    // 2. 注入全局变量（供 ${global.xxx} 引用）
    ruleConfig.Properties.PutValue("root_dir", "/data")
    ruleConfig.Properties.PutValue("api_key", "sk-xxx")

    // 3. 创建规则引擎池
    pool := rulego.NewRuleEnginePool(ruleConfig)

    // 4. 初始化会话管理 + 注册切面
    sessionMgr := agentsession.NewManager(agentsession.NewMemoryStorage(), nil)
    agentaspect.RegisterAspect("session", agentsession.NewBuiltinSessionAspect(sessionMgr))

    // 5. 加载智能体 JSON（支持从文件、数据库、API 加载）
    pool.Load(ruleConfig, "weather-agent", agentJSON)

    // 6. 执行
    msg := rulego.NewMsg("USER_INPUT", "北京天气怎么样？", rulego.TEXT, nil)
    pool.OnMsg("weather-agent", msg)
}

2. 定义智能体（纯 JSON）

{
  "ruleChain": {
    "id": "weather-agent",
    "name": "天气助手",
    "additionalInfo": {
      "description": "查询天气信息的智能助手"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [
      {
        "id": "node_agent",
        "type": "ai/agent",
        "name": "天气助手",
        "configuration": {
          "url": "https://ai.gitee.com/v1",
          "key": "${global.api_key}",
          "model": "GLM-5",
          "systemPrompt": "你是一个天气助手。使用 bash 工具执行 curl 命令查询天气 API。",
          "params": {"temperature": 0.7},
          "tools": [
            {"type": "builtin", "name": "bash", "config": {"workDir": "/data/workspace"}}
          ]
        }
      }
    ]
  }
}

3. 实时更新

智能体运行后，随时可以通过 API 更新配置，无需重启：

# 更新智能体配置（实时生效）
curl -X PUT http://localhost:8080/api/v1/rules/weather-agent \
  -H "Content-Type: application/json" \
  -d '{"ruleChain":{...新的JSON配置...}'

也可以通过可视化编辑器拖拽修改：

# 打开可视化编辑器
# https://editor.rulego.cc

典型场景：构建编程助手

下面展示如何用 JSON 构建一个类似 Claude Code 的编程助手智能体。

第一步：准备工作区

/data/workspace/
  IDENTITY.md      → "你是一个编程助手，擅长 Go 和 Python"
  AGENTS.md        → 代码风格规范、提交规范
  SOUL.md          → 简洁、安全、可测试
  skills/
    code-review/
      SKILL.md     → 代码审查技能定义
    test-gen/
      SKILL.md     → 测试生成技能定义

第二步：定义智能体 JSON

{
  "ruleChain": {
    "id": "coding-agent",
    "name": "编程助手",
    "additionalInfo": {
      "description": "具有文件读写和命令执行能力的编程智能体"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [{
      "id": "node_agent",
      "type": "ai/agent",
      "name": "编程助手",
      "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')}\n当前时间：${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"]
            }
          }
        ]
      }
    }]
  }
}

第三步：按需扩展

加一个子智能体（代码审查）——只需在 tools 数组中加一项：

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

换一个更强的模型——修改 model 字段，实时生效：

"model": "deepseek-reasoner"

加 MCP 工具——自动从 MCP Server 发现工具：

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

整个过程不需要写一行 Go 代码，不需要编译，不需要重启。

工作区系统

每个智能体可以拥有独立的工作区目录，通过 Markdown 文件定义行为和记忆：

workspace/
  IDENTITY.md      智能体身份、角色、能力描述
  AGENTS.md        行为规则、协作规则、任务路由
  SOUL.md          核心价值观、行为原则
  TOOLS.md         工具使用指南和备注
  USER.md          用户画像和偏好
  MEMORY.md        长期记忆（手动维护的重要信息）
  HEARTBEAT.md     心跳任务队列（智能体主动检查和执行）
  BOOTSTRAP.md     首次运行引导（执行后自动删除）
  memory/          每日记忆日志（YYYY-MM-DD.md）
  skills/          智能体私有技能
  rules/           自定义规则链

系统提示词通过 ${include()} 动态加载这些文件，智能体可以使用 write 和 edit 工具修改它们，实现自我进化。

多智能体编排

子智能体调用

在 tools 中添加 agent 类型工具，主智能体即可调用子智能体：

{
  "tools": [
    {"type": "agent", "targetId": "code-reviewer", "name": "code_review", "description": "代码审查"},
    {"type": "agent", "targetId": "test-generator", "name": "generate_tests", "description": "生成测试"}
  ]
}

LLM 根据工具描述自动决定何时调用哪个子智能体，子智能体的输出作为工具结果返回给主智能体继续推理。

管道模式

智能体节点与 JS 过滤器、REST API 调用等节点组合，构建确定性路由：

用户输入 → [ai/agent 意图分类] → [jsFilter 路由] → True: [restApiCall 执行] → [end]
                                             → False: [end 对话]

自定义切面

切面是可插拔的中间件，在智能体执行的不同阶段注入自定义逻辑。应用层用 Go 代码实现切面接口，注册后自动生效。

命令拦截（Around 切面）

拦截 /help、/model 等命令，不消耗 Token：

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

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

会话管理（内置切面）

框架内置 SessionAspect，注册后自动管理对话历史：

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

更多切面示例参见 切面框架。

技能系统

技能（Skill）以 Markdown 文件定义，智能体通过 skill 工具按名称调用：

---
name: code-review
description: 审查代码质量并给出改进建议
---

# Code Review

审查指定代码，关注：安全性、性能、可读性。

## 步骤
1. 使用 read 工具读取代码文件
2. 分析代码结构和潜在问题
3. 输出审查报告

技能支持两级目录：

• 全局技能（globalDirs）：所有智能体共享
• 本地技能（localDirs）：特定智能体专属

智能体也可以通过 write 工具在 skills/ 目录下创建新技能，实现自主学习。

相关文档

• 概述 — 框架定位与核心概念
• 架构设计 — 分层架构详解
• 智能体节点 — ReAct 节点的概念与高级特性
• 智能体组件 — ai/agent 组件的完整配置参考
• 工具系统 — 工具配置与扩展
• 切面框架 — 切面接口与自定义开发
• 会话管理 — 会话配置与存储扩展