TL;DR

agentsdk-go 是一个用 Go 实现的 Agent 开发框架，完整移植了 Claude Code 的七大核心能力（Hooks、MCP、Sandbox、Skills、Subagents、Commands、Plugins），并扩展了六层中间件拦截机制。相比 LangGraph 的黑盒架构和 Claude Agent SDK 的资源占用问题，agentsdk-go 提供了更透明的实现、更低的资源消耗和更灵活的扩展能力。核心代码 20,300 行，Agent 主循环仅 189 行，测试覆盖率达 90-93%。

一、agentsdk-go 是什么

核心定位

agentsdk-go 是基于 Claude Code 完整架构设计的 Agent 开发框架，面向生产环境的 CLI、CI/CD 和企业平台部署场景。它不是简单的 LLM 调用封装，而是提供了完整的 Agent 工程能力。

技术指标

  • • 代码规模：约 20,300 行生产代码（不含测试）
  • • 核心复杂度：Agent 主循环 189 行
  • • 测试覆盖率：六大核心模块均达 90-93%（subagents 91.7%，api 91.0%，mcp 90.3%，model 92.2%，sandbox 90.5%，security 90.4%）
  • • 模块化程度：13 个独立包
  • • 外部依赖：anthropic-sdk-go、fsnotify、gopkg.in/yaml.v3、google/uuid、golang.org/x/mod、golang.org/x/net

系统架构

核心层（6 个模块）
  1. 1. pkg/agent：Agent 执行循环，协调模型调用和工具执行
  2. 2. pkg/middleware：六层拦截点，扩展请求/响应生命周期
  3. 3. pkg/model：模型适配器，当前支持 Anthropic Claude
  4. 4. pkg/tool：工具注册和执行，包含内置工具和 MCP 工具支持
  5. 5. pkg/message：基于 LRU 的会话历史管理
  6. 6. pkg/api：统一 API 接口，暴露 SDK 功能
特性层（7 个模块）
  1. 1. pkg/core/hooks：七种生命周期事件的 Hooks 执行器
  2. 2. pkg/mcp：MCP (Model Context Protocol) 客户端，桥接外部工具（stdio/SSE）
  3. 3. pkg/sandbox：沙箱隔离层，控制文件系统和网络访问策略
  4. 4. pkg/runtime/skills：Skills 管理，支持脚本加载和热重载
  5. 5. pkg/runtime/subagents：Subagent 管理，用于多 Agent 编排和调度
  6. 6. pkg/runtime/commands：Commands 解析器，处理斜杠命令路由和参数验证
  7. 7. pkg/plugins：插件系统，具备签名验证和生命周期钩子
中间件拦截点
    
    
    
  用户请求
  ↓
before_agent  ← 请求验证、审计日志
  ↓
Agent 循环
  ↓
before_model  ← Prompt 处理、上下文优化
  ↓
模型调用
  ↓
after_model   ← 结果过滤、内容检查
  ↓
before_tool   ← 工具参数验证
  ↓
工具执行
  ↓
after_tool    ← 结果后处理
  ↓
after_agent   ← 响应格式化、指标收集
  ↓
用户响应

这种六层拦截设计允许开发者在 Agent 执行的关键节点注入自定义逻辑，实现日志记录、性能监控、安全审计等功能。

配置系统

agentsdk-go 使用 .claude/ 目录进行配置，与 Claude Code 完全兼容：

    
    
    
  .claude/
├── settings.json           # 项目配置
├── settings.local.json     # 本地覆盖（gitignored）
├── skills/                 # Skills 定义
├── commands/               # 斜杠命令定义
├── agents/                 # Subagents 定义
└── plugins/                # 插件目录

配置优先级（从高到低）：

  1. 1. 托管策略（/etc/claude-code/managed-settings.json）
  2. 2. 运行时覆盖（CLI/API 提供）
  3. 3. .claude/settings.local.json
  4. 4. .claude/settings.json
  5. 5. 内置默认值

