hexagon

README

Go 生态全能型 AI Agent 框架

---

📖 项目简介

Hexagon 取名自网络热词「六边形战士」，寓意均衡强大、无懈可击。

我们聚焦 易用性、性能、扩展性、任务编排、可观测性、安全性 六大核心维度，深耕技术打磨，致力于实现各能力模块的均衡卓越，为 Go 开发者打造企业级落地首选的 AI Agent 开发基座。

🚀 核心特性

• ⚡ 高性能 │ 原生 Go 驱动，极致并发，支持 100k+ 活跃 Agent
• 🧩 易用性 │ 声明式 API 设计，3 行代码极速构建基础原型
• 🛡️ 安全性 │ 企业级沙箱隔离，内置完备的权限管控与防护
• 🔧 扩展性 │ 插件化架构，支持高度自定义的组件无缝集成
• 🛠️ 编排力 │ 强大的图编排引擎，轻松驾驭复杂的多级任务链路
• 🔍 可观测 │ 深度集成 OpenTelemetry，实现全链路透明追踪

---

🌐 生态系统

Hexagon 是一个完整的 AI Agent 开发生态，由多个仓库组成：

仓库	说明	链接
hexagon	AI Agent 框架核心 (编排、RAG、Graph、Hooks)	github.com/everyday-items/hexagon
ai-core	AI 基础能力库 (LLM/Tool/Memory/Schema)	github.com/everyday-items/ai-core
toolkit	Go 通用工具库 (lang/crypto/net/cache/util)	github.com/everyday-items/toolkit
hexagon-ui	Dev UI 前端 (Vue 3 + TypeScript)	github.com/everyday-items/hexagon-ui

🧠 ai-core — AI 基础能力库

提供 LLM、Tool、Memory、Schema 等核心抽象，支持多种 LLM Provider：

import "github.com/everyday-items/ai-core/llm"
import "github.com/everyday-items/ai-core/llm/openai"
import "github.com/everyday-items/ai-core/tool"
import "github.com/everyday-items/ai-core/memory"

主要模块：

• llm/ - LLM Provider 接口 + 实现 (OpenAI, DeepSeek, Anthropic, Gemini, 通义, 豆包, Ollama)
• llm/router/ - 智能模型路由 (任务感知 + 模型能力档案)
• tool/ - 工具系统，支持函数式定义
• memory/ - 记忆系统，支持向量存储
• schema/ - JSON Schema 自动生成
• streamx/ - 流式响应处理
• template/ - Prompt 模板引擎

🛠️ toolkit — Go 通用工具库

生产级 Go 通用工具包，提供语言增强、加密、网络、缓存、协程池等基础能力：

import "github.com/everyday-items/toolkit/lang/conv"      // 类型转换
import "github.com/everyday-items/toolkit/lang/stringx"   // 字符串工具
import "github.com/everyday-items/toolkit/lang/syncx"     // 并发工具
import "github.com/everyday-items/toolkit/net/httpx"      // HTTP 客户端
import "github.com/everyday-items/toolkit/net/sse"        // SSE 客户端
import "github.com/everyday-items/toolkit/util/retry"     // 重试机制
import "github.com/everyday-items/toolkit/util/idgen"     // ID 生成
import "github.com/everyday-items/toolkit/util/poolx"     // 协程池
import "github.com/everyday-items/toolkit/cache/local"    // 本地缓存

主要模块：

• lang/ - 语言增强 (conv, stringx, slicex, mapx, timex, contextx, errorx, syncx)
• crypto/ - 加密 (aes, rsa, sign)
• net/ - 网络 (httpx, sse, ip)
• cache/ - 缓存 (local, redis, multi)
• util/ - 工具 (retry, rate, idgen, logger, validator, poolx 协程池)
• collection/ - 数据结构 (set, list, queue, stack)

🎨 hexagon-ui — Dev UI 前端

基于 Vue 3 + TypeScript 的开发调试界面：

cd hexagon-ui
npm install
npm run dev
# 访问 http://localhost:5173

功能特性：

• 实时事件流 (SSE 推送)
• 指标仪表板
• 事件详情查看
• LLM 流式输出展示

⚡ 快速开始

📦 安装

go get github.com/everyday-items/hexagon

⚙️ 环境配置

# OpenAI
export OPENAI_API_KEY=your-api-key

# 或 DeepSeek
export DEEPSEEK_API_KEY=your-api-key

🎯 3 行代码入门

package main

import (
    "context"
    "fmt"
    "github.com/everyday-items/hexagon"
)

func main() {
    response, _ := hexagon.Chat(context.Background(), "What is Go?")
    fmt.Println(response)
}

🔧 带工具的 Agent

package main

import (
    "context"
    "fmt"
    "github.com/everyday-items/hexagon"
)

