面向 Node.js 与 TypeScript 的 Session-first Agent SDK。它把多轮会话、工具执行、MCP、子 Agent、Skills、权限控制、Hooks、沙箱和结构化输出统一到一套 API 中，适合构建 CLI 助手、IDE 插件、自动化工作流和对话式开发工具。
根目录 README 只保留仓库概览和最小上手。更详细的配置、API 和使用模式已经放在 docs/ 中，并通过 VitePress 对外发布，避免首页和文档站维护两套重复内容。
- Session-first：
createSession()、resumeSession()、forkSession()、prompt() - 流式 Agent 交互：
send()+stream()，支持内容、thinking、tool use、tool result、usage、result 等 15 种事件类型 - 多模型支持：
openai、anthropic、azure-openai、gemini、deepseek、openai-compatible - 工具系统：内置 23 个标准工具，支持
defineTool()、createTool()、MCP 协议工具与 MCP 资源工具 - 工具目录：
ToolCatalog统一管理内置、自定义、MCP 工具的来源追踪与信任分级 - MCP：支持
stdio、sse、http传输，也支持进程内createSdkMcpServer() - 协作能力：子 Agent（前台/后台）、
Task/TaskOutput/TaskStop工具，以及用户级和项目级 Skills - Memory 系统：
MemoryManager+FileSystemMemoryStore，可选的MemoryRead/MemoryWrite工具 - 安全与治理：
permissionMode、canUseTool、permissionHandler、Hooks、沙箱配置可组合使用 - Observability：可选 trace 记录，把 stream events、tool calls、usage、hooks 汇总为可调试的执行轨迹
- 工程能力：运行时 Context、结构化输出、日志接口、会话持久化与分叉、自动上下文压缩、上下文溢出恢复、Token 预算
npm install @blade-ai/agent-sdk
# 或
pnpm add @blade-ai/agent-sdk已发布包面向 npm 分发；这个仓库本身使用 pnpm 进行依赖安装、构建、测试、发布和文档开发。
import { createSession } from '@blade-ai/agent-sdk';
const session = await createSession({
provider: { type: 'openai', apiKey: process.env.OPENAI_API_KEY! },
model: 'gpt-4o-mini',
temperature: 0.2,
maxOutputTokens: 4096,
});
await session.send('分析当前项目的目录结构，并总结关键模块职责');
for await (const event of session.stream()) {
if (event.type === 'content') {
process.stdout.write(event.delta);
}
}
session.close();如果你只需要一次性调用，可以直接使用 prompt()：
import { prompt } from '@blade-ai/agent-sdk';
const result = await prompt('总结这个仓库的公开 API', {
provider: { type: 'openai', apiKey: process.env.OPENAI_API_KEY! },
model: 'gpt-4o-mini',
});
console.log(result.result);
console.log(result.toolCalls);
console.log(result.usage);createSession() 可以直接配置常见模型采样和预算参数，这些字段会传入当前会话的默认 ModelConfig：
const session = await createSession({
provider: { type: 'openai', apiKey: process.env.OPENAI_API_KEY! },
model: 'gpt-5',
temperature: 0.2,
maxOutputTokens: 4096,
maxContextTokens: 128000,
providerOptions: {
openai: { reasoningEffort: 'low' },
},
thinkingEnabled: true,
thinkingBudget: 1024,
});SDK 保持 session-first 的默认体验，root 入口面向 Node server 和 CLI 场景：
import { createSession } from '@blade-ai/agent-sdk';需要更明确的运行时边界时，可以使用 subpath exports：
import { createSession } from '@blade-ai/agent-sdk/server';
import { ToolKind } from '@blade-ai/agent-sdk/core';
import { defineTool } from '@blade-ai/agent-sdk/tools';
import { getBuiltinTools } from '@blade-ai/agent-sdk/local';@blade-ai/agent-sdk/core 只导出 browser-safe 的类型、协议和常量。浏览器环境误导入 root、server、session 或 local 入口时，会解析到 browser stub，并在调用 server-only API 时抛出清晰错误。
当需要调试 Agent 行为时，可以开启 observability。SDK 会为每次 send() + stream() 生成一条 trace，串起 turn、内容流、工具调用、usage、hooks 和最终结果。
默认情况下，trace 只记录结构化摘要，不保存完整 prompt、模型输出、工具入参或工具结果，避免把敏感内容写入调试数据。只有显式设置 capturePayloads: true 时才会记录完整 payload。
import { createSession } from '@blade-ai/agent-sdk';
const session = await createSession({
provider: { type: 'openai', apiKey: process.env.OPENAI_API_KEY! },
model: 'gpt-4o-mini',
observability: {
enabled: true,
// capturePayloads: true, // 调试时才开启，可能包含敏感内容
sink: async (trace) => {
await sendTraceToYourPlatform(trace);
},
},
});
await session.send('分析当前项目的测试覆盖');
for await (const event of session.stream()) {
if (event.type === 'content') process.stdout.write(event.delta);
}
console.log(session.getLastTrace());- 需要一个可持久化、可恢复、可分叉的 Agent Session 层
- 需要把文件、搜索、Shell、Web、MCP 等能力统一暴露给模型
- 需要在本地开发环境里组合权限控制和沙箱
- 需要用自定义工具、MCP server、子 Agent 或 Skills 扩展能力
- 需要结构化输出、日志、trace 和运行时 Context 来接入现有应用
README 只保留概览。详细用法请直接看文档：
pnpm install
pnpm run build
pnpm test
pnpm run type-check
pnpm run lint
pnpm run docs:dev更多贡献约定见 CONTRIBUTING.md。