本教程介绍如何在 RuleGo-Editor 中通过可视化方式创建一个 AI 智能体，配置大模型、工具，并通过对话测试和 OpenAI 兼容 API 调用智能体。

前提条件

1. RuleGo-Server 需使用 with_ai 构建标签编译，以包含 AI 相关组件（ai/agent 节点、LLM 工具等）。从 Github Releases (opens new window) 下载的预编译包已包含。如从源码构建：

   go build -tags "with_ai" -o server ./cmd/server/
   

   详见 安装与部署。

2. 已在 config.conf 中配置 LLM 连接信息：

   [global]
   llm_url = https://api.openai.com/v1
   llm_api_key = sk-xxx
   llm_model = gpt-4o
   

   支持所有兼容 OpenAI API 的大模型服务（DeepSeek、通义千问、智谱、Ollama 等）。也可以在智能体节点中单独配置，不使用全局变量。

3. 已启动 RuleGo-Server 并可以访问编辑器 http://localhost:9090/editor/

第一步：创建规则链

打开编辑器，点击工具栏的【新建】按钮创建一个新的规则链。规则链即智能体——每个规则链都可以作为一个独立的智能体使用。

创建后，在规则链信息中设置名称和描述。建议填写清晰的描述，方便后续作为子智能体被引用时自动生成工具说明。

第二步：添加智能体节点

从左侧组件面板的 AI Agent 分类中，将 智能体（ai/agent） 组件拖动到画布上。

ai/agent 节点是智能体的核心，负责 LLM 推理和工具调用循环。完整的组件配置参考参见 智能体组件。

第三步：配置大模型

双击智能体节点打开属性编辑面板，配置 LLM 连接信息。

方式一：选择预设供应商

从下拉列表中选择 LLM 供应商，系统会自动填充 API 地址和可用模型列表，只需填入 API 密钥即可。

方式二：自定义供应商

如果你的 LLM 服务不在预设列表中，切换到"自定义"模式，手动填写 API 地址、密钥和模型名称。支持所有兼容 OpenAI API 协议的服务（Ollama、vLLM、LocalAI 等）。

也可以使用全局变量引用 config.conf 中的配置：

API 地址：${global.llm_url}
API 密钥：${global.llm_api_key}
模型：${global.llm_model}

大模型参数（temperature、topP、maxTokens 等）可在"高级配置"中调整。

第四步：配置工具（可选）

工具是智能体可调用的能力单元。在智能体节点的属性面板中，找到"工具"配置区域，为智能体添加工具。

内置工具

框架提供 bash（命令执行）、read（文件读取）、write（文件写入）、edit（文件编辑）、skill（技能）等内置工具，勾选需要的工具并配置工作目录即可。

内置工具的详细说明参见 工具系统。

子智能体或子规则链

将其他智能体或规则链作为工具引用，实现多智能体协作。选择"agent"类型工具并指定目标规则链 ID，框架会自动填充工具名称和描述。

更多智能体编排案例参见 编排案例。

第五步：配置结束节点和连线

从组件面板拖入一个 结束节点（end），然后从智能体节点拖拽连线到结束节点。

• Success 连接：智能体执行成功时流转到结束节点
• Stream 连接：流式输出时每个 chunk 流转到结束节点（用于实时对话）
• Failure 连接：执行失败时流转（可连接到错误处理节点或直接结束）

配置完成后，点击工具栏的【保存】按钮保存并部署规则链。

第六步：测试智能体

保存规则链后，编辑器底部会出现 Agent 对话 界面（规则链分类为 AI Agent 时自动显示）。在对话框中输入消息，即可与智能体进行对话测试。

对话界面支持：

• SSE 流式输出，实时显示智能体的回复
• 显示推理过程和工具调用详情
• 每个工具有独立的进度指示和执行结果

也可以通过工具栏的【运行】按钮，以 REST API 方式执行规则链进行测试。

第七步：通过 API 调用智能体

