基于 cloudwego/eino 构建的 Go Agent 框架封装，提供统一的 Agent 创建入口、安全沙箱、MCP 工具管理和更多开箱即用的能力。

• 统一 Agent 入口 — Functional Options 模式，支持 Chat / Deep / Sequential / Parallel / Loop 五种 Agent 类型
• 安全沙箱 — RestrictedBackend + CommandValidator，路径白名单、命令两阶段验证、符号链接防逃逸
• MCP 工具管理 — 并发多服务器加载、自动重连、单服务器刷新、运行时动态注册
• 模型工厂 — 开箱即用 DefaultChatModel / DefaultOllamaChatModel，支持 OpenAI 兼容 API 和 Ollama 本地模型
• 中断审批门控 — 基于 eino-examples InvokableApprovableTool 为任意工具添加人工审批流程
• 知识库检索 — CNB 知识库工具，一行代码接入检索能力
• A2UI 协议 — 将 Agent 事件流转换为 A2UI 消息，一个 callback 即可接入 SSE/WebSocket/gRPC 等任意传输层

         +--------------------------------------+
         |         Agent Entry Layer            |
         |  NewChat / NewDeep / NewSequential   |
         |    / NewParallel / NewLoop           |
         |    (Functional Options Config)       |
         +------------------+-------------------+
                            |
          +-----------------+-----------------+
          |                 |                 |
          v                 v                 v
   +------------+   +------------+   +------------+
   | ChatModel  |   |    Deep    |   |  Workflow  |
   |   Agent    |   |   Agent    |   |   Agent    |
   |            |   | (Sandbox)  |   | (Seq/Par/  |
   |            |   |            |   |   Loop)    |
   +------+-----+   +------+-----+   +------+-----+
          |                |                |
          +----------------+----------------+
                           |
                           v
         +--------------------------------------+
         |            Tool Layer                |
         |   MCP  |  Knowledge  |  Approval    |
         +------------------+-------------------+
                            ^
         +------------------+-------------------+
         |         Infrastructure Layer                  |
         |   model (OpenAI+Ollama)  | backend | logger |
         +--------------------------------------+
                            |
                            v
         +--------------------------------------+
         |          A2UI Protocol Layer         |
         |  StreamEvents | RenderHistory        |
         |  EventHandler → SSE / WS / gRPC     |
         +--------------------------------------+

eino-agent-sdk/
├── agent/                统一 Agent 创建入口
│   ├── agent.go          EinoAgent 门面 + 工厂方法
│   ├── options.go        Functional Options 定义
│   ├── chat.go           ChatModel Agent 配置转换
│   ├── deep.go           Deep Agent 配置转换
│   ├── workflow.go       Sequential / Parallel / Loop 配置转换
│   └── runner.go         惰性 Runner（按需初始化）
├── backend/              安全沙箱
│   ├── restricted.go     RestrictedBackend 路径与命令验证
│   └── command_validator.go  两阶段 Shell 命令验证器
├── mcp/                  MCP 工具管理
│   ├── mcp.go            MCPToolLoader 并发加载 + 懒重连客户端
│   ├── manager.go        Manager 单例，全量/单服务/动态注册刷新
│   └── config.go         MCPServerConfig 结构定义
├── model/                模型工厂
│   ├── openai.go         DefaultChatModel + OpenAI 兼容配置
│   └── ollama.go         DefaultOllamaChatModel + Ollama 本地模型配置
├── tool/                 工具集
│   └── cnb_knowledge/     CNB 知识库检索工具
├── a2ui/                 A2UI 协议实现
│   ├── types.go          A2UI v0.8/v0.9 消息类型定义
│   ├── streamer.go       事件流转换核心逻辑
│   ├── handler.go        EventHandler 回调接口
│   ├── writer.go         io.Writer 适配器
│   └── history.go        增强版历史渲染
├── logger/               GoFrame 格式结构化日志
│   └── logger.go         slog Handler 实现
├── docs/                 详细文档
└── go.mod

要求 Go 1.26+：

go get cnb.cool/xqitw/eino-agent-sdk

通用智能体技能，通过 npx skills 安装。

npx skills add https://cnb.cool/xqitw/eino-agent-sdk.git 