func main() {
    // 定义计算器工具
    type CalcInput struct {
        A  float64 `json:"a" desc:"第一个数字" required:"true"`
        B  float64 `json:"b" desc:"第二个数字" required:"true"`
        Op string  `json:"op" desc:"运算符" required:"true" enum:"add,sub,mul,div"`
    }

    calculator := hexagon.NewTool("calculator", "执行数学计算",
        func(ctx context.Context, input CalcInput) (float64, error) {
            switch input.Op {
            case "add": return input.A + input.B, nil
            case "sub": return input.A - input.B, nil
            case "mul": return input.A * input.B, nil
            case "div": return input.A / input.B, nil
            }
            return 0, fmt.Errorf("unknown operator")
        },
    )

    // 创建带工具的 Agent
    agent := hexagon.QuickStart(
        hexagon.WithTools(calculator),
        hexagon.WithSystemPrompt("你是一个数学助手"),
    )

    output, _ := agent.Run(context.Background(), hexagon.Input{
        Query: "计算 123 * 456",
    })
    fmt.Println(output.Content)
}

🔍 RAG 检索增强

// 创建 RAG 引擎
engine := hexagon.NewRAGEngine(
    hexagon.WithRAGStore(hexagon.NewMemoryVectorStore()),
    hexagon.WithRAGEmbedder(hexagon.NewOpenAIEmbedder()),
)

// 索引文档
engine.Index(ctx, []hexagon.Document{
    {ID: "1", Content: "Go 支持并发编程"},
    {ID: "2", Content: "Go 有丰富的标准库"},
})

// 检索
docs, _ := engine.Retrieve(ctx, "Go 的特性", hexagon.WithTopK(2))

📊 图编排

import "github.com/everyday-items/hexagon/orchestration/graph"

// 构建工作流图
g, _ := graph.NewGraph[MyState]("workflow").
    AddNode("analyze", analyzeHandler).
    AddNode("process", processHandler).
    AddEdge(graph.START, "analyze").
    AddEdge("analyze", "process").
    AddEdge("process", graph.END).
    Build()

// 执行
result, _ := g.Run(ctx, initialState)

👥 多 Agent 团队

// 创建团队
team := hexagon.NewTeam("research-team",
    hexagon.WithAgents(researcher, writer, reviewer),
    hexagon.WithMode(hexagon.TeamModeSequential),
)

// 执行
output, _ := team.Run(ctx, hexagon.Input{Query: "写一篇技术文章"})

🚀 高级能力

🔀 智能模型路由 (Smart Router)

根据任务类型、复杂度自动选择最优模型：

import "github.com/everyday-items/ai-core/llm/router"

// 创建智能路由器
smartRouter := router.NewSmartRouter(baseRouter,
    router.WithAutoClassify(true),
)

// 带路由上下文的请求
routingCtx := router.NewRoutingContext(router.TaskTypeCoding, router.ComplexityMedium).
    WithPriority(router.PriorityQuality).
    RequireFunctions()

resp, decision, _ := smartRouter.CompleteWithRouting(ctx, req, routingCtx)
// decision 包含: 选择的模型、得分、原因、备选方案

特性：

• 任务感知路由 (coding/reasoning/creative/analysis 等)
• 质量/成本/延迟优先级策略
• 20+ 预定义模型能力档案
• 路由历史和统计分析

⚙️ 确定性业务流程 (Process Framework)

状态机驱动的业务流程框架：

import "github.com/everyday-items/hexagon/process"

// 定义订单处理流程
p, _ := process.NewProcess("order-processing").
    AddState("pending", process.AsInitial()).
    AddState("validated").
    AddState("processing").
    AddState("completed", process.AsFinal()).
    AddState("failed", process.AsFinal()).

    // 状态转换
    AddTransition("pending", "validate", "validated",
        process.WithGuard(func(ctx context.Context, data *process.ProcessData) bool {
            return data.Get("amount") != nil
        })).
    AddTransition("validated", "process", "processing").
    AddTransition("processing", "complete", "completed").
    AddTransition("processing", "fail", "failed").

    // 绑定 Agent 到状态
    OnStateEnter("validated", step.NewAgentStep("validator", validatorAgent)).
    Build()

// 执行流程
output, _ := p.Invoke(ctx, process.ProcessInput{
    Data: map[string]any{"order_id": "123", "amount": 100},
})

特性：

• 状态机驱动，确定性执行
• 支持守卫条件和转换动作
• 步骤类型：Action/Agent/Condition/Parallel/Sequence/Retry/Timeout
• 流程生命周期：Start/Pause/Resume/Cancel
• 完整实现 Runnable 六范式接口

📄 智能文档工作流 (ADW)

超越传统 RAG 的端到端文档自动化：

import "github.com/everyday-items/hexagon/adw"
import "github.com/everyday-items/hexagon/adw/extractor"
import "github.com/everyday-items/hexagon/adw/validator"

// 定义提取 Schema
schema := adw.NewExtractionSchema("invoice").
    AddStringField("invoice_number", "发票号码", true).
    AddDateField("date", "日期", "YYYY-MM-DD", true).
    AddMoneyField("amount", "金额", true).
    AddStringField("vendor", "供应商", false)

