[Brave]

Brave

一、项目简介

Open Agent SDK 是一个开源的 AI Agent 开发框架，灵感来源于 Anthropic 官方的 @anthropic-ai/claude-agent-sdk。它能让开发者构建自主运行的 AI Agent，这些 Agent 可以理解代码库、编辑文件、执行命令、搜索网页，并完成复杂的多步骤工作流。

与官方 SDK 最大的区别在于架构设计。官方的 @anthropic-ai/claude-agent-sdk 需要依赖本地 Claude Code CLI 进程，其调用链为：

你的代码 → SDK → 启动 cli.js 子进程 → stdin/stdout JSON → Anthropic API

而 Open Agent SDK 将整个 Agent 循环都运行在进程内（in-process），调用链大幅简化为：

你的代码 → SDK → QueryEngine → Anthropic API（直接调用）

这意味着你可以将它部署到任何环境——云服务器、Serverless 函数、Docker 容器、CI/CD 流水线，不再受本地 CLI 依赖的束缚。

二、快速上手

安装

npm install @shipany/open-agent-sdk

配置 API Key

可以直接使用 Anthropic 官方的 API Key：

export ANTHROPIC_API_KEY=your-api-key

也支持第三方 Provider（如 OpenRouter）：

export ANTHROPIC_BASE_URL=https://openrouter.ai/api
export ANTHROPIC_API_KEY=your-openrouter-api-key
export ANTHROPIC_MODEL=anthropic/claude-sonnet-4-6

最简示例：阻塞式调用

import { createAgent } from '@shipany/open-agent-sdk'

const agent = createAgent({ model: 'claude-sonnet-4-6' })
const result = await agent.prompt('读取 package.json 并告诉我项目名称')

console.log(result.text)
console.log(`Tokens: ${result.usage.input_tokens + result.usage.output_tokens}`)

仅需三行核心代码，你就拥有了一个可以读取文件、理解内容并回答问题的 AI Agent。

三、核心功能详解

3.1 多种调用方式

Open Agent SDK 提供了灵活的 API 设计，满足不同使用场景：

query() 流式调用——兼容官方 SDK 的顶层入口，返回 AsyncGenerator<SDKMessage>，适合需要实时展示中间过程的场景：

import { query } from '@shipany/open-agent-sdk'

for await (const message of query({
  prompt: '找到并修复 auth.py 中的 Bug',
  options: {
    allowedTools: ['Read', 'Edit', 'Bash'],
    permissionMode: 'acceptEdits',
  },
})) {
  if (message.type === 'assistant' && message.message?.content) {
    for (const block of message.message.content) {
      if ('text' in block) console.log(block.text)
      else if ('name' in block) console.log(`Tool: ${block.name}`)
    }
  }
}

createAgent() + prompt() 阻塞式调用——适合简单的一问一答场景，代码更简洁。

createAgent() + query() 流式调用——结合 Agent 会话管理和流式输出的优势。

3.2 多轮会话

Agent 会自动维护上下文，支持多轮对话：

const agent = createAgent({
  model: 'claude-sonnet-4-6',
  systemPrompt: '你是一位资深软件工程师，请简洁回答。',
})

const r1 = await agent.prompt('阅读主入口文件并解释架构')
console.log(r1.text)

// 第 1 轮的完整上下文会自动保留
const r2 = await agent.prompt('现在重构错误处理部分')
console.log(r2.text)

通过 agent.getMessages() 可以获取完整的对话历史，agent.clear() 则可以重置会话。

3.3 丰富的内置工具（26 个）

Open Agent SDK 内置了与 Claude Code 完全相同的 26 个工具，涵盖文件操作、代码搜索、Web 访问、多 Agent 协作等各个方面：

类别	工具	说明
文件操作	Read, Write, Edit	读取（支持图片、PDF）、创建、精确替换
代码搜索	Glob, Grep	文件模式匹配、正则搜索（基于 ripgrep）
命令执行	Bash	执行 Shell 命令
Web 访问	WebFetch, WebSearch	获取网页内容、搜索互联网
Agent 协作	Agent, SendMessage, TeamCreate/Delete	子 Agent、消息传递、团队管理
任务管理	TaskCreate/Update/List/Get/Stop/Output	完整的任务生命周期管理
其他	NotebookEdit, AskUserQuestion, TodoWrite 等	Jupyter 编辑、用户交互、待办事项等

你可以通过 allowedTools 来控制 Agent 可以使用的工具白名单，例如创建一个只读 Agent：

for await (const message of query({
  prompt: '审查这段代码的最佳实践',
  options: {
    allowedTools: ['Read', 'Glob', 'Grep'], // 只允许读取类工具
  },
})) {
  // ...
}

3.4 自定义工具

除了内置工具，你还可以轻松定义自己的工具：

const weatherTool = {
  name: 'GetWeather',
  description: '获取城市天气',
  inputJSONSchema: {
    type: 'object',
    properties: { city: { type: 'string' } },
    required: ['city'],
  },
  get inputSchema() {
    return { safeParse: (v) => ({ success: true, data: v }) }
  },
  async prompt() { return this.description },
  async call(input) {
    return { data: `${input.city}的天气：22°C，晴` }
  },
  userFacingName: () => 'GetWeather',
  isReadOnly: () => true,
  isConcurrencySafe: () => true,
  mapToolResultToToolResultBlockParam: (data, id) => ({
    type: 'tool_result', tool_use_id: id, content: data,
  }),
}

const agent = createAgent({
  tools: [...getAllBaseTools(), weatherTool],
})

3.5 MCP Server 集成

Open Agent SDK 完整支持 MCP（Model Context Protocol），包括 stdio、SSE、HTTP 三种传输方式：

