🚀 2026 年生产级 Go 语言 LLM Agent 框架
English | 中文
- 官方单 Agent 主链 -
react + native tool calling + checkpoint/session/guardrails - 官方多 Agent 门面 -
agent/team，统一supervisor / selector / round_robin / swarm - Reflection 机制 - 自我评估与迭代改进
- 动态工具选择 - 智能工具匹配，减少 Token 消耗
- 双模型架构 (toolProvider) - 便宜模型优先承担工具调用链路（原生 tool calling，非原生 provider 自动降级 XML tool-calling），贵模型做内容生成，大幅降低成本
- Skills 系统 - 动态技能加载
- MCP/A2A 协议 - 完整 Agent 互操作协议栈 (支持 Google A2A & Anthropic MCP)
- Guardrails - 输入/输出验证、PII 检测、注入防护、自定义验证规则
- Evaluation - 自动化评估框架 (A/B 测试、LLM Judge、研究质量多维评估)
- Thought Signatures - 推理链签名，保持多轮推理连续性
- 角色编排 (Role Pipeline) - 多 Agent 角色流水线，支持 Collector→Filter→Generator→Validator→Writer 研究管线
- Web 工具 - Web Search / Web Scrape 工具抽象，支持可插拔搜索/抓取后端
- 声明式 Agent 加载器 — YAML/JSON 定义 Agent，工厂自动装配
- 插件系统 — 插件注册表、生命周期管理（Init/Shutdown）
- Human-in-the-Loop — 人工审批节点
- Agent 联邦/服务发现 — 跨集群编排与注册发现
- 多层记忆 - 仿人脑记忆架构：
- 短期/工作记忆 (Working Memory) - 存储当前任务上下文，支持 TTL 与优先级衰减
- 长期记忆 (Long-term Memory) - 结构化信息存储
- 情节记忆 (Episodic Memory) - 存储事件序列与执行经验
- 语义记忆 (Semantic Memory) - 存储事实知识与本体关系
- 程序性记忆 (Procedural Memory) - 存储“如何做”的技能与流程
- Intelligent Decay - 基于 recency/relevance/utility 的智能衰减算法
- 上下文工程 - 自适应压缩、摘要、窗口管理、紧急截断
- 官方默认 -
ReAct作为唯一默认推理/执行主链 - 高级显式启用 -
Reflexion、ReWOO、Plan-Execute - 实验能力 -
Dynamic Planner、Iterative Deepening - 统一约束 - 高级与实验模式不再默认注入 runtime，需显式 opt-in
- DAG 工作流 - 支持有向无环图的复杂逻辑编排
- DAG 节点并行执行 - 支持分支并发执行与结果聚合
- 状态持久化 - 支持检查点 (Checkpoint) 的保存与恢复
- 熔断器 (Circuit Breaker) - DAG 节点级熔断保护（Closed/Open/HalfOpen 三态机）
- YAML DSL 编排语言 - 声明式工作流定义，支持变量插值、条件分支、循环、子图
- 单入口启动链路 -
cmd/agentflow/main.runServe -> internal/app/bootstrap.InitializeServeRuntime -> cmd/agentflow/server_handlers_runtime.BuildServeHandlerSet -> cmd/agentflow/server_http.RegisterHTTPRoutes -> api/routes -> api/handlers -> internal/usecase -> domain(agent/rag/workflow/llm) - 组合根职责收敛 -
cmd仅做装配；运行时构建集中在internal/app/bootstrap（详见docs/architecture/启动装配链路与组合根说明.md） - 组合根状态已分 bundle -
cmd/agentflow/server_runtime_bundles.go将长生命周期状态收口到handlers / text / tooling / workflow / infra / ops六组，避免Server持有一整份扁平跨域字段表 - 热重载单 seam -
server_hotreload.go只负责触发重建与状态回写，真正的chat/cost绑定、resolver 重建、workflow runtime 重建统一下沉到internal/app/bootstrap - 用例边界已收口 -
internal/usecase现在对 handler 暴露自有chat/workflow契约，例如ChatStreamEvent、WorkflowPlan、WorkflowNodeEvent，handler 不再直接依赖llmcore.UnifiedChunk或workflow.DAGWorkflow - 领域入口并列 -
api/handlers可直接进入agent usecase、rag usecase、workflow usecase；不是所有请求都必须先进入workflow - 编排关系固定 -
workflow是 Layer 3 编排层，不是agent的一种；有编排需求时由workflow调用agent/rag/llm，无编排需求时可直接走agent或rag
- 混合检索 (Hybrid Retrieval) - 结合向量搜索 (Dense) 与关键词搜索 (Sparse)
- BM25 Contextual Retrieval - 基于 Anthropic 最佳实践的上下文检索，BM25 参数可调（k1/b），IDF 缓存
- Multi-hop 推理与去重 - 多跳推理链，四阶段去重流程（ID 去重 + 内容相似度去重），DedupStats 统计
- Web 增强检索 - 本地 RAG + 实时 Web 搜索混合检索，支持权重分配与结果去重
- 语义缓存 (Semantic Cache) - 基于向量相似度的响应缓存，大幅降低延迟与成本
- 多向量数据库支持 - Qdrant, Pinecone, Milvus, Weaviate 及内置 InMemoryStore
- 文档管理 - 自动分块 (Chunking)、元数据过滤、重排序 (Reranker)
- 学术数据源 - arXiv 论文检索、GitHub 仓库/代码搜索适配器
- DocumentLoader — 统一文档加载接口（Text/Markdown/CSV/JSON）
- RAG Runtime Builder — 统一通过
rag/runtime.Builder完成配置桥接与运行时装配 - Graph RAG — 知识图谱检索增强
- 查询路由/变换 — 智能查询分发与改写
- 10+ 独立提供商 + 4 个兼容厂商 - OpenAI、Anthropic Claude、Google Gemini、xAI Grok、GLM、MiniMax、Mistral、Qwen（通义千问）、Doubao（豆包）独立实现；DeepSeek、Kimi、腾讯混元、Llama 通过 OpenAI 兼容层接入
- 智能路由 - 成本/健康/QPS 负载均衡
- A/B 测试路由 - 多变体流量分配、粘性路由、动态权重调整、指标收集
- 统一 Token 计数器 - Tokenizer 接口 + tiktoken 适配器 + CJK 估算器
- Provider 重试包装器 - RetryableProvider 指数退避重试，仅重试可恢复错误
- API Key 池 - 多 Key 轮询、限流检测
- Provider 工厂函数 — 配置驱动的 Provider 实例化（标准 chat 入口：
llm/providers/vendor.NewChatProviderFromConfig） - OpenAI 兼容层 — 统一适配 OpenAI 兼容 API（9 个 provider 瘦身至 ~30 行）
- 协议兼容 HTTP 入站 —
/v1/chat/completions、/v1/responses、/v1/messages统一收口到同一ChatService -> llm/gateway主链；Gemini / VertexgenerateContent路径保持 provider 出站协议边界
- Embedding - OpenAI、Gemini、Cohere、Jina、Voyage
- Image -
gpt-image-1、Imagen 4、Flux、Stability、Ideogram、通义万相、智谱、文心一格、豆包、腾讯混元、可灵 - Video -
sora-2、Runway Gen-4.5 /gen4_turbo、Veo 3.1、Gemini、可灵、Luma、MiniMax、即梦 Seedance - Speech -
gpt-4o-mini-tts、gpt-4o-transcribe、ElevenLabs、Deepgram - Music - Suno, MiniMax
- 3D - Meshy, Tripo
- Rerank - Cohere, Qwen, GLM
- 文档总表 - 近 12 个月主流模型总表见
docs/cn/guides/近12个月主流多模态模型总表.md
- 弹性机制 - 重试、幂等、熔断
- 可观测性 - Prometheus 指标、OpenTelemetry 追踪
- 缓存系统 - 多级缓存策略
- API 安全中间件 - API Key 认证、IP 限流、CORS、Panic 恢复、请求日志
- 成本控制与预算管理 - Token 计数、周期重置、成本报告、优化建议
- 配置热重载与回滚 - 文件监听自动重载、版本化历史、一键回滚、验证钩子
- MCP WebSocket 心跳重连 — 指数退避重连、连接状态监控
- 金丝雀发布 (Canary) — 分阶段流量切换（10%→50%→100%）、自动回滚、错误率/延迟监控
- API Key 仅支持
X-API-KeyHeader，api_keyQuery 参数已禁用且不再受支持。 server.environment=production时，server.allow_no_auth=true会在启动校验阶段直接报错并拒绝启动。- 当未配置 JWT/API Key 且
server.allow_no_auth=false时，受保护接口会 fail-closed 返回503。 - 升级建议：生产环境必须显式配置
server.api_keys或server.jwt；仅development/test环境可设置server.allow_no_auth=true。
go get github.com/BaSui01/agentflow正式入口约定：
- 仓库级正式入口统一为
sdk.New(opts).Build(ctx) agent/runtime.Builder作为agent子模块 runtime 入口- 多 Agent 正式入口统一为
agent/team，显式编排正式入口统一为workflow/runtime github.com/BaSui01/agentflow/agent根包已删除；需要直接使用 Agent runtime DTO / Builder 时，请显式导入agent/runtimegithub.com/BaSui01/agentflow/rag、github.com/BaSui01/agentflow/workflow、github.com/BaSui01/agentflow/llm根包已删除；分别改为导入rag/runtime、workflow/core|runtime、llm/core|gateway|runtime/compose- Agent 运行时主面采用三层模型：
Model / Control / ToolsModel负责模型与 provider 相关参数Control负责 loop/budget/reasoning/override 等执行控制Tools负责工具声明、选择与协议装配
types.AgentConfig是对外配置入口，运行时会先收口为ExecutionOptions，再由ChatRequestAdapter生成 provider 侧ChatRequestChatRequest只是 gateway/provider adapter DTO，不是 Agent 运行时正式配置主面
完整可运行示例：examples/01_simple_chat/
package main
import (
"context"
"fmt"
"os"
agent "github.com/BaSui01/agentflow/agent/runtime"
"github.com/BaSui01/agentflow/sdk"
"github.com/BaSui01/agentflow/llm/providers"
openaiprov "github.com/BaSui01/agentflow/llm/providers/openai"
"github.com/BaSui01/agentflow/types"
"go.uber.org/zap"
)
func main() {
ctx := context.Background()
logger, _ := zap.NewDevelopment()
defer logger.Sync()
provider := openaiprov.NewOpenAIProvider(providers.OpenAIConfig{
BaseProviderConfig: providers.BaseProviderConfig{
APIKey: os.Getenv("OPENAI_API_KEY"),
BaseURL: "https://api.openai.com",
},
}, logger)
rt, err := sdk.New(sdk.Options{
Logger: logger,
LLM: &sdk.LLMOptions{
Provider: provider,
},
Agent: &sdk.AgentOptions{},
}).Build(ctx)
if err != nil {
panic(err)
}
ag, err := rt.NewAgent(ctx, types.AgentConfig{
Core: types.CoreConfig{
ID: "hello-agent",
Name: "Hello Agent",
Type: "assistant",
},
LLM: types.LLMConfig{
Model: "gpt-5.4",
},
})
if err != nil {
panic(err)
}
if err := ag.Init(ctx); err != nil {
panic(err)
}
out, err := ag.Execute(ctx, &agent.Input{
Content: "Hello!",
})
if err != nil {
panic(err)
}
fmt.Println(out.Content)
}package main
import (
"context"
"fmt"
"os"
llm "github.com/BaSui01/agentflow/llm/core"
llmrouter "github.com/BaSui01/agentflow/llm/runtime/router"
"github.com/glebarez/sqlite"
"go.uber.org/zap"
"gorm.io/gorm"
)
func main() {
logger, _ := zap.NewDevelopment()
defer logger.Sync()
ctx := context.Background()
db, err := gorm.Open(sqlite.Open("file::memory:?cache=shared"), &gorm.Config{})
if err != nil {
panic(err)
}
// AutoMigrate LLM provider/model tables
if err := db.AutoMigrate(&llm.LLMProvider{}, &llm.LLMModel{}, &llm.LLMProviderModel{}, &llm.LLMProviderAPIKey{}); err != nil {
panic(err)
}
// Minimal seed: one provider + one model + mapping + API key.
p := llm.LLMProvider{Code: "openai", Name: "OpenAI", Status: llm.LLMProviderStatusActive}
if err := db.Create(&p).Error; err != nil {
panic(err)
}
m := llm.LLMModel{ModelName: "gpt-5.4", DisplayName: "GPT-5.4", Enabled: true}
if err := db.Create(&m).Error; err != nil {
panic(err)
}
pm := llm.LLMProviderModel{
ModelID: m.ID,
ProviderID: p.ID,
RemoteModelName: "gpt-5.4",
BaseURL: "https://api.openai.com",
PriceInput: 0.001,
PriceCompletion: 0.002,
Priority: 10,
Enabled: true,
}
if err := db.Create(&pm).Error; err != nil {
panic(err)
}
key := os.Getenv("OPENAI_API_KEY")
if key == "" {
key = "sk-xxx" // demo key (no live call without real key)
}
if err := db.Create(&llm.LLMProviderAPIKey{
ProviderID: p.ID,
APIKey: key,
Label: "default",
Priority: 10,
Weight: 100,
Enabled: true,
}).Error; err != nil {
panic(err)
}
factory := llmrouter.VendorChatProviderFactory{Logger: logger}
router := llmrouter.NewMultiProviderRouter(db, factory, llmrouter.RouterOptions{Logger: logger})
if err := router.InitAPIKeyPools(ctx); err != nil {
panic(err)
}
selection, err := router.SelectProviderWithModel(ctx, "gpt-5.4", llmrouter.StrategyCostBased)
if err != nil {
panic(err)
}
fmt.Printf("selected provider=%s model=%s\n", selection.ProviderCode, selection.ModelName)
}推荐把 llm/runtime/router.VendorChatProviderFactory 视为配置驱动 chat provider 的标准构造入口；只有在你明确需要 provider 包级低级 API 时，才直接使用 llm/providers/openai、llm/providers/anthropic、llm/providers/gemini 构造器。
上面的 MultiProviderRouter 示例只用于维护框架内置的 legacy DB-backed provider + api_key pool 部署。
如果你是在做新的 routed-provider 集成，不要把它当作仓库级推荐主入口，直接从 BuildChannelRoutedProvider(...) 开始。
如果你的底层路由语义不是 provider + api_key pool，而是业务侧自定义的 channel / key / model mapping：
- 推荐主链路是：
Handler/Service -> Gateway -> ChannelRoutedProvider -> resolvers/selectors -> provider factory -> provider API ChannelRoutedProvider是 channel-based routing 的推荐主入口- 外部项目建议通过
BuildChannelRoutedProvider(...)一次性装配这条链，而不是手工散落 wiring - 仓库内置
llm/runtime/router/extensions/channelstore作为通用 extension 起点，提供StoreModelMappingResolver、PriorityWeightedSelector、StoreSecretResolver、StoreProviderConfigSource、StaticStore - 上层业务保持
Handler/Service -> Gateway不变，迁移时只替换Gateway后面的 routed provider 链路 - 通过
ChannelSelector、ModelMappingResolver、SecretResolver、UsageRecorder等接口注入自定义实现 BuildChannelRoutedProvider(...)是新接入唯一推荐的 routed-provider 装配入口MultiProviderRouter仅为旧部署兼容与维护保留；如果你仍在使用它，请把它视为 legacy DB-backed 实现，而不是与ChannelRoutedProvider并列的同级推荐入口- 旧部署若还依赖 DB-backed provider catalog + API key pool，可继续停留在
Gateway -> RoutedChatProvider -> MultiProviderRouter，但不要在新的公共接入链路里再引入它 - 外部项目现在可通过
llm/runtime/compose.Build(...)复用同一套 resilience/cache/policy/tool-provider runtime 装配；仓库自身组合根继续通过internal/app/bootstrap.BuildLLMHandlerRuntimeFromProvider(...)复用这层公共装配；image/video仍延后到gateway + capabilities - 仓库内置
llm.main_provider_mode启动切换位；仓库自身通过internal/app/bootstrap.RegisterMainProviderBuilder(...)注册channel_routedbuilder 并复用 server 启动链；外部项目若需要相同模式，应在自己的组合根直接调用channelstore.NewMainProviderBuilder(...)或自行装配 routed provider llm/runtime/router/extensions/runtimepolicy提供可复用的UsageRecorder/CooldownController/QuotaPolicy参考实现，便于先把 usage、cooldown、daily limit、concurrency limit 链路跑通- 第一阶段不把
image/video接进ChannelRoutedProvider，因为 image/video 当前走的是 capability 路由面：gateway + capabilities + vendor.Profile；若硬塞进llm.Provider，会把文本 routed provider 与多模态 capability 入口过早耦合 - 外部项目的 adapter-only 接入模板与配置切换示例见
docs/architecture/Channel路由外部接入模板-中文版.md - 设计与迁移说明见
docs/architecture/Channel路由扩展架构说明.md
完整可运行示例：examples/06_advanced_features/（或 examples/09_full_integration/）
executor := agent.NewReflectionExecutor(baseAgent, agent.ReflectionExecutorConfig{
Enabled: true,
MaxIterations: 3,
MinQuality: 0.7,
})
result, _ := executor.ExecuteWithReflection(ctx, input)opts := runtime.DefaultBuildOptions()
opts.EnableAll = false
opts.EnableLSP = true
rt, err := sdk.New(sdk.Options{
Logger: logger,
LLM: &sdk.LLMOptions{
Provider: provider,
},
Agent: &sdk.AgentOptions{
BuildOptions: opts,
},
}).Build(ctx)
if err != nil {
panic(err)
}
ag, err := rt.NewAgent(ctx, types.AgentConfig{
Core: types.CoreConfig{
ID: "assistant-1",
Name: "Assistant",
Type: "assistant",
},
LLM: types.LLMConfig{
Model: "gpt-5.4",
},
})
if err != nil {
panic(err)
}
fmt.Println("LSP enabled:", ag.GetFeatureStatus()["lsp"])上下文运行时默认会随 sdk -> agent/runtime.Builder 主链装配；可通过 types.AgentConfig.Context 控制预算与压缩策略：
cfg.Context = &types.ContextConfig{
Enabled: true,
MaxContextTokens: 128000,
ReserveForOutput: 4096,
}启用 Skills / 增强 Memory / retrieval / tool-state 注入时，这些信息会作为 context runtime 管理的独立上下文段进入消息组装，而不是直接改写原始用户输入。
请求级 session_overlay、trace_feedback_plan、trace_synopsis、trace_history、tool_guidance、verification_gate、context_pressure 等临时策略层，也会统一通过 ephemeral prompt layer builder 注入，而不是并入稳定 system prompt；其中 tool_guidance 会按 safe_read / requires_approval / unknown 风险层输出工具提示，审批语义会同时进入 runtime stream 事件与 explainability trace，并进一步汇总进高层 decision timeline（如 prompt_layers / approval / validation_gate / completion_decision），最终生成双层可回灌摘要：短层 trace_synopsis 与压缩长层 trace_history。这两层是否注入不再是写死规则，而是由轻量 TraceFeedbackPlanner 先产出一个 trace-aware micro plan（目标、推荐动作、主/辅层、原因、阈值），再决定是否注入，并把决策结果写入 trace_feedback_decision timeline。默认主链是 ComposedTraceFeedbackPlanner(rule-based planner + hint adapter)，后续统计驱动或 LLM 规划器也应通过同一 planner adapter 面接入，而不是引入第二套注入主链。
也可以通过 runtime.Builder 一键开关：
opts := runtime.DefaultBuildOptions()
opts.EnableAll = false
opts.EnableLSP = true
gateway := llmgateway.New(llmgateway.Config{ChatProvider: provider, Logger: logger})
ag, err := runtime.NewBuilder(gateway, logger).
WithOptions(opts).
Build(ctx, cfg)
if err != nil {
panic(err)
}
_ = ag完整可运行示例：examples/05_workflow/
graph := workflow.NewDAGGraph()
graph.AddNode(&workflow.DAGNode{ID: "start", Type: workflow.NodeTypeAction, Step: startStep})
graph.AddNode(&workflow.DAGNode{ID: "process", Type: workflow.NodeTypeAction, Step: processStep})
graph.AddEdge("start", "process")
graph.SetEntry("start")
wf := workflow.NewDAGWorkflow("my-workflow", "description", graph)
rt, _ := sdk.New(sdk.Options{
Logger: logger,
Workflow: &sdk.WorkflowOptions{Enable: true},
}).Build(ctx)
result, _ := rt.Workflow.Facade.ExecuteDAG(ctx, wf, input)如果你觉得子目录过多、阅读压力大，先看精简导航：docs/cn/目录导航(精简版).md。
┌──────────────────────────────┐
│ cmd/ │
│ 组合根：启动/装配/生命周期 │
└──────────────┬───────────────┘
│
┌──────────────▼───────────────┐
│ api/ │
│ 协议适配层：HTTP/MCP/A2A │
└──────────────┬───────────────┘
│
┌──────────────▼───────────────┐
│ workflow/ (Layer 3) │
│ 编排层：DAG/DSL/步骤调度 │
│ 可调用 agent/rag/llm │
└───────┬─────────────┬────────┘
│ │
┌──────────────▼───┐ ┌────▼─────────────┐
│ agent/ (Layer 2) │ │ rag/ (Layer 2) │
│ 执行能力/推理/工具 │ │ 检索能力/索引/重排 │
└──────────────┬───┘ └────┬─────────────┘
│ │
└──────┬─────┘
│
┌─────────▼─────────┐
│ llm/ (Layer 1) │
│ Provider/Gateway │
└─────────┬─────────┘
│
┌─────────▼─────────┐
│ types/ (Layer 0) │
│ 零依赖共享契约层 │
└───────────────────┘
pkg/ = 横向基础设施层，可被多层复用，但不得反向依赖 api/ 与 cmd/
internal/app/bootstrap/ = 启动期装配与 bridge，属于组合根支撑，不承载领域决策
依赖规则速记：
types只允许被依赖，不反向依赖业务层llm不依赖agent/workflow/api/cmdagent与rag同属 Layer 2；单 agent 可以直接用 ragworkflow在agent/rag之上，是编排层，不是 agent 的一种api只做协议转换；cmd只做装配
| 源目录 | 允许依赖 | 禁止依赖 |
|---|---|---|
types/ |
无 | llm/、agent/、rag/、workflow/、api/、cmd/、internal/、config/、pkg/ |
llm/ |
types/、pkg/、config/ |
agent/、rag/、workflow/、api/、cmd/、internal/ |
agent/ |
types/、llm/、rag/、pkg/、config/ |
workflow/、api/、cmd/、internal/ |
rag/ |
types/、llm/、pkg/、config/ |
agent/、workflow/、api/、cmd/、internal/ |
workflow/ |
types/、llm/、agent/、rag/、pkg/、config/ |
api/、cmd/、internal/、agent/persistence |
api/ |
types/、llm/、agent/、rag/、workflow/、config/ |
provider 实现细节、组合根逻辑 |
cmd/ |
通过 internal/app/bootstrap 装配各层 |
业务实现下沉、绕过 bootstrap 直拼底层细节 |
pkg/ |
types/ 与必要的 pkg/* |
api/、cmd/ |
agentflow/
├── types/ # Layer 0: 零依赖核心类型
│ ├── message.go # Message, Role, ToolCall
│ ├── error.go # Error, ErrorCode
│ ├── token.go # TokenUsage, Tokenizer
│ ├── context.go # Context key helpers
│ ├── schema.go # JSONSchema
│ └── tool.go # ToolSchema, ToolResult
│
├── llm/ # Layer 1: LLM 抽象层（目录容器；root 无 Go 文件）
│ ├── providers/ # Provider 实现
│ │ ├── openai/ # OpenAI
│ │ ├── anthropic/ # Claude
│ │ ├── gemini/ # Gemini
│ │ ├── openaicompat/ # Compat Chat 基座
│ │ ├── vendor/ # Chat factory + vendor profiles
│ │ └── ... # 多模态 / 厂商特化能力实现
│ ├── runtime/ # Router / policy / compose
│ ├── gateway/ # 统一能力入口
│ ├── batch/ # 批量请求处理
│ ├── capabilities/ # Image / Video / Audio / Rerank ...
│ ├── core/ # Provider / request-response / gateway contracts
│ ├── tokenizer/ # 统一 Token 计数器
│ └── tools/ # 工具执行
│
├── agent/ # Layer 2: Agent 核心（目录容器；root 无 Go 文件）
│ ├── adapters/ # 适配层（chat/declarative/structured/handoff）
│ ├── capabilities/ # 能力层（memory/reasoning/planning/tools/guardrails/streaming）
│ ├── collaboration/ # 协作层（federation 联邦编排）
│ ├── core/ # 核心层（registry/helpers/extension contracts）
│ ├── execution/ # 执行层（runtime/context/loop/protocol/orchestration）
│ ├── integration/ # 集成层（deployment/hosted/k8s/lsp/voice）
│ ├── observability/ # 可观测层（monitoring/evaluation/hitl）
│ └── persistence/ # 持久化层（checkpoint/conversation/artifacts/mongodb）
│
├── rag/ # Layer 2: RAG 检索能力（目录容器；root 无 Go 文件）
│ ├── core/ # 检索契约 / document / vector store 抽象
│ ├── runtime/ # RAG 运行时构建入口与主能力面
│ ├── retrieval/ # hybrid / contextual / multi-hop / graph / query routing
│ ├── loader/ # DocumentLoader（Text/Markdown/CSV/JSON）
│ ├── sources/ # 数据源适配器（arXiv, GitHub）
│ └── adapter/ # runtime / loader / tokenizer 适配桥
│
├── workflow/ # Layer 3: 工作流编排层（目录容器；root 无 Go 文件）
│ ├── core/ # DAG / Workflow / Step / checkpoint 契约
│ ├── runtime/ # Builder / Facade 统一装配入口
│ ├── engine/ # 执行引擎与 step dependency integration
│ ├── steps/ # 节点级 step 实现
│ ├── observability/ # 执行历史与工作流可观测
│ └── dsl/ # YAML DSL 编排
│ ├── schema.go # DSL 类型定义
│ ├── parser.go # YAML 解析 + 变量插值
│ └── validator.go # DSL 验证器
│
├── api/ # 适配层：HTTP/MCP/A2A handler + routes
│ ├── handlers/ # 协议解析、响应序列化、service/usecase 入口
│ └── routes/ # 路由注册
│
├── internal/ # 组合根支撑：启动期 builder / wiring / bridge
│ └── app/bootstrap/ # runtime 构建、依赖注入、handler 装配
│
├── config/ # 配置管理
│ ├── loader.go # 配置加载器
│ ├── defaults.go # 默认配置
│ ├── hotreload.go # 热重载与回滚
│ ├── watcher.go # 文件监听
│ ├── api.go # 配置 API
│ └── doc.go # 包文档
│
├── pkg/ # 横向基础设施层（不得反向依赖 api/cmd）
│ ├── service/ # 生命周期服务注册与总线
│ └── openapi/ # OpenAPI 工具生成
│
├── cmd/agentflow/ # 应用入口与运行时装配
│ ├── main.go # CLI 入口（serve/migrate/health/version）
│ ├── migrate.go # 迁移子命令
│ ├── server_runtime.go # Server 结构与启动编排
│ ├── server_runtime_bundles.go # Server 运行时 bundle 分组（handlers/text/tooling/workflow/infra/ops）
│ ├── server_services.go # 基于 pkg/service.Registry 的生命周期总线
│ ├── server_http.go # 路由注册与 HTTP/Metrics 管理器构建
│ ├── server_handlers_runtime.go # 调用 BuildServeHandlerSet 并回填 Server 字段
│ ├── server_startup_summary.go # 启动摘要与能力/依赖状态汇总
│ ├── server_stores.go # Mongo/RAG/Memory/Audit 装配
│ ├── server_hotreload.go # 热重载管理器初始化
│ └── server_shutdown.go # 优雅关闭流程
│
└── examples/ # 示例代码（20 个场景）
| 示例 | 说明 |
|---|---|
| 01_simple_chat | 基础对话 |
| 02_streaming | 流式响应 |
| 03_tool_use | 工具调用 |
| 04_custom_agent | 自定义 Agent |
| 05_workflow | 工作流编排 |
| 06_advanced_features | 高级特性 |
| 07_mid_priority_features | 中优先级特性 |
| 08_low_priority_features | 低优先级特性 |
| 09_full_integration | 完整集成 |
| 11_multi_provider_apis | 多提供商 API |
| 12_complete_rag_system | RAG 系统 |
| 13_new_providers | 新提供商 |
| 14_guardrails | 安全护栏 |
| 15_structured_output | 结构化输出 |
| 16_a2a_protocol | A2A 协议 |
| 18_advanced_agent_features | 高级 Agent 特性 |
| 19_2026_features | 2026 新特性 |
| 20_multimodal_providers | 多模态提供商 |
| 21_research_workflow | 研究工作流 |
- 快速开始
- Provider 配置指南
- 近12个月主流多模态模型总表
- Agent 开发教程
- 架构文档索引
- Agent 框架现状与收口改进计划
- Function Calling 回归矩阵说明
- 工具集成说明
- 工作流编排
- 多模态处理
- 模型与媒体端点参考
- 多模态能力端点参考
- 视频与图像厂商及端点说明
- 检索增强 RAG
- Team 多 Agent 协作
- Hosted 工具与 MCP
- 工作流编排进阶
- 成本追踪
- 多模态框架 API
- 历史归档说明
- Go 1.24+
- MongoDB - 对话/运行状态/记忆/审计日志持久化
- Redis - 短期记忆/缓存
- PostgreSQL/MySQL/SQLite - 元数据 (GORM)
- Qdrant/Pinecone/Milvus/Weaviate - 向量存储
- Prometheus - 指标收集
- OpenTelemetry - 分布式追踪
- Zap - 结构化日志
- tiktoken-go - OpenAI Token 计数
- github.com/coder/websocket - WebSocket 客户端
- golang-migrate - 数据库迁移
- yaml.v3 - YAML 解析
MIT License - 详见 LICENSE