npx skills add https://cnb.cool/xqitw/eino-agent-sdk.git --list

将以下内容发送给 CodeBuddy 等智能体即可自动安装：

npx skills add https://cnb.cool/xqitw/eino-agent-sdk.git --skill eino-sdk-skill -a codebuddy -y --copy

ctx := context.Background()

m, _ := model.DefaultChatModel(ctx)

a, _ := agent.NewChat(ctx,
    agent.WithName("my-agent"),
    agent.WithModel(m),
)

events := a.Runner().Query(ctx, "你好")
for {
    event, ok := events.Next()
    if !ok { break }
    if event.Output != nil && event.Output.MessageOutput != nil {
        println(event.Output.MessageOutput.Message.Content)
    }
}

完整示例（Deep Agent + 文件系统 + Shell + MCP）请参阅 快速开始。

模块	说明
agent/	统一 Agent 创建入口，支持 5 种类型，Functional Options 配置
backend/	RestrictedBackend + CommandValidator，安全沙箱
mcp/	MCP 工具管理器，并发加载、自动重连、动态刷新
model/	ChatModel 工厂 — OpenAI 兼容 API + Ollama 本地模型
tool/cnb_knowledge/	CNB 知识库检索工具
a2ui/	A2UI 协议实现，EventHandler 回调接入任意传输层
logger/	GoFrame 格式结构化日志

SDK 本身不强制依赖任何环境变量。CNB_TOKEN 和 CNB_REPO_SLUG 仅在使用 DefaultChatModel 或默认知识库时需要。OLLAMA_BASE_URL 和 OLLAMA_MODEL 仅在使用 DefaultOllamaChatModel 时需要。设置 EINO_LOG_LEVEL=debug 可查看详细日志。

变量	使用方	用途	何时需要
CNB_TOKEN	model、tool/cnb_knowledge	API 认证令牌	使用 DefaultChatModel 或默认知识库时
CNB_REPO_SLUG	model、tool/cnb_knowledge	构建基础 URL	使用 DefaultChatModel 或默认知识库时
OLLAMA_BASE_URL	model	Ollama 服务地址	使用 DefaultOllamaChatModel 时（默认 http://localhost:11434）
OLLAMA_MODEL	model	Ollama 模型名称	使用 DefaultOllamaChatModel 时（默认 qwen3）
EINO_LOG_LEVEL	logger	日志级别	可选，debug 或 info（默认）

• Functional Options 模式 — 所有 Agent 类型共享 Option 接口，通过 New() 或便捷入口创建，扩展新类型只需添加选项函数
• 惰性 Runner — EinoAgent.Runner() 按需初始化，子 Agent 场景无需 Runner
• 两阶段命令验证 — 正则预检拦截危险模式，AST 解析精确提取命令名，防止子 shell、路径遍历、glob 等逃逸
• 符号链接防逃逸 — RestrictedBackend 所有路径检查前先解析符号链接
• 并发 MCP 加载 — errgroup 并发上限 5，工具名自动添加前缀避免冲突
• 自动重连 — lazyReconnectClient 指数退避重试（最多 3 次，基础延迟 500ms，最大延迟 5s）
• 单服务刷新 — RefreshServer 按名称刷新，RefreshServerWithConfig 支持运行时注册新 MCP 服务器
• A2UI 事件流 — EventHandler 回调解耦传输层，一个 callback 即可接入 SSE/WebSocket/gRPC；WriterHandler 兼容 eino 官方 io.Writer 模式；历史回放保留 ToolCall 信息

• 快速开始 — 安装、环境变量、最小与完整示例
• Agent 模块详解 — 类型、配置项、子 Agent 组合
• MCP 工具管理 — 初始化、运行时刷新、自动重连
• 模型配置 — DefaultChatModel 与自定义模型
• Backend 安全沙箱 — RestrictedBackend 与 CommandValidator
• A2UI 协议 — 事件流转换、EventHandler 回调、历史回放、中断恢复
• 工具集 — 中断审批门控、知识库检索

欢迎参与贡献！详细的贡献规范和开发流程请参考 CONTRIBUTING.md。

基于 MIT License 开源。