// 创建处理管道
pipeline := adw.NewPipeline("invoice-processing").
    AddStep(adw.NewDocumentTypeDetectorStep()).
    AddStep(extractor.NewLLMExtractionStep(llmProvider, schema)).
    AddStep(extractor.NewEntityExtractionStep(llmProvider)).
    AddStep(validator.NewSchemaValidationStep(schema)).
    AddStep(adw.NewConfidenceCalculatorStep()).
    Build()

// 处理文档
output, _ := pipeline.Process(ctx, adw.PipelineInput{
    Documents: documents,
    Schema:    schema,
})

// 访问结果
for _, doc := range output.Documents {
    fmt.Println("发票号:", doc.StructuredData["invoice_number"])
    fmt.Println("实体:", doc.Entities)
    fmt.Println("验证:", doc.IsValid())
}

特性：

• Document 扩展：结构化数据/表格/实体/关系/验证错误
• Schema 驱动的结构化提取
• LLM 提取器：实体/关系提取
• 完整验证：类型/格式/范围/枚举/正则
• 并发处理 + 钩子系统

🌐 A2A 协议 (Agent-to-Agent)

实现 Google A2A 协议，支持标准化的 Agent 间通信：

import "github.com/everyday-items/hexagon/a2a"

// 将 Hexagon Agent 暴露为 A2A 服务
server := a2a.ExposeAgent(myAgent, "http://localhost:8080")
server.Start(":8080")

// 连接远程 A2A Agent
client := a2a.NewClient("http://remote-agent.example.com")
card, _ := client.GetAgentCard(ctx)

// 发送消息
task, _ := client.SendMessage(ctx, &a2a.SendMessageRequest{
    Message: a2a.NewUserMessage("你好"),
})

// 流式交互
events, _ := client.SendMessageStream(ctx, req)
for event := range events {
    switch e := event.(type) {
    case *a2a.ArtifactEvent:
        fmt.Print(e.Artifact.GetTextContent())
    }
}

特性：

• 完整 A2A 协议实现 (AgentCard/Task/Message/Artifact)
• JSON-RPC 2.0 + SSE 流式响应
• 多种认证方式 (Bearer Token/API Key/Basic Auth/RBAC)
• Agent 发现服务 (Registry/Static/Remote)
• 推送通知支持
• 与 Hexagon Agent 无缝桥接

💡 设计理念

1. 渐进式复杂度 - 入门 3 行代码，进阶声明式配置，专家图编排
2. 约定优于配置 - 合理默认值，零配置可运行
3. 组合优于继承 - 小而专注的组件，灵活组合
4. 显式优于隐式 - 类型安全，编译时检查
5. 生产优先 - 内置可观测性，优雅降级

🏗️ 架构

📐 整体架构

🔗 生态系统依赖

📈 数据流

🤖 LLM 支持

Provider	状态
OpenAI (GPT-4, GPT-4o, o1, o3)	✅ 已支持
DeepSeek	✅ 已支持
Anthropic (Claude)	✅ 已支持
Google Gemini	✅ 已支持
通义千问 (Qwen)	✅ 已支持
豆包 (Ark)	✅ 已支持
Ollama (本地模型)	✅ 已支持

📁 项目结构

hexagon/
├── agent/              # Agent 核心 (ReAct/Role/Team/Handoff/State/Primitives)
├── a2a/                # A2A 协议 (Client/Server/Handler/Discovery)
├── core/               # 统一接口 (Component[I,O], Stream[T])
├── orchestration/      # 编排引擎
│   ├── graph/          # 图编排 (状态图/检查点/Barrier/分布式/可视化)
│   ├── flow/           # Flow 流程编排 (可配置超时)
│   ├── chain/          # 链式编排
│   ├── workflow/       # 工作流引擎
│   └── planner/        # 规划器
├── process/            # 确定性业务流程框架 (状态机驱动)
│   └── step/           # 步骤类型 (Action/Agent/Condition/Parallel)
├── adw/                # 智能文档工作流 (Agentic Document Workflows)
│   ├── extractor/      # 结构化提取器
│   └── validator/      # Schema 验证器
├── rag/                # RAG 系统
│   ├── loader/         # 文档加载 (Text/Markdown/CSV/XLSX/PPTX/DOCX/PDF/OCR)
│   ├── splitter/       # 文档分割 (Character/Recursive/Markdown/Sentence/Token/Code)
│   ├── retriever/      # 检索器 (Vector/Keyword/Hybrid/HyDE/Adaptive/ParentDoc)
│   ├── reranker/       # 重排序
│   └── synthesizer/    # 响应合成
├── memory/             # 多 Agent 记忆共享
├── artifact/           # 工件系统
├── mcp/                # MCP 协议支持
├── hooks/              # 钩子系统 (Run/Tool/LLM/Retriever)
├── observe/            # 可观测性 (Tracer/Metrics/OTel/DevUI)
├── security/           # 安全防护 (Guard/RBAC/Cost/Audit/Filter)
├── tool/               # 工具系统 (File/Python/Shell/Sandbox)
├── store/              # 存储
│   └── vector/         # 向量存储 (Qdrant/FAISS/PgVector/Redis/Milvus/Chroma/Pinecone/Weaviate)
├── plugin/             # 插件系统
├── config/             # 配置管理
├── evaluate/           # 评估系统
├── testing/            # 测试工具 (Mock/Record)
├── deploy/             # 部署配置 (Docker Compose/Helm Chart/CI)
├── examples/           # 示例代码
└── hexagon.go          # 入口 (v0.3.0-beta)

