OpenAgentKernel（官方 SDK）

@cloudbase/open-agent-kernel（OAK）是 CloudBase 官方的服务端 Agent SDK，Apache-2.0 开源。它内置了 Agent 开发中重复度最高的基础设施——会话持久化、多轮上下文、MCP 工具接入、人工审批（HITL）、用户长期记忆、沙箱执行——让你只写业务逻辑。

快速开始

前置条件：Node.js 20.19+、一个云开发环境的 envId、环境的服务端 API Key（获取地址）。

npm install @cloudbase/open-agent-kernel

import { createAgent } from "@cloudbase/open-agent-kernel";

process.env.CLOUDBASE_APIKEY = "your-cloudbase-api-key";

const agent = createAgent({
  envId: "your-env-id",
  model: "deepseek-v4-pro",
  systemPrompt: "你是一个智能助手，请帮我回答用户的问题",
});

const session = await agent.startSession({ userId: "user-1" });

for await (const msg of session.send("一句话解释：什么是 Serverless？")) {
  const update = msg.params?.update;
  if (update?.sessionUpdate === "agent_message_chunk") {
    process.stdout.write(update.content.text);
  }
}
// 本轮回答结束后循环自动退出

模型字符串写法默认走 CloudBase AI 网关，用 CLOUDBASE_APIKEY 鉴权；也可以传 { id, apiKey, apiBaseUrl } 接入自带 endpoint 的模型。模型需先在控制台开通，未开通会返回 403 AI_MODEL_NOT_SUPPORTED（错误码说明）。

在控制台创建

打开 CloudBase 控制台的 Agent 板块，新建 Agent 时选择官方 cloudbase-agent 模板，得到的就是一个 OpenAgentKernel 项目：会话持久化、MCP 工具、人工审批开箱即用，创建完成即可在「接入 & 调试」页直接对话。

需要深度定制时，在「本地开发」页按指引操作：

tcb fn code download   # 把代码拉到本地
# 修改代码……
tcb fn deploy          # 部署回云端

控制台负责托管、日志和调试入口，OpenAgentKernel 负责运行时。

核心配置

createAgent(config) 的常用字段：

字段	必填	说明
`envId`	是	云开发环境 ID，模型网关、数据库、存储、沙箱都以它为锚点
`model`	是	模型 ID（走 CloudBase AI 网关）或 `{ id, apiKey, apiBaseUrl }` 完整配置
`systemPrompt`	否	系统提示词（Agent 的人设与行为约束）
`stream`	否	是否流式增量输出，默认 `true`。注意：若部署形态在网关层缓冲整个响应，前端仍要等整轮结束才收到，与本开关无关
`mcpServers`	否	MCP server 配置，支持进程内 / 本地 stdio / 远程 HTTP 等形态
`permissions`	否	工具审批（HITL）：`requireApproval` 支持 `'*'`、工具名数组或函数
`session`	否	会话持久化，默认落云开发数据库
`storage`	否	多模态附件存储，默认落云开发云存储
`sandbox`	否	远程沙箱（当前内测中，如有需求请联系我们）
`userMemory`	否	用户长期记忆，同步到云开发云存储、跨会话生效
`credentials`	视场景	腾讯云 SecretId/SecretKey；仅有 `CLOUDBASE_APIKEY` 时会话与审批也能持久化，工作区文件同步、多模态附件上传等需要它

完整字段与默认值见 GitHub README 的「完整参数说明」。

配置 MCP 工具

const agent = createAgent({
  envId,
  model: "deepseek-v4-pro",
  systemPrompt: "你是一个智能助手",
  mcpServers: {
    // 远程 HTTP MCP
    remote: {
      type: "http",
      url: "https://example.com/mcp/v1",
      headers: { Authorization: "Bearer xxx" },
    },
    // 本地 stdio MCP
    stdio: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-everything"],
    },
  },
});

工具名规则为 mcp__{serverName}__{toolName}。进程内自定义工具的写法见 README「MCP 工具扩展」。

工具审批（HITL）

const agent = createAgent({
  envId,
  model: "deepseek-v4-pro",
  permissions: {
    requireApproval: ["database_delete", "reset_password"],
  },
});

命中的工具调用会暂停，事件流中发出 session/request_permission 请求帧；业务层展示确认交互后调用 session.respondApproval() 继续执行。

会话持久化与跨进程恢复

会话记录默认持久化到云开发数据库，不依赖进程内存。第二次函数调用时用 conversationId 恢复上下文：

