OpenAgentKernel (Official SDK)

@cloudbase/open-agent-kernel (OAK) is the official server-side Agent SDK for CloudBase, open source under Apache-2.0. It ships with the infrastructure that Agent developers rebuild most often — session persistence, multi-turn context, MCP tool integration, human-in-the-loop approval (HITL), user long-term memory, and sandboxed execution — so you only write business logic.

• GitHub: https://github.com/TencentCloudBase/OpenAgentKernel
• CNB: https://cnb.cool/tencent/cloud/cloudbase/OpenAgentKernel
• npm: https://www.npmjs.com/package/@cloudbase/open-agent-kernel

Quick start

Prerequisites: Node.js 22+, a CloudBase environment envId, and the environment's server-side API Key (get one here).

npm install @cloudbase/open-agent-kernel@beta

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

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

const agent = createAgent({
  envId: "your-env-id",
  model: "deepseek-v4-pro",
  systemPrompt: "You are a helpful assistant.",
});

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

for await (const event of session.send("Explain Serverless in one sentence.")) {
  if (event.type === "message_delta") process.stdout.write(event.text);
  if (event.type === "session_idle") break; // end of this turn
}

Passing a model ID string uses the CloudBase AI gateway with TCB_API_KEY authentication. You can also pass { id, apiKey, apiBaseUrl } to bring your own endpoint.

Create from the console

Open the Agent section of the CloudBase console and choose the official cloudbase-agent template when creating an Agent. What you get is an OpenAgentKernel project: session persistence, MCP tools, and human approval work out of the box, and you can chat with it on the "Integrate & Debug" page right after creation.

For deeper customization, follow the "Local development" page:

tcb fn code download   # pull the code locally
# edit the code...
tcb fn deploy          # deploy back to the cloud

The console handles hosting, logs, and debugging entry points; OpenAgentKernel handles the runtime.

Core configuration

Common fields of createAgent(config):

Field	Required	Description
envId	Yes	CloudBase environment ID; the model gateway, database, storage, and sandbox are all anchored to it
model	Yes	Model ID (via the CloudBase AI gateway) or a full { id, apiKey, apiBaseUrl } spec
systemPrompt	No	System prompt (the Agent's persona and behavioral constraints)
mcpServers	No	MCP server config; supports in-process, local stdio, and remote HTTP
permissions	No	Tool approval (HITL): requireApproval accepts '*', an array of tool names, or a function
session	No	Session persistence, stored in the CloudBase database by default (table prefix oak_)
storage	No	Multimodal attachment storage, stored in CloudBase cloud storage by default
sandbox	No	Remote sandbox (currently in private beta; contact us if you need it)
userMemory	No	User long-term memory, synced to CloudBase cloud storage across sessions
credentials	Depends	Tencent Cloud SecretId/SecretKey; with only TCB_API_KEY, sessions/approvals/memory still persist, while attachment upload and similar features require it

See the full parameter reference in the GitHub README for all fields and defaults.

Configure MCP tools

const agent = createAgent({
  envId,
  model: "glm-5.2",
  systemPrompt: "You are a helpful assistant.",
  mcpServers: {
    // remote HTTP MCP
    remote: {
      type: "http",
      url: "https://example.com/mcp/v1",
      headers: { Authorization: "Bearer xxx" },
    },
    // local stdio MCP
    stdio: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-everything"],
    },
  },
});

Tool names follow the mcp__{serverName}__{toolName} convention. For in-process custom tools, see the MCP section of the README.

Tool approval (HITL)

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

Matching tool calls pause and emit a tool_approval_required event. Show your confirmation UI, then call session.respondApproval() to continue.

Session persistence and cross-process resume

Session records persist to the CloudBase database by default and do not rely on process memory. Resume the context in a later function invocation with the conversationId:

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

// in another process / the next function invocation
const resumed = await agent.resumeSession(conversationId);

Event stream

session.send() returns an AsyncIterable<SessionEvent>:

Event	Meaning
message_delta	Incremental model output text, for streaming rendering
message_complete	The complete text of one output
tool_call / tool_result	Tool invocation and its result
tool_approval_required	Waiting for human approval
session_idle	End of this turn (reason: completed / requires_action / aborted / error)
error	Runtime error

OAK's event stream is protocol-neutral: when integrating with SSE, AG-UI, or a custom protocol, map the events in your application layer.

Deployment and integration

Deploy your Agent to CloudBase:

• HTTP cloud function deployment: pay-as-you-go, auto scaling
• Cloud hosting deployment: long-lived connections, custom runtime

Client and channel integration follows the existing guides: Web / Node.js / Mini Program / cURL / WeChat channels.

Migrating from visual configuration

Everything you used to configure on the console's visual interface has a place in code:

Visual configuration item	How to do it now
Persona / role setting	systemPrompt in createAgent
Model selection	the model field
Tools / MCP	mcpServers config
Sensitive-operation confirmation	permissions.requireApproval
Welcome message / opening questions	See "Dynamic configuration" below — stored as data, changed without code changes

Dynamic welcome message and opening questions

The welcome message and opening questions are presentation-layer data and should not be hard-coded. Store them in a config collection in the CloudBase database and read them at runtime — changes take effect immediately without redeploying:

// cloud function entry: read the config collection per request
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,
});

The frontend (including Agent UI components) reads welcomeMessage and openingQuestions from the same collection to render the opening screen. With this pattern, the persona, welcome message, and opening questions are data rather than code — changing them is as simple as updating a database record.

FAQ

What is TCB_API_KEY? The server-side API Key of a CloudBase environment, used for the default model gateway calls. It is not the same as Tencent Cloud platform credentials (SecretId/SecretKey), which let the SDK operate CloudBase resources directly.

Which features need credentials? Session persistence, approval state, and user memory work with only TCB_API_KEY; multimodal attachment upload and tenant isolation for CloudBase tools inside the sandbox require credentials.

Is the sandbox available now? The Sandbox capability is currently in private beta; contact us if you need it.