📚 文档

📄 核心文档

文档	说明
快速入门	5 分钟上手 Hexagon
架构设计	框架设计理念和架构
API 参考	完整 API 文档
稳定性说明	API 稳定性和版本策略
框架对比	与主流框架的对比分析

📖 使用指南

指南	说明
快速开始	从零开始构建第一个 Agent
Agent 开发	Agent 开发完整指南
Agent 进阶	高级 Agent 开发模式
RAG 系统	检索增强生成入门
RAG 集成	RAG 系统深度集成
图编排	复杂工作流编排
多 Agent	多 Agent 协作系统
插件开发	插件系统使用指南
可观测性	追踪、指标、日志集成
安全防护	安全最佳实践
性能优化	性能调优指南

💻 示例代码

示例	说明
examples/quickstart	快速入门示例
examples/react	ReAct Agent 示例
examples/rag	RAG 检索示例
examples/graph	图编排示例
examples/team	多 Agent 团队示例
examples/handoff	Agent 交接示例
examples/chatbot	聊天机器人示例
examples/code-review	代码审查示例
examples/data-analysis	数据分析示例
examples/qdrant	Qdrant 向量存储示例
examples/devui	Dev UI 示例

🖥️ Dev UI

内置开发调试界面，实时查看 Agent 执行过程。

import "github.com/everyday-items/hexagon/observe/devui"

// 创建 DevUI
ui := devui.New(
    devui.WithAddr(":8080"),
    devui.WithMaxEvents(1000),
)

// 启动服务
go ui.Start()

// 访问 http://localhost:8080

运行示例：

# 启动后端
go run examples/devui/main.go

# 启动前端 (hexagon-ui)
cd ../hexagon-ui
npm install
npm run dev
# 访问 http://localhost:5173

🚢 部署

Hexagon 提供三种部署方式，支持本地开发到生产环境的全场景覆盖：

方案	适用场景	命令
Docker Compose (完整模式)	快速体验、演示、单机部署	make up
Docker Compose (开发模式)	团队开发（复用 docker-dev-env）	make dev-up
Helm Chart	K8s 集群、生产环境	make helm-install

Docker 快速启动

cd deploy
cp .env.example .env
# 编辑 .env，填入 LLM API Key
make up

# 访问
# 主应用:  http://localhost:8000
# Dev UI:  http://localhost:8080

Kubernetes / Helm

cd deploy
make helm-install

# 使用外部基础设施
helm install hexagon helm/hexagon/ \
  -n hexagon --create-namespace \
  --set qdrant.enabled=false \
  --set external.qdrant.url=http://my-qdrant:6333

详见 部署指南。

🔨 开发

make build   # 构建
make test    # 测试
make lint    # 代码检查
make fmt     # 格式化

🤝 贡献

欢迎贡献！请阅读 CONTRIBUTING.md 了解如何参与。

📜 许可证

MIT License

MIT License

Copyright (c) 2026 everyday-items

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Documentation

Overview

Package hexagon 提供 Hexagon AI Agent 框架的顶层 API

Hexagon 是一个新一代 Go AI Agent 框架，设计目标是：

• 极简入门：3 行代码即可开始
• 类型安全：编译时检查，零运行时类型错误
• 高性能：原生并发，100k+ 并发 Agent
• 可观测：100% 覆盖率
• 生产就绪：优雅降级，运维友好

快速开始

最简单的使用方式（3 行代码）：

response, _ := hexagon.Chat(ctx, "What is Go?")
fmt.Println(response)

带工具的 Agent：

agent := hexagon.QuickStart(
    hexagon.WithTools(calculatorTool),
    hexagon.WithSystemPrompt("You are a math assistant."),
)
output, _ := agent.Run(ctx, hexagon.Input{Query: "What is 123 * 456?"})

Index