配置示例：

    
    
    
  {
  "permissions": {
    "allow": ["Bash(ls:*)", "Bash(pwd:*)"],
    "deny": ["Read(.env)", "Read(secrets/**)"]
  },
  "env": {
    "MY_VAR": "value"
  },
  "sandbox": {
    "enabled": false
  }
}

二、为什么要自己写 agentsdk-go

LangGraph 的架构问题

LangGraph 虽然功能强大，但存在几个核心痛点：

  1. 1. 黑盒架构：状态图抽象过重，难以追踪 Agent 执行流程，调试困难
  2. 2. 灵活性不足：固定的图结构限制了动态决策和运行时调整
  3. 3. 工程能力缺失：缺少 Sandbox、Hooks、MCP 等生产环境必需的能力
  4. 4. Python 生态绑定：对 Go 生态支持不佳

Claude Agent SDK 的资源瓶颈

Claude Agent SDK 基于 claude -p 实现，每次调用都会在本地启动一个完整的 Claude 实例：

  • • CPU 占用：每个实例独立进程，多任务并发时 CPU 飙升
  • • 内存消耗：每个实例加载完整上下文，内存占用线性增长
  • • 启动延迟：进程冷启动时间影响响应速度

这在 CI/CD 和高并发场景下完全不可接受。

agentsdk-go 的优势

1. 架构透明性

完全遵循 Claude Code 的设计原则，核心 Agent 循环仅 189 行，逻辑清晰：

  • • 请求接收 → 中间件前置处理 → 模型调用 → 工具执行 → 中间件后置处理 → 响应返回
  • • 每个环节都可拦截、观测、调试
2. 资源效率
  • • 单进程模型：所有 Agent 共享一个运行时，无进程启动开销
  • • 会话缓存：基于 LRU 的消息历史管理，避免重复上下文加载
  • • 按需加载：Skills、Plugins、MCP 工具仅在使用时初始化
3. 扩展能力
  • • 中间件系统：六层拦截点覆盖完整生命周期
  • • Sandbox 优化：更细粒度的资源控制（CPU、内存、磁盘、网络）
  • • 自定义工具：简单的 tool.Tool 接口，5 分钟完成集成
4. 生产就绪
  • • 高测试覆盖率：核心模块 90%+ 覆盖，保证代码质量
  • • HTTP API：内置 REST + SSE 服务器，开箱即用
  • • 可观测性：Trace、Metrics、Logs 完整支持

三、如何使用 agentsdk-go 开发 Agent

安装和环境准备

前置要求
  • • Go 1.24.0 或更高版本
  • • Anthropic API Key
安装 SDK
    
    
    
  go get github.com/cexll/agentsdk-go

基础示例：5 分钟创建第一个 Agent

这是来自 examples/01-basic/main.go 的最小示例，展示了 agentsdk-go 的核心用法：

    
    
    
  package main

import (
    "context"
    "fmt"
    "log"

    "github.com/cexll/agentsdk-go/pkg/api"
    "github.com/cexll/agentsdk-go/pkg/middleware"
    modelpkg "github.com/cexll/agentsdk-go/pkg/model"
)

func main() {
    // 创建 Anthropic provider
    provider := &modelpkg.AnthropicProvider{
        ModelName: "claude-sonnet-4-5-20250929",
    }

    // 初始化运行时
    traceMW := middleware.NewTraceMiddleware(".trace")
    rt, err := api.New(context.Background(), api.Options{
        ModelFactory: provider,
        Middleware:   []middleware.Middleware{traceMW},
    })
    if err != nil {
        log.Fatalf("build runtime: %v", err)
    }
    defer rt.Close()

    // 发起同步调用
    resp, err := rt.Run(context.Background(), api.Request{
        Prompt: "你好",
    })
    if err != nil {
        log.Fatalf("run: %v", err)
    }

    if resp.Result != nil {
        fmt.Println(resp.Result.Output)
    }
}

