@blade-ai/agent-sdk

技能简介

@blade-ai/agent-sdk 是一款面向本地 Node.js 进程与服务端的 Session-first TypeScript Agent SDK。它用一套统一 API 同时覆盖多轮会话、流式工具执行、MCP（Model Context Protocol）、子 Agent、Skills（技能）、权限管理、Hooks、沙箱策略、结构化输出和可观测性，适用于构建从简单 CLI 工具到复杂生产级 Agent 服务的一系列场景。框架内置项目脚手架生成器，一行命令即可拉起 local preset（无依赖）、web preset（Browser + AgentServer）或 production preset（PostgreSQL + Worker + Docker + 审批拓扑）的完整项目。

核心能力

• Session-first 架构：统一的多轮会话抽象，基于持久化的 InputSubmission（now / next / later 转向策略），支持中断、取消和待处理输入管理
• 双运行模式（local / server）：local profile 适用于本地 Agent 或 CLI，默认开启文件系统工具、本地存储和上下文发现；server profile 适用于共享多租户服务，显式注入存储和权限管理
• 流式事件体系：17 种类型化事件（轮次、内容、思维、工具、usage、转向、结果、错误），全部可重放，支持 text() / textStream() / on() / stream() 多种消费方式
• 多 Provider 支持：内置 OpenAI、Anthropic、Azure OpenAI、Gemini、DeepSeek 和 OpenAI-compatible API 适配器
• MCP 工具集成：完整支持 MCP 协议，可直接挂载 MCP 服务器作为工具源
• 扩展体系：洋葱式模型/工具 middleware，可打包 middleware、hooks 与工具的声明式插件系统
• 协作能力：前台/后台子 Agent、任务工具，以及项目级 Skills
• 安全模型：有界模型/工具执行、权限模式（readonly/ask）、策略回调、路径检查和可选 OS 沙箱（Docker）集成
• 多运行时支撑：AgentServer + AgentWorker 架构，PostgreSQL 持久化运行时、Docker 隔离执行环境、崩溃安全的本地会话记录
• 内置项目脚手架：create-blade-agent 命令支持 local / web / production 三种预设，一键生成完整可运行项目

工作原理

@blade-ai/agent-sdk 的核心是 createAgent() 入口函数。

第一步：创建 Agent 实例

import { createAgent } from "@blade-ai/agent-sdk";

const agent = await createAgent({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
  filesystem: {
    roots: [process.cwd()],
    cwd: process.cwd(),
  },
});

第二步：发送消息并消费流

const response = await agent.send("读取 package.json，用三个要点总结这个项目");

for await (const chunk of response.textStream()) {
  process.stdout.write(chunk);  // 流式输出
}

await agent.close();

Agent 生命周期

每次 agent.send() 返回一个 AgentResponse，支持多种视图消费同一底层执行：

• text() — 获取完整文本
• textStream() — 消费文本增量
• on(type, listener) — 监听指定类型事件
• stream() — 消费全部类型化事件

执行模式切换

Agent 可通过 profile: "local" | "server" 切换运行模式，或通过 advanced 配置精细化选项。

安装配置

环境要求

• Node.js 22.14.0 及以上
• ESM 项目或支持 ESM 的构建工具

安装命令

npm install @blade-ai/agent-sdk
# 或
yarn add @blade-ai/agent-sdk
# 或
pnpm add @blade-ai/agent-sdk

项目脚手架生成（推荐）

# 本地 Agent（无依赖）：
npm exec --yes --package=@blade-ai/agent-sdk -- create-blade-agent my-agent --preset local --verify

# Web 应用（Browser + AgentServer）：
npm exec --yes --package=@blade-ai/agent-sdk -- create-blade-agent my-agent --preset web

# 生产拓扑（PostgreSQL + Worker + Docker + 审批）：
npm exec --yes --package=@blade-ai/agent-sdk -- create-blade-agent my-agent --preset production --verify

手动配置步骤

1. 安装 SDK：npm install @blade-ai/agent-sdk
2. 创建 agent 实例（传入 model、apiKey，可选 filesystem）
3. 调用 agent.send() 开始对话
4. 消费 response.textStream() 获取流式输出
5. 完成后 agent.close() 清理资源

使用步骤

基础对话

const agent = await createAgent({
  model: "gpt-4o-mini",
  apiKey,
});

const res = await agent.send("帮我写一个快速排序算法");
console.log(await res.text());

自定义工具

import { defineTool } from "@blade-ai/agent-sdk";
import Type from "typebox";

const getWeather = defineTool({
  name: "GetWeather",
  description: "查询城市天气",
  parameters: Type.Object({ city: Type.String() }),
  async execute({ city }) {
    return { weather: `${city}：晴，25°C` };
  },
});

const res = await agent.send("北京天气怎么样？");

权限与 Hooks

const agent = await createAgent({
  model: "gpt-4o-mini",
  apiKey,
  advanced: {
    permission: async (request) =>
      request.kind === "readonly" ? "allow" : "ask",
    hooks: {
      PreToolUse: [async (event) => {
        console.log(event.toolName, event.toolInput);
        return { action: "continue" };
      }],
    },
  },
});

MCP 服务器集成

const agent = await createAgent({
  model: "gpt-4o-mini",
  apiKey,
  mcpServers: [
    { command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] },
  ],
});

适用场景

• 本地 CLI 工具：生成无依赖的本地 Agent，用于自动化脚本、代码审查、文档生成
• Web Agent 应用：Browser 内嵌 Agent 能力，AgentServer 提供真实工具和运行中插入指令
• 生产级 Agent 服务：PostgreSQL 持久化 + Worker 拓扑 + Docker 隔离，适合多租户场景
• 多轮对话产品：Session-first 架构天然适合需要持续上下文的产品内嵌 Agent
• 代码审查与重构：通过 filesystem 能力和 Skills 系统实现项目级代码质量检查
• 团队协作工具：多 Agent 委派 + 审批流程，适合代码审查、数据分析报告生成

适用人群

• Node.js/TypeScript 开发者：需要在项目中集成 Agent 能力
• AI 应用架构师：设计 Agent 产品时需要可组合的 SDK 框架
• 平台工程师：构建企业内部 AI Agent 服务平台
• 独立开发者：快速生成带 Agent 能力的 CLI 或 Web 工具

官方链接

• npm：https://www.npmjs.com/package/@blade-ai/agent-sdk
• GitHub：https://github.com/blade-ai/blade-agent-sdk
• 中文文档：https://github.com/blade-ai/blade-agent-sdk/blob/main/docs/index.md