Blades

Blades 是一个面向 Go 语言的多模态 AI Agent 框架，支持自定义模型、工具、记忆、中间件等。它适用于多轮对话、思维链推理以及结构化输出等多种场景。

名称由来：游戏《战神》以希腊神话为背景，讲述了克拉托斯从凡人蜕变为战神并展开弑神之旅的冒险故事。而“双刀”正是克拉托斯标志性的武器。

架构设计

Blades 充分利用 Go 语言的特点，提供了一套灵活高效的 AI Agent 解决方案。其核心在于通过统一的接口和可插拔组件实现高度解耦与扩展性。整体架构如下：

• Go 风格：完全遵循 Go 的设计理念构建，代码风格和使用体验对 Go 开发者来说十分熟悉。
• 简单易用：通过简洁的代码声明即可定义 AI Agent，快速满足需求，使复杂逻辑清晰易懂、易于管理和维护。
• 中间件生态：借鉴 Kratos 的中间件设计理念，可观测性和护栏等功能可以轻松集成到 AI Agent 中。
• 高度可扩展：通过统一的接口和可插拔组件实现高度解耦与扩展性，便于集成不同的 LLM 模型和外部工具。

核心概念

Blades 框架通过一系列精心设计的核心组件实现了强大的功能与灵活性。这些组件协同工作，共同构建 Agent 的智能行为：

• Agent：执行任务的核心单元，能够调用模型和工具。
• Prompt：用于与 LLM 对话的模板化文本，支持动态变量替换和复杂上下文构建。
• Chain：连接多个 Agent 或其他 Chain，形成复杂的流程。
• ModelProvider：可插拔的 LLM 接口，方便切换和集成不同的语言模型服务（如 OpenAI 等）。
• Tool：Agent 可使用的外部能力，例如调用 API、查询数据库、访问文件系统等。
• Memory：为 Agent 提供短期或长期记忆能力，支持带上下文的连续对话。
• Middleware：类似于 Web 框架中的中间件，可对 Agent 进行横切控制。

Agent

Agent 是 Blades 框架中最核心的接口，定义了所有可执行组件的基本行为。它的设计旨在提供统一的执行范式。通过 Run 方法，框架内的各类功能模块实现了 解耦、标准化和高可组合性。Agent、Chain 和 ModelProvider 等组件都实现了该接口，从而统一了它们的执行逻辑，使不同组件能够像乐高积木一样灵活组合，构建复杂的 AI Agent。

// Agent 表示一个能够处理调用并生成消息序列的自主代理。
type Agent interface {
    Name() string
    Description() string
    Run(context.Context, *Invocation) Generator[*Message, error]
}

ModelProvider

ModelProvider 是 Blades 框架中用于与底层大语言模型（LLM）交互的核心抽象层。其设计目标是通过统一的接口实现 解耦和扩展性，将框架的核心逻辑与具体模型的实现细节（如 OpenAI、DeepSeek、Gemini 等）分离。它充当适配器的角色，负责将框架内部的标准化请求转换为模型原生 API 所需的格式，并将模型的响应转换回框架的标准格式，从而使开发者能够轻松切换和集成不同的 LLM。

type ModelProvider interface {
    // Generate 执行一次完整的生成请求，并一次性返回结果。适用于不需要实时反馈的场景。
    Generate(context.Context, *ModelRequest, ...ModelOption) (*ModelResponse, error)
    // NewStreaming 启动流式请求。该方法会立即返回一个 Generator 对象，允许调用者逐步接收模型生成的内容。适用于构建具有打字机效果的实时对话应用。
    NewStreaming(context.Context, *ModelRequest, ...ModelOption) (Generator[*ModelResponse])
}

Agent

Agent 是 Blades 框架中的核心协调者。作为顶层的 Agent，它整合并编排 ModelProvider、Tool、Memory 和 Middleware 等组件，以理解用户意图并执行复杂任务。其设计允许通过灵活的 Option 函数进行配置，从而驱动智能应用的行为与能力，履行任务编排、上下文管理及指令遵循等核心职责。

Flow

flow 用于构建复杂的工作流和多步推理。其设计理念是编排多个 Agent 组件，实现数据和控制流的传递，其中一个 Agent 的输出可以作为下一个 Agent 的输入。这种机制使开发者能够灵活地组合组件，构建高度定制化的 AI 流程，实现多步推理和复杂的数据处理。它是实现 Agent 复杂决策过程的关键。

Tool

Tool 是扩展 AI Agent 能力的关键组件，代表 Agent 可以调用的外部功能或服务。其设计旨在赋予 Agent 与现实世界交互的能力，执行特定操作或获取外部信息。通过清晰的 InputSchema，它引导 LLM 生成正确的调用参数，并通过内部的 Handle 函数执行实际逻辑，从而将各种外部 API、数据库查询等封装成 Agent 能够理解和调用的形式。

内存

Memory 组件为 AI 代理赋予记忆能力，提供用于存储和检索对话消息的通用接口，确保代理在多次对话轮次中保持上下文连贯性。其设计支持按会话 ID 管理消息，并可配置消息数量限制，以在记忆广度与系统资源消耗之间取得平衡。该框架提供了 InMemory 实现，同时也鼓励开发者将其扩展到持久化存储或更复杂的记忆策略。

type Memory interface {
    AddMemory(context.Context, *Memory) error
    SaveSession(context.Context, blades.Session) error
    SearchMemory(context.Context, string) ([]*Memory, error)	
}

中间件