关键点：

  1. 1. 模型初始化：通过 AnthropicProvider 配置模型
  2. 2. 中间件注入：TraceMiddleware 自动记录执行日志到 .trace 目录
  3. 3. 运行时创建：api.New() 初始化完整运行时
  4. 4. 同步调用：rt.Run() 阻塞等待结果

运行示例：

    
    
    
  # 1. 设置环境变量
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# 2. 运行示例
go run ./examples/01-basic

进阶用法：自定义中间件

中间件是 agentsdk-go 的核心扩展机制，允许在六个关键节点注入逻辑：

    
    
    
  loggingMiddleware := middleware.Middleware{
    // 请求前：记录输入和启动时间
    BeforeAgent: func(ctx context.Context, req *middleware.AgentRequest) (*middleware.AgentRequest, error) {
        log.Printf("[REQUEST] %s", req.Input)
        req.Meta["start_time"] = time.Now()
        return req, nil
    },

    // 响应后：计算执行时间
    AfterAgent: func(ctx context.Context, resp *middleware.AgentResponse) (*middleware.AgentResponse, error) {
        duration := time.Since(resp.Meta["start_time"].(time.Time))
        log.Printf("[RESPONSE] %s (elapsed: %v)", resp.Output, duration)
        return resp, nil
    },

    // 模型调用前：优化 Prompt
    BeforeModel: func(ctx context.Context, req *middleware.ModelRequest) (*middleware.ModelRequest, error) {
        // 添加系统提示词
        req.Messages = append([]middleware.Message{
            {Role: "system", Content: "你是一个技术专家"},
        }, req.Messages...)
        return req, nil
    },

    // 工具执行前：参数验证
    BeforeTool: func(ctx context.Context, req *middleware.ToolRequest) (*middleware.ToolRequest, error) {
        log.Printf("[TOOL] %s with params: %v", req.Name, req.Parameters)
        return req, nil
    },
}

// 注入中间件
runtime, err := api.New(ctx, api.Options{
    ProjectRoot:  ".",
    ModelFactory: provider,
    Middleware:   []middleware.Middleware{loggingMiddleware},
})

流式输出：实时获取 Agent 执行进度

对于长时间运行的任务，流式 API 提供实时反馈：

    
    
    
  events := runtime.RunStream(ctx, api.Request{
    Prompt:    "分析代码仓库结构并生成报告",
    SessionID: "analysis",
})

for event := range events {
    switch event.Type {
    case "content_block_delta":
        // 输出文本内容
        fmt.Print(event.Delta.Text)

    case "tool_execution_start":
        // 工具开始执行
        fmt.Printf("\n[工具执行] %s\n", event.ToolName)

    case "tool_execution_stop":
        // 工具执行完成
        fmt.Printf("[工具结果] %s\n", event.Output)
    }
}

自定义工具：扩展 Agent 能力

agentsdk-go 允许注册自定义工具，接口非常简洁（参考 examples/05-custom-tools/main.go）：

    
    
    
  // 定义自定义工具
type EchoTool struct{}

func (t *EchoTool) Name() string {
    return "echo"
}

func (t *EchoTool) Description() string {
    return "返回提供的文本"
}

func (t *EchoTool) Schema() *tool.JSONSchema {
    return &tool.JSONSchema{
        Type: "object",
        Properties: map[string]any{
            "text": map[string]any{
                "type":        "string",
                "description": "要返回的文本",
            },
        },
        Required: []string{"text"},
    }
}

func (t *EchoTool) Execute(ctx context.Context, params map[string]any) (*tool.ToolResult, error) {
    return &tool.ToolResult{
        Output: fmt.Sprint(params["text"]),
    }, nil
}

