Blades

这是什么？适合谁？

Blades 是一个基于 Go 语言的多模态 AI Agent 框架，由 go-kratos 团队开发。它提供了 Agent 开发的完整基础设施，包括多模态处理、工具集成、会话管理和部署支持。框架架构清晰，含中文 README 和丰富的 examples 目录，适合作为 Workflow 模式参考。

适合人群：Go 后端开发者、需要构建 AI Agent 应用的团队、希望学习 Agent 框架设计的工程师。 使用前提：Go 1.22+，熟悉 Go 语言基础，了解 AI Agent 的基本概念。

准备工作

所需工具与账号

工具	用途	定价
Go 1.22+	编程语言	免费
Blades CLI	项目脚手架	免费开源
LLM API Key	AI 能力（OpenAI/Anthropic/DeepSeek）	按量付费
Docker（可选）	容器化部署	免费

时间预算

• 环境搭建：2 小时
• 学习框架核心概念：4 小时
• 第一个 Agent 开发：1 天
• 集成到现有应用：1 天

前置知识

• Go 语言基础（goroutine、channel、interface）
• 了解 LLM API 调用（OpenAI/Anthropic SDK）
• 熟悉 Git 和命令行操作

替代方案

工具	适用场景	差异
LangChain Go	需要丰富生态	LangChain 生态更成熟，但 Go 版本功能有限
Eino（字节跳动）	国内场景	中文生态更好，社区更活跃
自建 Agent	特殊需求	灵活性最高，但开发成本大

5 步核心流程

第 1 步：环境准备与安装

确保 Go 1.22+ 已安装：

go version  # 确认版本 ≥ 1.22

克隆 Blades 仓库：

git clone https://github.com/go-kratos/blades
cd blades

安装依赖：

go mod download

设置 LLM API Key：

export OPENAI_API_KEY="your-key"
# 或使用 Anthropic
export ANTHROPIC_API_KEY="your-key"

预期产出：可运行的 Blades 开发环境。

第 2 步：创建 Agent 项目

使用 Blades 的 example 作为模板：

cp -r examples/simple-agent my-agent
cd my-agent

项目结构：

my-agent/
├── main.go          # 入口文件
├── agent/           # Agent 定义
├── tools/           # 自定义工具
├── prompts/         # Prompt 模板
└── config.yaml      # 配置文件

预期产出：标准化的 Agent 项目骨架。

第 3 步：定义 Agent 能力

编辑 agent/agent.go，配置 Agent 的核心能力：

package agent

import "github.com/go-kratos/blades/agent"

func NewMyAgent() *agent.Agent {
    return agent.New(
        agent.WithName("my-agent"),
        agent.WithModel("gpt-4o"),
        agent.WithTools(
            tools.NewWebSearch(),
            tools.NewCodeInterpreter(),
        ),
        agent.WithSystemPrompt("你是一个专业的 Go 开发助手..."),
    )
}

支持的能力类型：

• 文本处理：对话、分析、总结
• 多模态：图像识别、文档分析
• 工具调用：Web 搜索、代码执行、API 调用
• 会话管理：多轮对话、上下文记忆

预期产出：功能完整的 Agent 定义。

第 4 步：部署与测试

本地运行 Agent：

go run main.go

测试 Agent 功能：

curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "帮我分析这个 Go 项目的代码结构"}'

预期产出：本地运行的 Agent 服务，通过 API 测试验证。

第 5 步：集成到应用

将 Agent 集成到现有 Go 应用中：

import "github.com/go-kratos/blades/agent"

// 在现有服务中嵌入 Agent
func main() {
    myAgent := agent.NewMyAgent()
    
    http.HandleFunc("/api/agent", func(w http.ResponseWriter, r *http.Request) {
        resp := myAgent.Chat(r.Context(), r.FormValue("message"))
        json.NewEncoder(w).Encode(resp)
    })
    
    http.ListenAndServe(":8080", nil)
}

预期产出：Agent 集成到现有应用，可通过 API 调用。

常见踩坑（5 条）

踩坑 1：Go 版本不兼容

• 现象：编译报错 undefined: slices.Sort
• 原因：Blades 需要 Go 1.22+ 的泛型和标准库特性
• 解决：升级 Go 到 1.22+：go install golang.org/dl/go1.22@latest

踩坑 2：国内网络无法下载依赖

• 现象：go mod download 超时
• 原因：Go 模块代理被墙
• 解决：设置国内代理：export GOPROXY=https://goproxy.cn,direct

踩坑 3：LLM API 调用超时

• 现象：Agent 响应超时
• 原因：默认超时时间不足以完成复杂任务
• 解决：在 Agent 配置中增加超时时间：agent.WithTimeout(120 * time.Second)

踩坑 4：工具调用结果解析失败

• 现象：Agent 调用了工具但无法解析返回结果
• 原因：工具返回格式与 Agent 期望不一致
• 解决：确保自定义工具返回标准的 JSON 格式，包含 status 和 data 字段

踩坑 5：并发 Agent 实例内存泄漏

• 现象：长时间运行后内存持续增长
• 原因：Agent 会话上下文未及时清理
• 解决：配置会话 TTL：agent.WithSessionTTL(30 * time.Minute)，定期清理过期会话

FAQ（5 个常见问题）

Q1：Blades 与 LangChain Go 有什么区别？ A：Blades 更轻量，专注于 Agent 框架本身，代码结构清晰。LangChain Go 生态更丰富，但 Go 版本功能不如 Python 版本完整。简单项目选 Blades，复杂项目选 LangChain Python。

Q2：支持哪些 LLM 模型？ A：支持所有兼容 OpenAI API 格式的模型，包括 OpenAI GPT 系列、Anthropic Claude 系列、DeepSeek、以及本地部署的 Ollama 模型。

Q3：可以用于生产环境吗？ A：Blades 在 go-kratos 生态中已用于生产，但建议在充分测试后上线。关注错误处理、重试机制和监控。

Q4：如何扩展自定义工具？ A：实现 tools.Tool 接口即可。参考 examples/custom-tool 目录中的示例。

Q5：支持流式响应吗？ A：支持。使用 agent.WithStreaming(true) 启用流式输出，前端可通过 SSE 接收实时响应。

小技巧（5 条）

1. 使用配置管理：将 Agent 配置（模型、温度、Prompt）写入 config.yaml，便于不同环境切换
2. 监控 Agent 调用：集成 Prometheus 指标，跟踪调用次数、延迟和错误率
3. 缓存常用响应：对高频问题使用缓存，减少 API 调用成本
4. 设置速率限制：使用令牌桶算法限制 API 调用频率，避免超额
5. 编写集成测试：为 Agent 编写集成测试，确保工具调用和响应格式正确

进阶学习建议

掌握 Blades 后，你可以：

• 阅读 go-kratos 源码，学习框架设计模式
• 开发自定义 Agent 类型（RAG Agent、Multi-Agent 等）
• 将 Blades 与消息队列（Kafka/RabbitMQ）集成，构建异步 Agent 系统
• 学习 Agent 编排模式，实现多 Agent 协作

参考链接

• Blades GitHub 仓库
• go-kratos 官方文档

---

本文基于公开资料于 2026-08-14 整理。独立实测未进行，框架 API 可能随版本更新而变化，请以官方文档为准。