• Constants
• Variables
• func Chat(ctx context.Context, query string, opts ...QuickStartOption) (string, error)
• func ChatWithTools(ctx context.Context, query string, tools ...tool.Tool) (string, error)
• func NewChain[I, O any](name string) *chain.ChainBuilder[I, O]
• func NewGraph[S graph.State](name string) *graph.GraphBuilder[S]
• func NewTool[I, O any](name, description string, fn func(context.Context, I) (O, error)) *tool.FuncTool[I, O]
• func QuickStart(opts ...QuickStartOption) *agent.ReActAgent
• func SetDefaultProvider(p llm.Provider)
• type Agent
• type Chain
• type Component
• type CostController
• type Document
• type Embedder
• type Graph
• type Guard
• type Indexer
• type Input
• type Loader
• type MCPServerV2
• type MapState
• type Memory
• type MemoryItem
• type MemoryStore
• type Message
• type Metrics
• type Output
  • func Run(ctx context.Context, input Input, opts ...QuickStartOption) (Output, error)
• type QdrantConfig
• type QuickStartOption
  • func WithMemory(m memory.Memory) QuickStartOption
  • func WithProvider(p llm.Provider) QuickStartOption
  • func WithSystemPrompt(prompt string) QuickStartOption
  • func WithTools(tools ...tool.Tool) QuickStartOption
• type RAGEngine
• type Retriever
• type Role
• type Schema
• type Span
• type Splitter
• type State
• type StateManager
• type Stream
• type Team
• type Tool
• type Tracer
• type VectorStore

Constants

const (
	// Version is the current version of the Hexagon framework.
	// Format: MAJOR.MINOR.PATCH[-PRERELEASE]
	Version = "0.3.0-beta"

	// VersionMajor is the major version number.
	VersionMajor = 0

	// VersionMinor is the minor version number.
	VersionMinor = 3

	// VersionPatch is the patch version number.
	VersionPatch = 0

	// VersionPrerelease is the pre-release identifier (empty for stable releases).
	VersionPrerelease = "beta"
)

Version information for the Hexagon framework.

const (
	// START 起始节点
	START = graph.START
	// END 结束节点
	END = graph.END
)

图编排常量

const (
	TeamModeSequential    = agent.TeamModeSequential
	TeamModeHierarchical  = agent.TeamModeHierarchical
	TeamModeCollaborative = agent.TeamModeCollaborative
	TeamModeRoundRobin    = agent.TeamModeRoundRobin
)

团队模式常量

const (
	ChainModeAll   = guard.ChainModeAll
	ChainModeAny   = guard.ChainModeAny
	ChainModeFirst = guard.ChainModeFirst
)

守卫链模式

const (
	QdrantDistanceCosine = qdrant.DistanceCosine
	QdrantDistanceEuclid = qdrant.DistanceEuclid
	QdrantDistanceDot    = qdrant.DistanceDot
)

Qdrant 距离度量方式

Variables

var (
	WithAgents          = agent.WithAgents
	WithMode            = agent.WithMode
	WithManager         = agent.WithManager
	WithMaxRounds       = agent.WithMaxRounds
	WithTeamDescription = agent.WithTeamDescription
)

团队选项

var (
	WithBudget              = cost.WithBudget
	WithMaxTokensPerRequest = cost.WithMaxTokensPerRequest
	WithMaxTokensPerSession = cost.WithMaxTokensPerSession
	WithMaxTokensTotal      = cost.WithMaxTokensTotal
	WithRequestsPerMinute   = cost.WithRequestsPerMinute
)

成本控制选项

var (
	WithRAGStore    = rag.WithStore
	WithRAGEmbedder = rag.WithEngineEmbedder
	WithRAGLoader   = rag.WithLoader
	WithRAGSplitter = rag.WithEngineSplitter
	WithRAGTopK     = rag.WithEngineTopK
	WithRAGMinScore = rag.WithEngineMinScore
)

RAG 引擎选项

var (
	// WithFilter 设置元数据过滤条件
	WithFilter = rag.WithFilter

	// WithTopK 设置返回文档数量
	WithTopK = rag.WithTopK

	// WithMinScore 设置最小相关性分数
	WithMinScore = rag.WithMinScore
)

RAG 检索选项

var (
	// NewTextLoader 创建文本文件加载器
	NewTextLoader = loader.NewTextLoader

	// NewMarkdownLoader 创建 Markdown 文件加载器
	NewMarkdownLoader = loader.NewMarkdownLoader

	// NewDirectoryLoader 创建目录批量加载器
	NewDirectoryLoader = loader.NewDirectoryLoader

	// NewURLLoader 创建 URL 加载器
	NewURLLoader = loader.NewURLLoader

	// NewStringLoader 创建字符串加载器
	NewStringLoader = loader.NewStringLoader
)

文档加载器

var (
	// NewCharacterSplitter 创建字符分割器
	NewCharacterSplitter = splitter.NewCharacterSplitter

	// NewRecursiveSplitter 创建递归分割器
	NewRecursiveSplitter = splitter.NewRecursiveSplitter

	// NewMarkdownSplitter 创建 Markdown 分割器
	NewMarkdownSplitter = splitter.NewMarkdownSplitter

	// NewSentenceSplitter 创建句子分割器
	NewSentenceSplitter = splitter.NewSentenceSplitter
)