const session = await agent.startSession({ userId: "user-1" });
const conversationId = session.id;

// 另一个进程 / 下一次函数调用
const resumed = await agent.resumeSession(conversationId);

事件流

session.send() 返回 AsyncIterable，每一项是 JSON-RPC 格式的 ACP 通知，实际更新内容在 msg.params.update 里。一条真实的帧长这样：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "a8ea09e4-3ae4-4856-a285-bc2a7c9d76ab",
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "content": { "type": "text", "text": "Serverless 是一种" }
    }
  }
}

update.sessionUpdate 的取值：

类型	含义
`agent_message_chunk`	正文增量文本，流式渲染用
`agent_thought_chunk`	思考过程增量（推理模型输出的 reasoning）
`tool_call` / `tool_call_update`	工具调用发起、进度与结果
`agent_phase`	运行阶段变化（结束时为 `idle`）
`usage_update`	本轮用量统计
`log`	运行日志

本轮结束的判定：for await 循环自然退出即本轮结束，不需要监听专门的结束事件。

OAK 的事件流基于 ACP（Agent Client Protocol）：接入 SSE、AG-UI 或自定义协议时，由业务层做事件映射。

部署与接入

写好的 Agent 部署到云开发：

HTTP 云函数部署：按量计费、自动扩缩容
云托管部署：长连接、自定义运行时

客户端与渠道接入沿用现有指南：Web / Node.js / 小程序 / cURL / 微信渠道。

从可视化界面配置迁移

此前在控制台可视化界面上配置的项，在代码里都有对应位置：

可视化界面配置项	现在的做法
人设 / 角色设定	`createAgent` 的 `systemPrompt`
模型选择	`model` 字段
工具 / MCP	`mcpServers` 配置
敏感操作确认	`permissions.requireApproval`
欢迎语 / 开场问题	见下方「动态配置」——存数据库，改配置不改代码

动态配置欢迎语与开场问题

欢迎语和开场问题是界面展示层的数据，不建议写死在代码里。推荐把它们存到云开发数据库的一张配置表，运行时读取——修改配置立即生效，不需要重新部署：

// 云函数入口：每次请求时读取配置表
const db = app.database();
const { data } = await db.collection("agent_config").doc("my-agent").get();

const agent = createAgent({
  envId,
  model: data.model,
  systemPrompt: data.systemPrompt,
});

前端（含 Agent UI 组件）同样从这张配置表读取 welcomeMessage 和 openingQuestions 渲染开场界面。这个模式下，人设、欢迎语、开场问题都成为数据而不是代码，改动它们和改一条数据库记录一样。

从 beta 版本迁移

0.1.1 是首个正式版（此前 npm 上为 0.1.0-beta.x）。如果你按早期 beta 文档写过代码，按下表迁移：

beta.15 / beta.16	0.1.1
`npm install @cloudbase/open-agent-kernel@beta`	`npm install @cloudbase/open-agent-kernel`
环境变量 `TCB_API_KEY`	`CLOUDBASE_APIKEY`
`event.type === "message_delta"`，文本在 `event.text`	`msg.params.update.sessionUpdate === "agent_message_chunk"`，文本在 `update.content.text`
`session_idle` 事件判断本轮结束	`for await` 循环自然退出即结束
`tool_approval_required` 事件	`session/request_permission` 请求帧
`message_complete`（完整文本）	无对应帧，正文由增量自行拼接
Node.js 22+	Node.js 20.19+

常见问题

CLOUDBASE_APIKEY 是什么？ 云开发环境的服务端 API Key，用于默认的模型网关调用与数据面鉴权。它与腾讯云平台凭证（SecretId/SecretKey）不是一回事，后者用于让 SDK 直接操作云开发资源。

哪些能力需要 credentials？ 会话持久化、审批状态在仅有 CLOUDBASE_APIKEY 时即可工作；本地工作区文件的云端同步、多模态附件上传等需要传 credentials。缺失时工作区同步会跳过并打印 [oak/workspacePersist] 警告，不影响对话本身。

沙箱现在能用吗？ Sandbox 能力当前内测中，如有需求请联系我们。

快速开始​

在控制台创建​

核心配置​

配置 MCP 工具​

工具审批（HITL）​

会话持久化与跨进程恢复​

事件流​

部署与接入​

从可视化界面配置迁移​

动态配置欢迎语与开场问题​

从 beta 版本迁移​

常见问题​