const agent = createAgent({
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
    },
    playwright: {
      command: 'npx',
      args: ['@playwright/mcp@latest'],
    },
  },
})

const result = await agent.prompt('列出 /tmp 目录下的文件')

这让你可以轻松接入社区中丰富的 MCP 工具生态。

3.6 子 Agent（Subagents）

对于复杂任务，可以定义多个子 Agent 协同完成工作：

for await (const message of query({
  prompt: '使用 code-reviewer Agent 审查这个代码库',
  options: {
    allowedTools: ['Read', 'Glob', 'Grep', 'Agent'],
    agents: {
      'code-reviewer': {
        description: '专业代码审查员，专注于代码质量和安全性。',
        prompt: '分析代码质量并提出改进建议。',
        tools: ['Read', 'Glob', 'Grep'],
      },
    },
  },
})) {
  // 处理消息...
}

四、引擎内核解析

Open Agent SDK 并非一个简化版的重新实现——它包含了完整的 Claude Code 引擎（2000+ 源文件）。以下是其核心组件：

系统提示词构建：完整的 Prompt 构建逻辑，支持静态/动态边界缓存（boundary caching），最大化利用 Anthropic 的 prompt caching 能力，降低 Token 消耗。

四层权限系统：规则匹配 → 低风险跳过 → 白名单 → AI 分类器 + 熔断机制。这套精密的权限管道确保了 Agent 操作的安全性，同时保持灵活性。通过 permissionMode 可以选择不同级别，如 bypassPermissions（绕过所有权限检查，适合受控环境）、acceptEdits（自动接受编辑操作）、plan（计划审批模式）等。

记忆系统：支持 4 种记忆类型（用户记忆、反馈记忆、项目记忆、参考记忆），并内置 autoDream 后台记忆整理器，让 Agent 能够在长时间工作中保持上下文连贯性。

上下文压缩：9 段结构化提取策略（autocompact、microcompact、snip compact），在上下文窗口接近限制时智能压缩对话历史，保留最关键的信息。

多 Agent 协作：支持 Leader/Teammate 团队模式、Git worktree 隔离、权限冒泡、异步邮箱通信等高级特性。

工具执行策略：只读工具支持并发批量执行，写入类工具则串行执行，在性能和安全性之间取得平衡。

API 客户端：流式传输、指数退避重试、备选模型回退、Prompt 缓存等企业级特性一应俱全。

五、与官方 SDK 的对比

特性	官方 SDK	Open Agent SDK
架构	启动本地 CLI 子进程	进程内 Agent 循环
云部署	需安装 CLI	任意环境可用
Serverless	不支持	完全支持
Docker	需在镜像中包含 CLI	仅需 npm install
自定义工具	通过 MCP	原生函数工具 + MCP
流式输出	通过子进程 stdio	直接 API 流式传输
系统提示词/权限/记忆/压缩/多Agent/MCP	完整引擎	完整引擎（相同代码）

核心差异在于部署灵活性。官方 SDK 的子进程架构使其更适合本地开发场景，而 Open Agent SDK 的进程内架构使其天然适合云端和容器化部署。

六、配置参考

Open Agent SDK 提供了丰富的配置选项：

选项	类型	默认值	说明
model	string	claude-sonnet-4-6	Claude 模型 ID
apiKey	string	环境变量	API Key
baseURL	string	Anthropic API	API 地址（第三方 Provider）
cwd	string	当前目录	工具工作目录
systemPrompt	string	—	自定义系统提示词
tools	Tool[]	全部内置工具	可用工具列表
allowedTools	string[]	—	工具白名单
permissionMode	string	bypassPermissions	权限模式
maxTurns	number	100	最大 Agent 轮次
maxBudgetUsd	number	—	最大花费（美元）
mcpServers	object	—	MCP 服务器配置
agents	object	—	子 Agent 定义
hooks	object	—	生命周期钩子
thinking	object	—	扩展思考配置
canUseTool	function	—	自定义权限回调

七、适用场景

基于以上特性，Open Agent SDK 特别适合以下场景：

自动化代码审查：在 CI/CD 流水线中部署 Agent，自动审查 Pull Request，检测潜在问题。通过只赋予只读工具权限，确保审查 Agent 不会修改代码。

智能运维助手：部署在云服务器或 Docker 容器中，结合 Bash 工具和自定义工具，实现服务器状态监控、日志分析、故障诊断等自动化运维任务。

Serverless AI 工作流：在 AWS Lambda、Vercel Functions 等 Serverless 平台上运行，按需处理复杂的 AI 任务，无需维护长期运行的服务器。

多 Agent 协作系统：利用子 Agent 和团队功能，构建多 Agent 协作系统，如「架构师 Agent + 编码 Agent + 测试 Agent」的组合，处理大型项目任务。

集成 MCP 工具生态：通过 MCP 集成 Playwright（浏览器自动化）、数据库访问、文件系统操作等各种外部工具，扩展 Agent 能力边界。

八、总结

Open Agent SDK 将 Claude Code 的完整引擎能力（2000+ 源文件）从本地 CLI 的束缚中解放出来，以进程内运行的方式使其能够部署到任何 Node.js 可运行的环境中。它保留了官方 SDK 的全部核心能力——四层权限系统、记忆系统、上下文压缩、多 Agent 协作、MCP 支持——同时提供了更简洁的 API、更灵活的部署方式，以及原生自定义工具支持。

无论你是想在 Serverless 函数中运行 AI Agent，还是在 Docker 容器中部署自动化工作流，亦或是构建复杂的多 Agent 协作系统，Open Agent SDK 都值得一试。

项目安装：npm install @shipany/open-agent-sdk