文档分割器

var (
	// NewVectorRetriever 创建向量检索器
	NewVectorRetriever = retriever.NewVectorRetriever

	// NewKeywordRetriever 创建关键词检索器
	NewKeywordRetriever = retriever.NewKeywordRetriever

	// NewHybridRetriever 创建混合检索器
	NewHybridRetriever = retriever.NewHybridRetriever

	// NewMultiRetriever 创建多源检索器
	NewMultiRetriever = retriever.NewMultiRetriever
)

文档检索器

var (
	// NewVectorIndexer 创建向量索引器
	NewVectorIndexer = indexer.NewVectorIndexer

	// NewConcurrentIndexer 创建并发索引器
	NewConcurrentIndexer = indexer.NewConcurrentIndexer

	// NewIncrementalIndexer 创建增量索引器
	NewIncrementalIndexer = indexer.NewIncrementalIndexer
)

文档索引器

var (
	// NewOpenAIEmbedder 创建 OpenAI Embedder
	NewOpenAIEmbedder = embedder.NewOpenAIEmbedder

	// NewCachedEmbedder 创建带缓存的 Embedder
	NewCachedEmbedder = embedder.NewCachedEmbedder

	// NewMockEmbedder 创建模拟 Embedder（用于测试）
	NewMockEmbedder = embedder.NewMockEmbedder
)

向量生成器

var (
	// NewMemoryVectorStore 创建内存向量存储
	NewMemoryVectorStore = vector.NewMemoryStore

	// NewQdrantStore 创建 Qdrant 向量存储
	//
	// 示例：
	//
	//	store, err := hexagon.NewQdrantStore(hexagon.QdrantConfig{
	//	    Host:             "localhost",
	//	    Port:             6333,
	//	    Collection:       "documents",
	//	    Dimension:        1536,
	//	    CreateCollection: true,
	//	})
	NewQdrantStore = qdrant.New
)

向量存储

var (
	QdrantWithHost             = qdrant.WithHost
	QdrantWithPort             = qdrant.WithPort
	QdrantWithCollection       = qdrant.WithCollection
	QdrantWithDimension        = qdrant.WithDimension
	QdrantWithAPIKey           = qdrant.WithAPIKey
	QdrantWithHTTPS            = qdrant.WithHTTPS
	QdrantWithTimeout          = qdrant.WithTimeout
	QdrantWithDistance         = qdrant.WithDistance
	QdrantWithOnDisk           = qdrant.WithOnDisk
	QdrantWithCreateCollection = qdrant.WithCreateCollection
)

Qdrant 配置选项

var ConnectMCPSSE = mcp.ConnectSSEServerV2

ConnectMCPSSE 通过 SSE 连接 MCP Server

示例：

tools, closer, err := hexagon.ConnectMCPSSE(ctx, "http://localhost:8080/sse")
defer closer.Close()

var ConnectMCPServer = mcp.ConnectMCPServerV2

ConnectMCPServer 使用官方 SDK 连接 MCP Server 并获取工具列表

返回的 []tool.Tool 可直接用于 Hexagon Agent。 调用方需要在使用完毕后调用 closer.Close() 释放连接。

示例：

tools, closer, err := hexagon.ConnectMCPServer(ctx, transport)
defer closer.Close()
agent := hexagon.QuickStart(hexagon.WithTools(tools...))

var ConnectMCPStdio = mcp.ConnectStdioServerV2

ConnectMCPStdio 通过 Stdio 连接 MCP Server

启动子进程并通过 stdin/stdout 通信。

示例：

tools, cleanup, err := hexagon.ConnectMCPStdio(ctx, "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp")
defer cleanup()

var ContextWithTracer = tracer.ContextWithTracer

ContextWithTracer 将追踪器添加到 context

var ErrNoProvider = errors.New("no LLM provider configured: set OPENAI_API_KEY environment variable or use WithProvider() option")

ErrNoProvider 表示没有配置 LLM Provider

var NewBufferMemory = memory.NewBuffer

NewBufferMemory 创建缓冲记忆

var NewCostController = cost.NewController

NewCostController 创建成本控制器

示例：

controller := hexagon.NewCostController(
    hexagon.WithBudget(10.0),  // $10 预算
    hexagon.WithMaxTokensTotal(100000),
)

var NewFileStore = memstore.NewFileStore

NewFileStore 创建文件持久化记忆存储

基于文件系统的持久化存储，支持原子写入和 TTL 过期。

示例：

store, err := hexagon.NewFileStore("/data/memory")

var NewGlobalState = agent.NewGlobalState

NewGlobalState 创建全局状态

var NewGuardChain = guard.NewGuardChain

NewGuardChain 创建守卫链

var NewInMemoryStore = memstore.NewInMemoryStore

NewInMemoryStore 创建内存记忆存储

纯内存实现，适合开发和测试。支持命名空间隔离、TTL、关键词搜索。

示例：