// 注册工具
rt, err := api.New(ctx, api.Options{
    ProjectRoot:         ".",
    ModelFactory:        provider,
    EnabledBuiltinTools: []string{"bash", "file_read"}, // 选择性启用内置工具
    CustomTools:         []tool.Tool{&EchoTool{}},      // 添加自定义工具
})

工具注册规则：

  • • EnabledBuiltinTools: nil → 启用所有内置工具
  • • EnabledBuiltinTools: []string{} → 禁用所有内置工具
  • • EnabledBuiltinTools: []string{"bash", "file_read"} → 仅启用指定工具（大小写不敏感）
  • • CustomTools → 追加自定义工具

高级特性：完整工程能力

examples/04-advanced 展示了生产环境所需的全部功能：

1. Sandbox 隔离
    
    
    
  opts := api.Options{
    Sandbox: &sandbox.Options{
        Enabled:     true,
        Root:        "/app/workspace",
        AllowedHosts: []string{"api.example.com"},
        CPULimit:    50.0,  // CPU 使用率限制 50%
        MemLimit:    512,   // 内存限制 512MB
        DiskLimit:   1024,  // 磁盘限制 1GB
    },
}
2. MCP 工具集成
    
    
    
  opts := api.Options{
    MCPServers: []mcp.ServerConfig{
        {
            Name:    "time-server",
            Command: "uvx",
            Args:    []string{"mcp-server-time"},
        },
    },
}
3. Skills 和 Subagents
    
    
    
  opts := api.Options{
    Skills: []skills.Skill{
        {Name: "code-review", Path: ".claude/skills/code-review"},
    },
    Subagents: []subagents.Config{
        {Name: "analyzer", Prompt: "专注于代码分析"},
    },
}

五层示例路径

agentsdk-go 提供渐进式学习路径：

  1. 1. 01-basic：最小化的单次请求/响应
  2. 2. 02-cli：交互式 REPL，支持会话历史
  3. 3. 03-http：REST + SSE 服务器（监听 :8080）
  4. 4. 04-advanced：完整管道（中间件、Hooks、MCP、Sandbox、Skills、Subagents）
  5. 5. 05-custom-tools：选择性内置工具 + 自定义工具注册

总结

agentsdk-go 不是简单的 API 封装，而是完整的 Agent 工程框架：

  • • 架构透明：189 行核心循环，逻辑清晰可追溯
  • • 资源高效：单进程模型，无冷启动开销
  • • 扩展灵活：六层中间件 + 自定义工具 + MCP 集成
  • • 生产就绪：90%+ 测试覆盖，HTTP API 开箱即用

如果你在使用 LangGraph 时感到束缚，或因 Claude Agent SDK 的资源占用而困扰，不妨试试 agentsdk-go——一个真正为工程师设计的 Agent 开发框架。

参考资源

  • • GitHub 仓库：https://github.com/cexll/agentsdk-go
  • • 示例代码：https://github.com/cexll/agentsdk-go/tree/main/examples
  • • Claude Code 文档：https://docs.anthropic.com/en/docs/agents
# 经验分享
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

亲测好用8个AI论文工具，本科生轻松搞定毕业论文！

avatar 2048 AI社区

告别熬夜做 PPT！这 8 个 AI 工具，输入文字自动生成排版 + 配图

制作 PPT 是许多人学习与工作中绕不开的任务 —— 无论是大学生筹备答辩演示，还是职场人打磨工作汇报，不少人都会陷入相似的困境：面对空白页面无从下手，耗费大量时间在模板筛选、排版调整与数据可视化上，最终的成品却往往难以达到专业水准。随着 AI 技术的发展，AI 辅助制作 PPT 的工具逐渐成熟，能够有效帮助使用者从繁琐的重复性工作中解脱，将更多精力聚焦于内容本身的打磨。

avatar 2048 AI社区
cover

5 款 AI 写论文哪个好？实测揭秘：这款「学术全能王」竟无短板！

avatar 2048 AI社区