基于 BambooMessages SDK 的 Go 语言 AI Agent 框架。
为 Go 开发者提供构建 AI Agent 应用的核心能力：工具调用、自我迭代、多 Agent 协作和 MCP 集成。
- ReAct 循环 — 内置 Reason-Act 迭代策略，支持自定义 LoopStrategy
- 并发工具执行 — AI 返回多个 tool_use 时，自动 goroutine 并行执行
- 上下文压缩 — 长对话自动压缩，避免超出模型 token 限制
- 多 Agent 编排 — 依赖图分析，独立任务并行，依赖任务串行
- MCP Client — JSON-RPC 2.0 over HTTP，自动发现并桥接外部工具
- Functional Options — 灵活的配置模式
- 内置工具 — 文件读写/搜索、Shell 执行、HTTP 请求、代码执行
- Hook 系统 — 6 核心事件钩子（preToolUse/postToolUse/preCompact/postCompact/preIteration/postIteration），支持拦截和变换
- Guardrails 装饰器 — 输入/输出护栏，通过 ToolWrapper 模式包装任意工具
- Agent-as-Tool — 将 Agent 包装为 Tool，支持嵌套调用（最大深度 3 层）
- Handoff 机制 — LLM 驱动的 Agent 间转移，内置循环检测（最大跳转 5 次）
- Decider 决策钩子 — Agent 执行完成后的最终决策（DiscardOutput/Revise）
- Thinking/Reasoning — 支持 Anthropic Extended Thinking（none/low/medium/high）
- Prompt Caching — 支持 Anthropic prompt caching 和 OpenAI prompt cache routing
- stopReason 智能处理 — 自动处理 max_tokens 重试、end_turn/stop_sequence 停止
- 权限控制 — allowedTools/disallowedTools 白名单/黑名单过滤
- 消息裁剪 — MessageTruncator + PipelineCompressor 多级压缩管道
graph TB
subgraph Orchestrator["Orchestrator 编排层"]
direction LR
Task["Task"]
Channel["Channel"]
Builder["AgentBuilder"]
DepGraph["Dep Graph"]
end
subgraph AgentCore["Agent Core 核心层"]
direction LR
Agent["Agent"]
Session["Session"]
ReActLoop["ReActLoop"]
Compressor["Compressor"]
Options["Options"]
end
subgraph ToolSystem["Tool System 工具层"]
direction LR
Registry["Registry"]
Executor["Executor"]
Adapter["Adapter"]
Builtins["Builtins"]
end
subgraph MCP["MCP 扩展层"]
direction LR
Client["Client"]
Bridge["Bridge"]
Config["Config"]
end
Orchestrator --> AgentCore
AgentCore --> ToolSystem
ToolSystem --> MCP
AgentCore --> MCP
BambooClient["BambooClient<br/>(BM-SDK)"]
AgentCore -.-> BambooClient
核心数据流：
sequenceDiagram
participant User
participant Agent
participant Loop as ReActLoop
participant Client as BambooClient
participant Executor as ToolExecutor
User->>Agent: Run(input)
Agent->>Loop: Execute(input)
loop 每次迭代
Loop->>Loop: 检查上下文长度
Loop->>Client: Chat() 流式请求
Client-->>Loop: StreamEvents
alt 返回 tool_use
Loop->>Executor: ExecuteAll() 并发执行
Executor-->>Loop: ToolResults
Loop->>Loop: 追加结果到 Session
else 返回 end_turn
Loop-->>Agent: AgentResult
end
end
Agent-->>User: 最终结果
go get github.com/bamboo-services/bamboo-agentpackage main
import (
"context"
"fmt"
"github.com/bamboo-services/bamboo-agent/agent"
"github.com/bamboo-services/bamboo-agent/orchestrator"
"github.com/bamboo-services/bamboo-agent/tool/builtin"
bamboo "github.com/bamboo-services/bamboo-messages/bamboo"
)
func main() {
ctx := context.Background()
// 1. 创建 BM-SDK 客户端（需配合 bamboo-messages 使用）
var bmClient bamboo.BambooClient // = bamboo.NewClient(provider)
// 2. 使用 Builder 构建 Agent
ag := orchestrator.NewAgentBuilder().
WithClient(bmClient).
WithSystemPrompt("你是一个有帮助的助手").
WithConfig(agent.AgentConfig{
MaxTokens: 4096,
MaxIterations: 10,
MaxConcurrentTools: 10,
}).
WithTools(
&builtin.FileReadTool{},
&builtin.ShellTool{},
&builtin.HTTPTool{},
).
Build()
// 3. 运行 Agent
result, err := ag.Run(ctx, "帮我读取 config.json 并分析内容")
if err != nil {
panic(err)
}
fmt.Println(result.Content)
}ag := agent.NewAgentWithOptions(bmClient,
agent.WithSystemPrompt("你是代码助手"),
agent.WithMaxIterations(20),
agent.WithMaxTokens(8192),
agent.WithTemperature(0.7),
agent.WithTools(&builtin.FileReadTool{}, &builtin.ShellTool{}),
)ag := agent.NewAgentWithOptions(client,
agent.WithHooks(&logHook{}), // 注册 Hook
)
type logHook struct{}
func (h *logHook) Event() agent.HookEvent { return agent.HookPreToolUse }
func (h *logHook) Execute(ctx context.Context, hctx agent.HookContext) (*agent.HookResult, error) {
log.Printf("Tool %s executing...", hctx.ToolName)
return &agent.HookResult{Action: agent.HookActionContinue}, nil
}inputGuard := func(ctx context.Context, input json.RawMessage) error {
// 验证输入...
return nil
}
wrappedTool := tool.WithGuardrails([]tool.InputGuardrail{inputGuard}, nil)(myTool)subAgent := agent.NewAgentWithOptions(client, agent.WithSystemPrompt("子 Agent"))
agentTool := agent.NewAgentTool("ask_sub", "咨询子Agent", subAgent)
parentAgent.AddTool(agentTool)ag := agent.NewAgentWithOptions(client,
agent.WithThinkingConfig("high"), // 启用深度思考
agent.WithSystemCacheControl("5m"), // 缓存 system prompt
agent.WithAllowedTools("file_read"), // 只允许特定工具
)type MyTool struct{}
func (t *MyTool) Info() tool.ToolInfo {
return tool.ToolInfo{
Name: "my_tool",
Description: "我的自定义工具",
Parameters: tool.InputSchema{
Type: "object",
Properties: map[string]tool.PropertyDef{
"query": {Type: "string", Description: "搜索关键词"},
},
Required: []string{"query"},
},
}
}
func (t *MyTool) Execute(ctx context.Context, input json.RawMessage) (tool.ToolResult, error) {
return tool.ToolResult{Content: "结果"}, nil
}
agent.AddTool(&MyTool{})orch := orchestrator.NewOrchestrator()
orch.RegisterAgent("researcher", researchAgent)
orch.RegisterAgent("writer", writerAgent)
tasks := []orchestrator.Task{
{ID: "research", Description: "调研主题", Agent: researchAgent, Input: "AI Agent 框架现状"},
{ID: "write", Description: "撰写报告", Agent: writerAgent, Input: "根据调研写报告", DependsOn: []string{"research"}},
}
results, err := orch.Execute(ctx, tasks)mcpClient := mcp.NewClient(mcp.DefaultConfig("http://localhost:8080"))
mcpClient.Connect(ctx)
bridge := mcp.NewBridge(mcpClient)
mcpTools, _ := bridge.DiscoverAndConvert(ctx)
ag := orchestrator.NewAgentBuilder().
WithClient(bmClient).
WithTools(mcpTools...).
Build()agent/ # Agent 核心层
agent.go # Agent 接口 + agentCore 实现
config.go # AgentConfig 配置
option.go # Functional Options
session.go # 内存会话管理
loop.go # LoopStrategy + ReActLoop
event.go # AgentEvent 事件类型
result.go # AgentResult + ToolCallRecord
compressor.go # ContextCompressor + SummaryCompressor
hook.go # Hook 系统
decider.go # Decider 决策钩子
agent_tool.go # Agent-as-Tool
handoff.go # Handoff 机制
tool/ # 工具层
tool.go # Tool 接口 + ToolInfo + ToolResult
schema.go # InputSchema + PropertyDef
registry.go # Registry 工具注册表
executor.go # ToolExecutor 并发执行器
adapter.go # BambooAdapter (Tool → bamboo.Tool)
guardrails.go # Guardrails 装饰器
builtin/ # 内置工具
file.go # FileReadTool / FileWriteTool / FileSearchTool
shell.go # ShellTool
http.go # HTTPTool
code.go # CodeExecTool
orchestrator/ # 编排层
orchestrator.go # Orchestrator 多 Agent 编排
builder.go # AgentBuilder 构建器
task.go # Task + TaskStatus
channel.go # Channel + AgentMessage
mcp/ # 扩展层
config.go # Config + MCPToolInfo + MCPToolResult
client.go # Client (JSON-RPC 2.0)
bridge.go # Bridge + mcpToolAdapter
| 工具 | 名称 | 功能 |
|---|---|---|
FileReadTool |
file_read |
读取文件内容 |
FileWriteTool |
file_write |
写入文件 |
FileSearchTool |
file_search |
搜索文件内容（返回匹配行） |
ShellTool |
shell |
执行 Shell 命令（支持超时） |
HTTPTool |
http_request |
HTTP GET/POST/PUT/DELETE 请求 |
CodeExecTool |
code_exec |
执行代码片段（Go / Python） |
- 接口最小化 — 每个核心组件定义最小接口，扩展通过组合实现
- 值类型传递 — 消息和事件使用值类型，通过 channel 安全传递
- 零外部耦合 — 内置工具不依赖具体框架，可独立使用
- Functional Options — 配置通过 Options 模式注入
- BM-SDK 对接 — 所有 AI 交互通过 BambooClient 进行
- 自动压缩 — 长对话自动压缩上下文，开发者无需手动管理
- 工具并发 — 多工具调用时自动并行执行，最大化吞吐量
- Hook 零开销 — 无 Hook 注册时不产生任何调用开销
- 装饰器模式 — Guardrails 通过包装而非修改接口实现扩展
- 智能停止 — 根据 FinishReason 自动决定停止/重试/继续
- 语言: Go 1.25
- 依赖: BambooMessages SDK
- 并发: goroutine + sync.WaitGroup + channel