store := hexagon.NewInMemoryStore()
store.Put(ctx, []string{"users", "u1"}, "prefs", map[string]any{"theme": "dark"})

var NewMCPServer = mcp.NewMCPServerV2

NewMCPServer 创建基于官方 SDK 的 MCP 服务器

将 Hexagon/ai-core 工具暴露为标准 MCP 服务。

示例：

server := hexagon.NewMCPServer("my-tools", "1.0.0")
server.RegisterTool(myCalculator)
server.ServeStdio(ctx)

var NewMetrics = metrics.NewMemoryMetrics

NewMetrics 创建内存指标收集器

示例：

m := hexagon.NewMetrics()
m.Counter("agent_calls", "agent", "react").Inc()

var NewNoopTracer = tracer.NewNoopTracer

NewNoopTracer 创建空追踪器（禁用追踪）

var NewOpenAI = openai.New

NewOpenAI 创建 OpenAI Provider

var NewPIIGuard = guard.NewPIIGuard

NewPIIGuard 创建 PII 检测守卫

var NewPersistentMemory = memstore.NewPersistentMemory

NewPersistentMemory 创建持久记忆适配器

将 MemoryStore 适配为 ai-core memory.Memory 接口， 使现有 Agent 无缝使用持久化存储。

示例：

store := hexagon.NewInMemoryStore()
mem := hexagon.NewPersistentMemory(store, []string{"users", "u123"})
agent := hexagon.QuickStart(hexagon.WithMemory(mem))

var NewPromptInjectionGuard = guard.NewPromptInjectionGuard

NewPromptInjectionGuard 创建 Prompt 注入检测守卫

示例：

guard := hexagon.NewPromptInjectionGuard()
result, _ := guard.Check(ctx, userInput)
if !result.Passed {
    // 处理潜在的注入攻击
}

var NewQdrantStoreWithOptions = qdrant.NewWithOptions

Qdrant 选项式创建

var NewRAGEngine = rag.NewEngine

NewRAGEngine 创建 RAG 引擎

示例：

engine := hexagon.NewRAGEngine(
    hexagon.WithRAGStore(vectorStore),
    hexagon.WithRAGEmbedder(embedder),
)
docs, _ := engine.Retrieve(ctx, "What is Go?")

var NewRAGPipeline = rag.NewPipeline

NewRAGPipeline 创建 RAG 管道

var NewReActAgent = agent.NewReAct

NewReActAgent 创建 ReAct Agent

var NewRedisStore = memstore.NewRedisStore

NewRedisStore 创建 Redis 持久化记忆存储

基于 Redis 的高性能持久化存储，支持命名空间隔离和 Pipeline 操作。

var NewStateManager = agent.NewStateManager

NewStateManager 创建状态管理器

示例：

sm := hexagon.NewStateManager("session-123", nil)
sm.Turn().Set("key", "value")
sm.Session().Set("user_id", 123)

var NewTeam = agent.NewTeam

NewTeam 创建 Agent 团队

示例：

team := hexagon.NewTeam("research-team",
    hexagon.WithAgents(researcher, writer),
    hexagon.WithMode(hexagon.TeamModeSequential),
)

var NewTracer = tracer.NewMemoryTracer

NewTracer 创建内存追踪器

示例：

tracer := hexagon.NewTracer()
ctx := hexagon.ContextWithTracer(ctx, tracer)

var StartSpan = tracer.StartSpan

StartSpan 开始新的追踪 Span

var TransferTo = agent.TransferTo

TransferTo 创建 Agent 交接工具（借鉴 OpenAI Swarm）

示例：

tools := []hexagon.Tool{
    hexagon.TransferTo(salesAgent),
    hexagon.TransferTo(supportAgent),
}

Functions

func Chat

func Chat(ctx context.Context, query string, opts ...QuickStartOption) (string, error)

Chat 执行简单对话（最简 API）

示例：

response, err := hexagon.Chat(ctx, "What is Go?")
fmt.Println(response)

func ChatWithTools

func ChatWithTools(ctx context.Context, query string, tools ...tool.Tool) (string, error)

ChatWithTools 带工具的对话

示例：

result, err := hexagon.ChatWithTools(ctx, "What is 123 * 456?", calculatorTool)

func NewChain

func NewChain[I, O any](name string) *chain.ChainBuilder[I, O]

NewChain 创建链式编排构建器

示例：

c, _ := hexagon.NewChain[Input, Output]("my-chain").
    Pipe(step1).
    Pipe(step2).
    Build()

func NewGraph

func NewGraph[S graph.State](name string) *graph.GraphBuilder[S]

NewGraph 创建图编排构建器

示例：

g, _ := hexagon.NewGraph[MyState]("my-graph").
    AddNode("step1", handler1).
    AddNode("step2", handler2).
    AddEdge(hexagon.START, "step1").
    AddEdge("step1", "step2").
    AddEdge("step2", hexagon.END).
    Build()

func NewTool