Middleware 是一种强大的机制，用于实现横切关注点（如日志记录、监控、身份验证、限流）。其设计允许在不修改 Runner 核心逻辑的情况下，将额外的行为注入到 Runner 的执行流程中。它以类似“洋葱模型”的函数链形式运作，提供高度灵活的流程控制和功能增强，从而实现非核心业务逻辑与核心功能之间的解耦。

💡 快速入门

使用示例（聊天代理）

以下是一个简单的聊天代理示例，展示了如何使用 OpenAI 的 ModelProvider 构建一个基本的对话应用：

package main

import (
    "context"
    "log"
    "os"

    "github.com/go-kratos/blades"
    "github.com/go-kratos/blades/contrib/openai"
)

func main() {
    // 使用环境变量配置 OpenAI API 密钥和基础 URL：
    model := openai.NewModel("gpt-5", openai.Config{
        APIKey: os.Getenv("OPENAI_API_KEY"),
    })
    agent := blades.NewAgent(
        "Blades Agent",
        blades.WithModel(model),
        blades.WithInstruction("你是一位乐于助人、能够提供详细准确信息的助手。"),
    )
    // 创建包含用户消息的 Prompt
    input := blades.UserMessage("法国的首都是哪里？")
    // 使用 Prompt 运行代理
    runner := blades.NewRunner(agent)
    output, err := runner.Run(context.Background(), input)
    if err != nil {
        log.Fatal(err)
    }
    // 打印代理的回答
    log.Println(output.Text())
}

技能

Agent 支持通过 WithSkills(...) 注入技能，技能可以从目录或 embed.FS 加载。关于技能包格式和元数据规则，请参阅 Agent Skill specification。

package main

import (
    "embed"

    "github.com/go-kratos/blades"
    "github.com/go-kratos/blades/skills"
)

//go:embed example-skill/*
var skillFS embed.FS

func createAgent(model blades.ModelProvider) (blades.Agent, error) {
    // 目录加载：
    skillsFromDir, err := skills.NewFromDir("./skills")
    if err != nil {
        return nil, err
    }
    // 嵌入加载：
    skillsFromEmbed, err := skills.NewFromEmbed(skillFS)
    if err != nil {
        return nil, err
    }
    allSkills := append(skillsFromDir, skillsFromEmbed...)
    return blades.NewAgent(
        "SkillsAgent",
        blades.WithModel(model),
        blades.WithSkills(allSkills...),
    )
}

更多示例请参考 examples 目录。

🤝 贡献与社区

该项目目前仍处于早期阶段，我们正在持续快速迭代。我们诚挚邀请所有 Go 开发者和 AI 爱好者访问我们的 GitHub 仓库，亲身体验 Blades 带来的开发乐趣。

欢迎为项目点亮 ⭐️ 星标，在 examples 目录中探索更多使用示例，或者直接开始构建你的第一个 Go LLM 应用！

我们期待您的任何反馈、建议和贡献，共同推动 Go AI 生态系统的繁荣发展。

📄 许可证

Blades 采用 MIT 许可证授权。有关详情，请参阅 LICENSE 文件。

Blades 快速上手指南

Blades 是一个专为 Go 语言设计的多模态 AI Agent 框架，支持自定义模型、工具、记忆和中间件。它采用地道的 Go 风格，通过统一的接口和可插拔组件，帮助开发者快速构建多轮对话、思维链推理及结构化输出的智能应用。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Go 版本：Go 1.21 或更高版本（推荐使用最新稳定版）
• 依赖管理：已安装并配置好 Go Modules
• API Key：若使用 OpenAI 等外部模型，需提前准备好对应的 API Key

安装步骤

使用 go get 命令安装 Blades 核心库及常用的 OpenAI 适配器：

go get github.com/go-kratos/blades
go get github.com/go-kratos/blades/contrib/openai

提示：如果下载速度较慢，可配置国内 Go 代理加速：

export GOPROXY=https://goproxy.cn,direct

基本使用

以下是一个最简单的聊天机器人示例，展示如何使用 OpenAI 模型创建一个基础的 AI Agent 并运行对话。

1. 编写代码

创建 main.go 文件，填入以下代码：

package main

import (
    "context"
    "log"
    "os"

    "github.com/go-kratos/blades"
    "github.com/go-kratos/blades/contrib/openai"
)

func main() {
    // 初始化 OpenAI 模型提供者
    // 请确保环境变量 OPENAI_API_KEY 已设置
    model := openai.NewModel("gpt-4o", openai.Config{
        APIKey: os.Getenv("OPENAI_API_KEY"),
    })

    // 创建 Agent
    agent := blades.NewAgent(
        "Blades Agent",
        blades.WithModel(model),
        blades.WithInstruction("You are a helpful assistant that provides detailed and accurate information."),
    )

    // 构造用户输入消息
    input := blades.UserMessage("What is the capital of France?")

    // 创建 Runner 并执行
    runner := blades.NewRunner(agent)
    output, err := runner.Run(context.Background(), input)
    if err != nil {
        log.Fatal(err)
    }

    // 输出结果
    log.Println(output.Text())
}

2. 配置环境变量

在终端中设置您的 OpenAI API Key：

export OPENAI_API_KEY="your-openai-api-key-here"

3. 运行程序

执行以下命令启动应用：

go run main.go

程序将调用 LLM 处理问题，并在控制台打印出类似 The capital of France is Paris. 的回答。

---

进阶提示：Blades 还支持通过 WithSkills(...) 注入技能（从目录或 embed.FS 加载），以及使用 Chain 编排复杂工作流。更多高级用法请参考项目 examples 目录。