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