func NewTool[I, O any](name, description string, fn func(context.Context, I) (O, error)) *tool.FuncTool[I, O]

NewTool 从函数创建工具

示例：

type CalcInput struct {
    A float64 `json:"a" desc:"第一个数字" required:"true"`
    B float64 `json:"b" desc:"第二个数字" required:"true"`
}

calculator := hexagon.NewTool("calculator", "执行加法计算",
    func(ctx context.Context, input CalcInput) (float64, error) {
        return input.A + input.B, nil
    },
)

func QuickStart

func QuickStart(opts ...QuickStartOption) *agent.ReActAgent

QuickStart 快速创建一个 ReAct Agent

注意：需要配置 LLM Provider，可以通过以下方式之一：

• 设置 OPENAI_API_KEY 环境变量
• 使用 WithProvider() 选项
• 调用 SetDefaultProvider()

如果没有配置 Provider，QuickStart 不会 panic， 但后续执行时会返回未配置 Provider 的错误。

示例：

agent := hexagon.QuickStart(
    hexagon.WithTools(searchTool, calculatorTool),
    hexagon.WithSystemPrompt("You are a helpful assistant."),
)
output, err := agent.Run(ctx, hexagon.Input{Query: "What is 2+2?"})

func SetDefaultProvider

func SetDefaultProvider(p llm.Provider)

SetDefaultProvider 设置默认 LLM Provider（并发安全）

Types

type Agent

type Agent = agent.Agent

Agent 是 Agent 接口

type Chain

type Chain[I, O any] = chain.Chain[I, O]

Chain 是链式组件

type Component

type Component[I, O any] = core.Component[I, O]

Component 是组件接口

type CostController

type CostController = cost.Controller

CostController 是成本控制器

type Document

type Document = rag.Document

Document 是 RAG 文档

type Embedder

type Embedder = rag.Embedder

Embedder 是向量生成器接口

type Graph

type Graph[S graph.State] = graph.Graph[S]

Graph 是编译后的图

type Guard

type Guard = guard.Guard

Guard 是守卫接口

type Indexer

type Indexer = rag.Indexer

Indexer 是文档索引器接口

type Input

type Input = agent.Input

Input 是 Agent 输入

type Loader

type Loader = rag.Loader

Loader 是文档加载器接口

type MCPServerV2

type MCPServerV2 = mcp.ServerV2

MCPServerV2 是基于官方 SDK 的 MCP 服务器

type MapState

type MapState = graph.MapState

MapState 是通用 map 状态

type Memory

type Memory = memory.Memory

Memory 是记忆接口

type MemoryItem

type MemoryItem = memstore.Item

MemoryItem 是记忆存储条目

type MemoryStore

type MemoryStore = memstore.MemoryStore

MemoryStore 是跨会话持久记忆存储接口

type Message

type Message = llm.Message

Message 是聊天消息

type Metrics

type Metrics = metrics.Metrics

Metrics 是指标接口

type Output

type Output = agent.Output

Output 是 Agent 输出

func Run

func Run(ctx context.Context, input Input, opts ...QuickStartOption) (Output, error)

Run 执行 Agent 并返回完整输出

示例：

output, err := hexagon.Run(ctx, hexagon.Input{Query: "Hello"})

type QdrantConfig

type QdrantConfig = qdrant.Config

QdrantConfig 是 Qdrant 配置

type QuickStartOption

type QuickStartOption func(*quickStartConfig)

QuickStartOption 是 QuickStart 的配置选项

func WithMemory

func WithMemory(m memory.Memory) QuickStartOption

WithMemory 设置记忆系统

func WithProvider

func WithProvider(p llm.Provider) QuickStartOption

WithProvider 设置 LLM Provider

func WithSystemPrompt

func WithSystemPrompt(prompt string) QuickStartOption

WithSystemPrompt 设置系统提示词

func WithTools

func WithTools(tools ...tool.Tool) QuickStartOption

WithTools 设置工具

type RAGEngine

type RAGEngine = rag.Engine

RAGEngine 是 RAG 引擎

type Retriever

type Retriever = rag.Retriever

Retriever 是文档检索器接口

type Role

type Role = agent.Role

Role 是角色定义

type Schema

type Schema = core.Schema

Schema 是 JSON Schema

type Span

type Span = tracer.Span

Span 是追踪 Span 接口

type Splitter

type Splitter = rag.Splitter

Splitter 是文档分割器接口

type State

type State = graph.State

State 是图状态接口

type StateManager

type StateManager = agent.StateManager

StateManager 是状态管理器接口

type Stream

type Stream[T any] = core.Stream[T]

Stream 是泛型流接口

type Team

type Team = agent.Team

Team 是团队

type Tool

type Tool = tool.Tool

Tool 是工具接口

type Tracer

type Tracer = tracer.Tracer

Tracer 是追踪器接口

type VectorStore

type VectorStore = rag.VectorStore

VectorStore 是向量存储接口