bamboo-agent

README

Bamboo Agent

基于 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-agent

基本使用

package 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)
}

Functional Options

ag := agent.NewAgentWithOptions(bmClient,
    agent.WithSystemPrompt("你是代码助手"),
    agent.WithMaxIterations(20),
    agent.WithMaxTokens(8192),
    agent.WithTemperature(0.7),
    agent.WithTools(&builtin.FileReadTool{}, &builtin.ShellTool{}),
)

Hook 系统

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
}

Guardrails

inputGuard := func(ctx context.Context, input json.RawMessage) error {
    // 验证输入...
    return nil
}
wrappedTool := tool.WithGuardrails([]tool.InputGuardrail{inputGuard}, nil)(myTool)

Agent-as-Tool

subAgent := agent.NewAgentWithOptions(client, agent.WithSystemPrompt("子 Agent"))
agentTool := agent.NewAgentTool("ask_sub", "咨询子Agent", subAgent)
parentAgent.AddTool(agentTool)

Thinking & Caching

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{})

多 Agent 编排

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)

MCP 集成

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）

设计原则

1. 接口最小化 — 每个核心组件定义最小接口，扩展通过组合实现
2. 值类型传递 — 消息和事件使用值类型，通过 channel 安全传递
3. 零外部耦合 — 内置工具不依赖具体框架，可独立使用
4. Functional Options — 配置通过 Options 模式注入
5. BM-SDK 对接 — 所有 AI 交互通过 BambooClient 进行
6. 自动压缩 — 长对话自动压缩上下文，开发者无需手动管理
7. 工具并发 — 多工具调用时自动并行执行，最大化吞吐量
8. Hook 零开销 — 无 Hook 注册时不产生任何调用开销
9. 装饰器模式 — Guardrails 通过包装而非修改接口实现扩展
10. 智能停止 — 根据 FinishReason 自动决定停止/重试/继续

技术栈

• 语言: Go 1.25
• 依赖: BambooMessages SDK
• 并发: goroutine + sync.WaitGroup + channel

License

MIT