智能体部署后，会自动获得 OpenAI 兼容的 API 端点，可以被任何兼容 OpenAI 协议的客户端或 SDK 调用。

端点地址

POST /api/v1/rules/{规则链ID}/v1/chat/completions

请求示例

同步调用：

curl -X POST http://localhost:9090/api/v1/rules/my-agent/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {apiKey}" \
  -d '{
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ]
  }'

流式调用（SSE）：

curl -X POST http://localhost:9090/api/v1/rules/my-agent/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {apiKey}" \
  -d '{
    "stream": true,
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ]
  }'

多轮对话：

curl -X POST http://localhost:9090/api/v1/rules/my-agent/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {apiKey}" \
  -d '{
    "stream": true,
    "messages": [
      {"role": "user", "content": "帮我查询当前的天气"},
      {"role": "assistant", "content": "好的，我来帮你查询..."},
      {"role": "user", "content": "明天呢？"}
    ]
  }'

使用 OpenAI SDK 调用

由于端点完全兼容 OpenAI 协议，可以直接使用官方 SDK：

Python：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:9090/api/v1/rules/my-agent/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="agent",
    messages=[
        {"role": "user", "content": "你好"}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Go：

import (
    "github.com/sashabaranov/go-openai"
)

config := openai.DefaultConfig("your-api-key")
config.BaseURL = "http://localhost:9090/api/v1/rules/my-agent/v1"
client := openai.NewClientWithConfig(config)

resp, _ := client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
    Model: "agent",
    Messages: []openai.ChatCompletionMessage{
        {Role: "user", Content: "你好"},
    },
})

model 字段在调用自定义智能体时可以为任意值，实际使用的模型由智能体节点内部配置决定。

接入 AI 编程工具

由于兼容 OpenAI 协议，智能体可以被 Claude Code、Cursor、Trae 等支持自定义 API 端点的 AI 编程工具直接调用。在工具的 API 配置中填入：

• API Base URL：http://localhost:9090/api/v1/rules/{规则链ID}/v1
• API Key：你的 RuleGo-Server API Key

更多 MCP 协议接入方式参见 MCP 服务。

完整配置参考

以下是一个带文件操作和命令执行能力的智能体规则链 JSON：

{
  "ruleChain": {
    "id": "my-agent",
    "name": "编程助手",
    "additionalInfo": {
      "description": "一个具有文件操作和命令执行能力的编程助手"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [
      {
        "id": "node_agent",
        "type": "ai/agent",
        "name": "智能体",
        "configuration": {
          "url": "${global.llm_url}",
          "key": "${global.llm_api_key}",
          "model": "${global.llm_model}",
          "maxStep": 25,
          "systemPrompt": "你是一个编程助手，可以读写文件和执行命令来帮助用户。",
          "tools": [
            {"type": "builtin", "name": "bash", "config": {"workDir": "/data/workspace", "timeout": 60000}},
            {"type": "builtin", "name": "read", "config": {"workDir": "/data/workspace"}},
            {"type": "builtin", "name": "write", "config": {"workDir": "/data/workspace"}},
            {"type": "builtin", "name": "edit", "config": {"workDir": "/data/workspace"}}
          ]
        }
      },
      {
        "id": "node_end",
        "type": "end",
        "name": "结束"
      }
    ],
    "connections": [
      {"fromId": "node_agent", "toId": "node_end", "type": "Success"},
      {"fromId": "node_agent", "toId": "node_end", "type": "Stream"},
      {"fromId": "node_agent", "toId": "node_end", "type": "Failure"}
    ]
  }
}

相关文档

• 智能体框架概述 — 框架核心概念和架构设计
• 智能体组件 — ai/agent 节点的完整配置参考
• 工具系统 — 内置工具、MCP 工具、子智能体工具
• 编排案例 — 智能体与规则链节点组合编排案例
• AI 功能 — RuleGo-Server 内置 AI Agent 和 Skill 管理
• AI 助手使用教程 — 通过对话方式创建和修改规则链
• REST API 参考 — 完整的 API 接口文档