GoLoom

AI Agent Scaffold — 一个基于 Go 的多 Agent LLM 编排框架。

GoLoom 提供开箱即用的 HTTP 服务，支持多 Agent 编排、SSE 流式对话、工具调用（Function Calling）以及 YAML 配置驱动的 Agent 定义，帮助你快速构建和部署 AI Agent 应用。

核心特性

• 多 Agent 编排 — 支持 4 种编排模式：LLM（单轮）、Sequential（顺序）、Parallel（并发）、Loop（循环）
• SSE 流式对话 — 基于 Server-Sent Events 的实时流式输出
• 工具调用 — OpenAI Function Calling 协议，支持自定义 Tool 扩展
• YAML 配置驱动 — 通过 YAML 文件定义 Agent 拓扑，支持环境变量展开
• OpenAI 兼容 — 适配 DeepSeek、通义千问等 OpenAI 兼容 API
• Next.js 前端 — 配套的 React + TypeScript + Tailwind CSS 聊天界面

技术栈

层级	技术
后端语言	Go 1.26
Web 框架	Gin
日志	Zap (structured logging)
前端框架	Next.js + React + TypeScript
样式	Tailwind CSS
LLM 协议	OpenAI Chat Completions API

项目结构

GoLoom/
├── backend/                        # Go 后端
│   ├── cmd/server/main.go          # 入口：.env → config → bootstrap → Gin
│   ├── internal/
│   │   ├── config/                 # YAML 配置加载 + ${VAR} 环境变量展开
│   │   ├── handler/                # Gin 路由、请求/响应处理、SSE
│   │   ├── service/                # ChatService、Agent 实现、Runner、Assembler
│   │   ├── model/                  # 核心接口（Agent、ChatModel、Tool、Runner）
│   │   └── llm/                    # OpenAI 兼容 HTTP 客户端
│   ├── pkg/types/                  # 错误码与 AppError 类型
│   ├── configs/                    # application.yaml + agent/*.yaml
│   └── .env.example                # 环境变量模板
├── frontend/                       # Next.js 前端
├── docs/                           # 详细文档（中文）
└── CLAUDE.md                       # Claude Code 开发指南

依赖方向： handler → service → model/llm（model 不依赖任何内部包）

快速开始

1. 环境准备

• Go 1.26+
• Node.js 18+（前端）
• 一个 OpenAI 兼容的 LLM API Key

2. 后端

cd backend

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 API Key

# 安装依赖
go mod tidy

# 运行
go run ./cmd/server

服务默认监听 http://localhost:8091。

3. 前端

cd frontend

npm install
npm run dev

前端默认运行在 http://localhost:3000。

API 接口

基础路径：/api/v1

方法	路径	说明
GET	/healthz	健康检查
GET	/api/v1/query_ai_agent_config_list	查询已注册 Agent 列表
POST	/api/v1/create_session	创建会话
POST	/api/v1/chat	同步对话
POST	/api/v1/chat_stream	SSE 流式对话

典型流程： 查询 Agent 列表 → 创建会话 → 使用 sessionId 进行对话。

示例

# 查询 Agent 列表
curl http://localhost:8091/api/v1/query_ai_agent_config_list

# 创建会话
curl -X POST http://localhost:8091/api/v1/create_session \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id"}'

# 同步对话
curl -X POST http://localhost:8091/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"session_id": "xxx", "content": "你好"}'

# 流式对话
curl -X POST http://localhost:8091/api/v1/chat_stream \
  -H "Content-Type: application/json" \
  -d '{"session_id": "xxx", "content": "你好"}'

Agent 配置

在 backend/configs/agent/ 目录下创建 YAML 文件定义 Agent：

id: my-agent
name: My Agent
description: 一个示例 Agent
type: llm
model_id: deepseek-chat
system_prompt: |
  你是一个 helpful assistant.
tools:
  - name: search
    description: 搜索工具
    parameters:
      query:
        type: string
        required: true
        description: 搜索关键词

支持 4 种 Agent 类型：

类型	说明
llm	单次 LLM 调用，支持工具调用循环（最多 4 轮）
sequential	顺序执行子 Agent，前一个的输出注入下一个的 {outputKey}
parallel	并发执行所有子 Agent，合并结果
loop	重复执行子 Agent，最多 maxIterations 次

配置支持环境变量展开：${VAR} 或 ${VAR:-default}。

测试

cd backend

# 运行所有测试
go test ./...

# 带 race 检测和覆盖率
go test -race -coverprofile=coverage.out ./...

# 查看覆盖率
go tool cover -html=coverage.out

# 运行指定测试
go test -run TestFuncName ./internal/service/...

# Lint
golangci-lint run --timeout=5m

文档

文档	内容
架构设计	整体架构与设计决策
API 参考	HTTP API 详细规格与 curl 示例
后端构建指南	完整的 Go 后端实现参考
前端构建指南	Next.js 前端实现参考
测试指南	测试规范与最佳实践
日志指南	Zap 日志级别与结构化字段规范
构建计划	6 阶段开发计划与进度追踪

设计理念

• 接口驱动 — 核心抽象（Agent、ChatModel、Tool、Runner）定义在 model 包，零外部依赖
• 配置即代码 — YAML 定义 Agent 拓扑，无需修改代码即可编排复杂工作流
• 依赖注入 — ChatService 通过接口注入 AgentRegistry 和 SessionStore，便于测试和扩展
• 渐进式复杂度 — 从单 Agent 到多 Agent 编排，按需组合

协议

MIT License