Files

peakxy bc087ad54b docs: 在README中新增项目运行截图

2026-06-02 21:21:26 +08:00

18 KiB

Raw Blame History

AI Agent Scaffold Go

AI Agent Scaffold Go 是一个面向 Agent 应用开发的 Go 脚手架，围绕 Gin、Eino、Google ADK Go、GORM、MySQL、Redis 构建，重点提供清晰的 DDD 分层、配置驱动的 Agent 装配、多 Agent 工作流编排和 HTTP 运行时接口。仓库同时附带一个基于 Next.js 的 frontend/ 子项目，作为对接后端 API 的示例前端，这个场景是通过drawio组件搭建的，旨在通过多轮对话来画出理想中的流程图。

项目展示

项目讲解文档

地址：项目文档
内容：简历写法、项目亮点与难点解析等

核心能力

配置驱动 Agent：通过 configs/agent/*.yaml 声明模型 API、ChatModel、MCP 工具、skills、LLM Agent、workflow Agent 和 Runner。
Armory 装配链：按 Root -> AiAPI -> ChatModel -> Agent -> AgentWorkflow -> Runner 的顺序装配运行时对象。
多 Agent 工作流：支持 loop、parallel、sequential 三类 workflow Agent，串行工作流可通过 output-key 把上一步结果注入下一步指令。
HTTP 运行时接口：提供 Agent 列表、创建会话、同步聊天、SSE 流式聊天接口。
OpenAI-compatible 模型调用：基础设施层直接构造 Chat Completions 请求，支持普通响应和 stream: true。
MCP SSE 工具调用：装配阶段注册 SSE MCP 工具，运行时在模型触发 tool call 后执行 JSON-RPC tools/call，再把工具结果回灌给模型。
Skill 资源扫描：支持扫描 SKILL.md，把 skill 元数据转换为模型可见工具。
分层边界清晰：领域层依赖本地 ports，避免直接耦合 Gin、GORM、Redis、模型 provider 和 ADK 实现。

技术栈

领域	选型
后端语言	Go 1.25.6+
HTTP 框架	Gin
Agent 运行与插件	Google ADK Go
模型/工具抽象依赖	Eino 相关依赖已纳入模块；当前模型调用由本地 OpenAI-compatible adapter 完成
配置	YAML + dotenv + 环境变量占位符
模型协议	OpenAI-compatible Chat Completions
工具协议	MCP SSE；stdio/local 配置结构已存在
持久化适配器	GORM + MySQL，当前默认启动路径未强制启用
缓存适配器	go-redis，当前默认启动路径未强制启用
日志	zap + Gin logger
前端	Next.js 16 + React 19 + Tailwind CSS + react-drawio

项目结构

ai-agent-scaffold-go
├── cmd/server
│   └── main.go                         # 后端入口：加载 .env、读取配置、构建应用、启动 HTTP 服务
├── configs
│   ├── application.yaml                # 应用、端口、LLM 超时、Agent 配置路径、可选 DB/Redis 设置
│   └── agent
│       ├── only-one-agent.yaml         # 单 Agent 示例
│       ├── agent-draw-io.yaml          # draw.io 多 Agent 工作流示例
│       └── skills/                     # skill 资源，按 SKILL.md 扫描
├── deployments
│   ├── docker-compose.yml              # 本地 MySQL/Redis 参考服务
│   ├── mysql/my.cnf
│   └── redis/redis.conf
├── frontend                            # Next.js draw.io 示例前端
├── internal
│   ├── api
│   │   ├── dto                         # HTTP 请求/响应 DTO
│   │   └── response                    # code/info/data 统一响应封装
│   ├── app
│   │   ├── bootstrap                   # 应用装配：配置表加载、Armory、ChatService、Gin 路由
│   │   └── config                      # application.yaml 与 Agent YAML 加载/校验
│   ├── domain
│   │   ├── agent
│   │   │   ├── model                   # Agent 配置模型、聊天命令、Runner 接口
│   │   │   ├── ports                   # 模型、工具、Agent、Runner、Registry、SessionStore 端口
│   │   │   └── service
│   │   │       ├── armory              # Agent 装配领域服务与节点链
│   │   │       └── chat                # 会话解析与聊天运行时服务
│   │   └── shared/tree                 # 泛型策略树路由框架
│   ├── infrastructure
│   │   ├── adk                         # Agent/Runner/插件适配
│   │   ├── ai                          # OpenAI-compatible client、MCP SSE client、tool/skill 工厂
│   │   ├── cache                       # Redis client adapter
│   │   ├── logging                     # zap logger
│   │   └── persistence                 # MySQL/GORM adapter
│   └── trigger/http                    # Gin HTTP 入站路由
├── pkg/types                           # 应用错误码与 AppError
├── .env.example
├── go.mod
└── README.md

后端架构

flowchart LR
    Client["Client / frontend"] --> Gin["trigger/http<br/>Gin routes"]
    Gin --> ChatService["domain/agent/service/chat"]
    ChatService --> Registry["AgentRegistry<br/>in-memory by default"]
    ChatService --> SessionStore["SessionStore<br/>in-memory by default"]
    Registry --> Runner["model.Runner"]
    Runner --> Agent["ADK adapter Agent"]
    Agent --> Model["ports.ChatModel"]
    Model --> OpenAI["OpenAI-compatible<br/>chat/completions"]
    Agent --> ToolRouter["MCPToolRouter"]
    ToolRouter --> MCP["MCP SSE tools"]

    Config["configs/application.yaml<br/>configs/agent/*.yaml"] --> Bootstrap["internal/app/bootstrap"]
    Bootstrap --> Armory["domain/agent/service/armory"]
    Armory --> Registry

后端按端口与适配器组织：

internal/domain 定义核心模型、端口、Armory 装配和聊天服务。
internal/app/bootstrap 负责把配置、领域服务、基础设施 adapter 和 Gin 路由连起来。
internal/infrastructure 实现外部依赖适配，包括模型 client、MCP client、ADK Runner、Redis、MySQL 和日志。
internal/trigger/http 只处理 HTTP 入参、出参和路由注册。
pkg/types 提供跨层使用的错误码：0000 成功、0001 未知错误、0002 参数错误、0003 Agent 不存在。

启动流程

sequenceDiagram
    participant Main as cmd/server
    participant Config as app/config
    participant Bootstrap as app/bootstrap
    participant Armory as domain/armory
    participant HTTP as Gin

    Main->>Main: parse -env and -config flags
    Main->>Main: load dotenv file if present
    Main->>Config: LoadApplication(configs/application.yaml)
    Main->>Bootstrap: Build(context, appCfg, logger)
    Bootstrap->>Config: LoadAgentTablesFile(configured paths)
    Bootstrap->>Armory: AcceptArmoryAgents(tables)
    Armory->>Bootstrap: registered runnable Agents
    Bootstrap->>HTTP: create router and register /healthz + /api/v1
    Main->>HTTP: engine.Run()

入口文件是 cmd/server/main.go。默认行为：

-env 默认读取 .env，也可通过 APP_ENV_FILE 指定；传空字符串可跳过 dotenv。
-config 默认读取 configs/application.yaml，也可通过 APP_CONFIG 指定。
dotenv 中的变量会进入进程环境，Agent YAML 里的 ${VAR} 和 ${VAR:-default} 会在加载时展开。
configs/application.yaml 负责声明服务地址、LLM 请求超时、Agent 配置文件路径，以及当前可选的 MySQL/Redis 设置。
bootstrap.Build 会装配 Agent、创建 ChatService、注册 Gin 路由并返回可运行的 Engine。

Armory 装配流程

Armory 是 Agent 配置到运行时对象的装配链。每个 Agent table 都会使用新的 DynamicContext，按节点顺序构建和传递装配状态。

flowchart TD
    Root["RootNode"] --> Api["AiAPINode<br/>build ModelAPI"]
    Api --> ChatModel["ChatModelNode<br/>build MCP/skill tools<br/>build ChatModel"]
    ChatModel --> Agent["AgentNode<br/>build LLM Agents"]
    Agent --> Workflow["AgentWorkflowNode<br/>build loop/parallel/sequential Agents"]
    Workflow --> Runner["RunnerNode<br/>build Runner and register Agent"]

关键文件：

internal/domain/agent/service/armory/factory/factory.go：组合完整节点链。
internal/domain/agent/service/armory/context.go：保存 ModelAPI、ChatModel、已构建 Agent、当前 workflow 进度和临时值。
internal/domain/agent/service/armory/chat_model_node.go：构建 MCP 工具、skill 工具和 ChatModel。
internal/domain/agent/service/armory/workflow/*.go：按 loop、parallel、sequential 构建 workflow Agent。
internal/domain/agent/service/armory/runner_node.go：根据 runner.agent-name 找到入口 Agent，创建 Runner 并注册到 AgentRegistry。

Workflow 行为：

sequential：按配置顺序执行子 Agent，并用子 Agent 的 output-key 保存中间结果，后续 Agent 指令可用 {output_key} 引用。
loop：当前 adapter 中按 fan-out 方式执行配置的子 Agent；配置里保留 max-iterations 字段。
parallel：当前 adapter 中按 fan-out 方式聚合子 Agent 输出。

运行时对话流程

sequenceDiagram
    participant Client
    participant Handler as trigger/http
    participant Chat as chat.Service
    participant Registry as AgentRegistry
    participant Runner
    participant Agent
    participant Model as OpenAI-compatible model
    participant Tool as MCPToolRouter

    Client->>Handler: POST /api/v1/chat
    Handler->>Chat: HandleMessage(agentId,userId,sessionId,message)
    Chat->>Registry: Get(agentId)
    Chat->>Runner: Run(userId,sessionId,content)
    Runner->>Agent: run(content)
    Agent->>Model: chat/completions
    alt model requests tool calls
        Agent->>Tool: CallTool(name,args)
        Tool-->>Agent: tool result
        Agent->>Model: next chat/completions with tool result
    end
    Model-->>Agent: final content
    Agent-->>Runner: output
    Runner-->>Handler: []string
    Handler-->>Client: {code,info,data}

同步聊天走 Runner.Run，流式聊天走 Runner.Stream。LLM Agent 最多允许 4 轮 tool-call 循环，避免工具调用无限递归。

快速开始

环境要求

Go 1.25.6+
Node.js 18+ 和 npm，仅启动 frontend/ 时需要
Docker，可选，仅在本地启动 MySQL/Redis 参考服务时需要
一个 OpenAI-compatible Chat Completions 服务
如果启用示例里的百度搜索 MCP，还需要可访问的 MCP SSE endpoint

1. 安装依赖并编译

cd ai-agent-scaffold-go
go mod tidy
go build ./...

2. 准备环境变量

复制示例文件：

cp .env.example .env

至少替换以下变量为自己的真实值：

OPENAI_BASE_URL=https://api.example.com/
OPENAI_API_KEY=replace-with-your-key
BAIDU_SEARCH_MCP_BASE_URI=http://example.com/mcp/
BAIDU_SEARCH_MCP_SSE_ENDPOINT=sse?api_key=replace-with-your-key

configs/agent/*.yaml 会读取这些变量来构建模型和 MCP 工具。

3. 可选：启动本地 MySQL/Redis

当前默认后端启动路径使用内存态 Agent registry 和 session store；MySQL/Redis 适配器已经存在，但不是默认启动的硬依赖。需要本地服务时可以使用：

docker compose -f deployments/docker-compose.yml up -d

参考端口：

MySQL：127.0.0.1:13306
Redis：127.0.0.1:16379

4. 启动后端

go run ./cmd/server

也可以显式指定文件：

go run ./cmd/server -env .env -config configs/application.yaml

默认监听地址来自 configs/application.yaml：

:8091

健康检查：

curl http://localhost:8091/healthz

预期响应：

{"status":"ok"}

配置说明

应用配置

configs/application.yaml 控制应用启动参数：

app:
  name: ai-agent-scaffold-go
  env: local
server:
  addr: ":8091"
database:
  required: false
  dsn: "root:<password>@tcp(127.0.0.1:13306)/ai-agent-scaffold-go?charset=utf8mb4&parseTime=True&loc=Local"
redis:
  required: false
  addr: "127.0.0.1:16379"
  password: ""
  db: 0
llm:
  request-timeout: 5m
agent:
  config-paths:
    - configs/agent/only-one-agent.yaml
    - configs/agent/agent-draw-io.yaml

说明：

server.addr 是 Gin 监听地址。
llm.request-timeout 使用 Go time.ParseDuration 格式，例如 30s、5m、1h。
agent.config-paths 可配置多个 Agent YAML，启动时会合并所有 tables。
database 和 redis 设置目前主要对应基础设施 adapter；默认 bootstrap 没有强制打开它们。

Agent 配置

Agent 配置文件结构位于 configs/agent/*.yaml：

ai:
  agent:
    config:
      tables:
        testAgent03:
          app-name: testAgent03
          agent:
            agent-id: "100003"
            agent-name: "single agent"
            agent-desc: "single agent demo"
          module:
            ai-api:
              base-url: ${OPENAI_BASE_URL}
              api-key: ${OPENAI_API_KEY}
              completions-path: "v1/chat/completions"
              embeddings-path: "v1/embeddings"
            chat-model:
              model: "gpt-5.5"
              tool-mcp-list:
                - sse:
                    name: baidu-search
                    base-uri: ${BAIDU_SEARCH_MCP_BASE_URI}
                    sse-endpoint: ${BAIDU_SEARCH_MCP_SSE_ENDPOINT}
                    request-timeout: 500000
              tool-skills-list:
                - type: "resource"
                  path: "agent/skills"
            agents:
              - name: "onlyAgent"
                description: "study plan helper"
                instruction: |
                  Build a beginner-friendly study plan from the user's request.
            runner:
              agent-name: "onlyAgent"
              plugin-name-list:
                - "myTestPlugin"
                - "myLogPlugin"

启动时会校验：

app-name
agent.agent-id
module.ai-api.base-url
module.ai-api.api-key
module.chat-model.model
module.agents[].name
module.agents[].instruction
module.runner.agent-name
每个 MCP tool 必须且只能声明 local、sse、stdio 之一
workflow type 必须是 loop、parallel 或 sequential

默认值：

ai-api.completions-path 默认 v1/chat/completions
ai-api.embeddings-path 默认 v1/embeddings
tool-skills-list[].type 默认 directory
agent-workflows[].max-iterations 默认 3

HTTP API

非流式接口统一返回：

{
  "code": "0000",
  "info": "success",
  "data": {}
}

GET /healthz

健康检查。

curl http://localhost:8091/healthz

{"status":"ok"}

GET /api/v1/query_ai_agent_config_list

查询已经注册的 Agent。

curl http://localhost:8091/api/v1/query_ai_agent_config_list

响应示例：

{
  "code": "0000",
  "info": "success",
  "data": [
    {
      "agentId": "100003",
      "agentName": "single agent",
      "agentDesc": "single agent demo"
    }
  ]
}

POST /api/v1/create_session

创建或复用某个 userId + agentId 的会话。

curl -X POST http://localhost:8091/api/v1/create_session \
  -H 'Content-Type: application/json' \
  -d '{"agentId":"100003","userId":"u1001"}'

响应示例：

{
  "code": "0000",
  "info": "success",
  "data": {
    "sessionId": "testAgent03:u1001:1"
  }
}

同等 GET 形式：

curl 'http://localhost:8091/api/v1/create_session?agentId=100003&userId=u1001'

POST /api/v1/chat

同步聊天。sessionId 可为空；为空时服务会自动创建或复用会话。

curl -X POST http://localhost:8091/api/v1/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "100003",
    "userId": "u1001",
    "sessionId": "",
    "message": "帮我制定一个 Go Agent 学习计划"
  }'

响应示例：

{
  "code": "0000",
  "info": "success",
  "data": {
    "content": "..."
  }
}

POST /api/v1/chat_stream

流式聊天，响应类型为 text/event-stream。

curl -N -X POST http://localhost:8091/api/v1/chat_stream \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "100003",
    "userId": "u1001",
    "sessionId": "",
    "message": "继续细化第一周计划"
  }'

流式片段示例：

event: message
data: 第一周可以从...

event: message
data: 接下来...

如果执行出错，服务会发送：

event: error
data: <error message>

前端启动

frontend/ 是一个 Next.js draw.io 示例前端，默认调用 http://localhost:8091/api/v1；启动方式是 cd frontend && npm install && npm run dev，然后访问 http://localhost:3000。

如需改后端地址，设置：

NEXT_PUBLIC_API_BASE_URL=http://localhost:8091/api/v1

开发与验证

后端常用命令：

go test ./...
go build ./...

检查 Go 文件是否需要格式化：

test -z "$(gofmt -l .)"

格式化：

gofmt -w .

前端常用命令：

cd frontend
npm run lint
npm run build

联系作者

邮箱：2465549609@qq.com

18 KiB Raw Blame History Unescape Escape

AI Agent Scaffold Go

目录

项目展示

项目讲解文档

核心能力

技术栈

项目结构

后端架构

启动流程

Armory 装配流程

运行时对话流程

快速开始

环境要求

1. 安装依赖并编译

2. 准备环境变量

3. 可选：启动本地 MySQL/Redis

4. 启动后端

配置说明

应用配置

Agent 配置

HTTP API

GET /healthz

GET /api/v1/query_ai_agent_config_list

POST /api/v1/create_session

POST /api/v1/chat

POST /api/v1/chat_stream

前端启动

开发与验证

联系作者

18 KiB

Raw Blame History