@cloudbase/agent-adapter-langgraph 1.0.1-alpha.21 → 1.0.1-alpha.24

package/README.md

@@ -121,10 +121,130 @@ function shouldContinue(state: ClientState): "tools" | "end" {
 }
 ``` 
 
+## CloudBaseSaver
+
+`CloudBaseSaver` 是基于腾讯云开发（CloudBase）的 LangGraph 检查点存储实现，支持多租户隔离。
+
+### 安装依赖
+
+```bash
+npm install @cloudbase/node-sdk
+```
+
+### 基本用法
+
+```typescript
+import { CloudBaseSaver } from "@cloudbase/agent-adapter-langgraph";
+import cloudbase from "@cloudbase/node-sdk";
+
+// 初始化 CloudBase
+const app = cloudbase.init({
+  env: process.env.CLOUDBASE_ENV_ID,
+  secretId: process.env.CLOUDBASE_SECRET_ID,
+  secretKey: process.env.CLOUDBASE_SECRET_KEY,
+});
+
+const db = app.database();
+
+// 创建检查点存储
+const checkpointer = new CloudBaseSaver({
+  db,
+  userId: "user-123",  // 用于多租户隔离
+  agentId: "my-agent",                       // 可选，用于区分不同 Agent，默认 "default"
+  checkpointsCollection: "checkpoints",      // 可选，默认 "checkpoints"
+  writesCollection: "checkpoint_writes",     // 可选，默认 "checkpoint_writes"
+});
+
+// 首次使用前，调用 setup() 创建数据库集合（可选，也可手动在控制台创建）
+await checkpointer.setup();
+
+// 在 LangGraph 工作流中使用
+const compiledWorkflow = workflow.compile({ checkpointer });
+```
+
+### 配置选项
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `db` | `CloudBaseDb` | ✅ | - | CloudBase 数据库实例，通过 `app.database()` 获取 |
+| `userId` | `string` | ✅ | - | 用户 ID，用于多租户数据隔离 |
+| `agentId` | `string` | ❌ | `"default"` | Agent ID，用于区分同一用户的不同 Agent/工作流 |
+| `checkpointsCollection` | `string` | ❌ | `"checkpoints"` | 存储检查点的集合名称 |
+| `writesCollection` | `string` | ❌ | `"checkpoint_writes"` | 存储待处理写入的集合名称 |
+
+### setup() 方法
+
+`setup()` 方法用于自动创建所需的数据库集合。该方法是幂等的，可以安全地多次调用：
+
+```typescript
+// 在应用启动时调用一次即可
+await checkpointer.setup();
+```
+
+如果集合已存在，`setup()` 会静默跳过，不会抛出错误。你也可以选择在 CloudBase 控制台手动创建集合。
+
+### 获取 userId
+
+在实际应用中，`userId` 通常从请求的认证信息中获取。一种常见方式是解析 JWT token 的 `sub` claim：
+
+```typescript
+function getUserIdFromRequest(request: Request): string {
+  const authHeader = request.headers.get("Authorization");
+  if (!authHeader?.startsWith("Bearer ")) {
+    throw new Error("Missing Authorization header");
+  }
+
+  const token = authHeader.slice(7);
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new Error("Invalid JWT format");
+  }
+
+  // 解码 payload（base64url）
+  const payload = parts[1]!;
+  const decoded = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+  const claims = JSON.parse(decoded);
+
+  if (typeof claims.sub !== "string" || !claims.sub) {
+    throw new Error("Invalid JWT: missing 'sub' claim");
+  }
+
+  return claims.sub;
+}
+
+// 在 createAgent 中使用
+createExpressRoutes({
+  createAgent: async (context) => {
+    const userId = getUserIdFromRequest(context.request);
+    const checkpointer = new CloudBaseSaver({ db, userId });
+    // ...
+  },
+  express: app,
+});
+```
+
+> **注意**：上述 JWT 解析仅做 base64 解码，未验证签名。生产环境建议使用 `jose` 等库进行完整的 JWT 验证。
+
+### 创建数据库集合
+
+在 CloudBase 控制台创建以下集合：
+
+- `checkpoints`（或自定义名称）
+- `checkpoint_writes`（或自定义名称）
+
+### 环境变量
+
+```bash
+CLOUDBASE_ENV_ID=your-env-id
+CLOUDBASE_SECRET_ID=your-secret-id
+CLOUDBASE_SECRET_KEY=your-secret-key
+```
+
 ## 依赖
 
 - `@langchain/langgraph`：LangGraph 框架
 - `@langchain/core`：LangChain 核心工具
+- `@cloudbase/node-sdk`：腾讯云开发 SDK（peerDependency，使用 CloudBaseSaver 时需安装）
 
 ## 文档
 
@@ -134,3 +254,4 @@ function shouldContinue(state: ClientState): "tools" | "end" {
 
 - [AG-UI 协议](https://docs.ag-ui.com)
 - [LangGraph 文档](https://langchain-ai.github.io/langgraph/)
+- [LangGraph Checkpointer 概念](https://langchain-ai.github.io/langgraph/concepts/persistence/) - 了解 checkpointer 的更多用法（如 `getTuple`、`list`、`deleteThread` 等）

package/dist/index.d.mts

@@ -8,6 +8,8 @@ import { Logger } from '@cloudbase/agent-shared';
 export { Logger, createConsoleLogger, noopLogger } from '@cloudbase/agent-shared';
 import { RunnableConfig } from '@langchain/core/runnables';
 import { IMemoryClientOptions, MemoryClient } from '@cloudbase/agent-agents';
+import { CheckpointListOptions as CheckpointListOptions$1, PendingWrite as PendingWrite$1 } from '@langchain/langgraph-checkpoint';
+import { CloudBase } from '@cloudbase/node-sdk';
 
 type SDZod = StateDefinition | InteropZodObject;
 type CompiledStateGraph<SD extends SDZod> = ReturnType<StateGraph<SD>["compile"]>;
@@ -135,6 +137,72 @@ declare class TDAISaver extends BaseCheckpointSaver {
     close(): void;
 }
 
+/** CloudBase database instance type (from app.database()) */
+type CloudBaseDb = ReturnType<CloudBase["database"]>;
+interface CloudBaseSaverConfig {
+    /** CloudBase database instance from app.database() */
+    db: CloudBaseDb;
+    /** User ID for multi-tenant isolation */
+    userId: string;
+    /** Agent ID to distinguish different agents/graphs (default: "default") */
+    agentId?: string;
+    /** Collection name for checkpoints (default: "checkpoints") */
+    checkpointsCollection?: string;
+    /** Collection name for writes (default: "checkpoint_writes") */
+    writesCollection?: string;
+}
+/**
+ * CloudBaseSaver - LangGraph checkpoint saver implementation using Tencent CloudBase
+ *
+ * Storage Strategy:
+ * - Uses 2 collections: checkpoints and checkpoint_writes
+ * - Data is serialized using BaseCheckpointSaver's serde (base64 encoded)
+ * - Multi-tenant isolation via userId field
+ */
+declare class CloudBaseSaver extends BaseCheckpointSaver {
+    private db;
+    private userId;
+    private agentId;
+    private checkpointsCollection;
+    private writesCollection;
+    constructor(config: CloudBaseSaverConfig);
+    /**
+     * Setup the required collections in CloudBase.
+     * Call this once before using the saver. Safe to call multiple times.
+     */
+    setup(): Promise<void>;
+    /**
+     * Serialize data to JSON object using serde.
+     * CloudBase is a document database, so we store JSON directly instead of Base64.
+     * Binary data (Uint8Array) is not supported - fail early if encountered.
+     */
+    private serialize;
+    /**
+     * Deserialize JSON object back to data using serde.
+     */
+    private deserialize;
+    /**
+     * Retrieves a checkpoint from CloudBase based on the provided config.
+     */
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    /**
+     * List checkpoints from CloudBase, ordered by checkpoint_id descending.
+     */
+    list(config: RunnableConfig, options?: CheckpointListOptions$1): AsyncGenerator<CheckpointTuple>;
+    /**
+     * Save a checkpoint to CloudBase.
+     */
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
+    /**
+     * Save intermediate writes to CloudBase.
+     */
+    putWrites(config: RunnableConfig, writes: PendingWrite$1[], taskId: string): Promise<void>;
+    /**
+     * Delete all checkpoints and writes for a thread.
+     */
+    deleteThread(threadId: string): Promise<void>;
+}
+
 /**
  * TDAI Store configuration
  */
@@ -296,4 +364,4 @@ declare class TDAIStore extends BaseStore {
     }): Promise<Item[]>;
 }
 
-export { ClientPropertiesAnnotation, type ClientState, ClientStateAnnotation, LanggraphAgent, TDAISaver, type TDAISaverConfig, TDAIStore, type TDAIStoreConfig };
+export { ClientPropertiesAnnotation, type ClientState, ClientStateAnnotation, CloudBaseSaver, type CloudBaseSaverConfig, LanggraphAgent, TDAISaver, type TDAISaverConfig, TDAIStore, type TDAIStoreConfig };

package/dist/index.d.ts

@@ -8,6 +8,8 @@ import { Logger } from '@cloudbase/agent-shared';
 export { Logger, createConsoleLogger, noopLogger } from '@cloudbase/agent-shared';
 import { RunnableConfig } from '@langchain/core/runnables';
 import { IMemoryClientOptions, MemoryClient } from '@cloudbase/agent-agents';
+import { CheckpointListOptions as CheckpointListOptions$1, PendingWrite as PendingWrite$1 } from '@langchain/langgraph-checkpoint';
+import { CloudBase } from '@cloudbase/node-sdk';
 
 type SDZod = StateDefinition | InteropZodObject;
 type CompiledStateGraph<SD extends SDZod> = ReturnType<StateGraph<SD>["compile"]>;
@@ -135,6 +137,72 @@ declare class TDAISaver extends BaseCheckpointSaver {
     close(): void;
 }
 
+/** CloudBase database instance type (from app.database()) */
+type CloudBaseDb = ReturnType<CloudBase["database"]>;
+interface CloudBaseSaverConfig {
+    /** CloudBase database instance from app.database() */
+    db: CloudBaseDb;
+    /** User ID for multi-tenant isolation */
+    userId: string;
+    /** Agent ID to distinguish different agents/graphs (default: "default") */
+    agentId?: string;
+    /** Collection name for checkpoints (default: "checkpoints") */
+    checkpointsCollection?: string;
+    /** Collection name for writes (default: "checkpoint_writes") */
+    writesCollection?: string;
+}
+/**
+ * CloudBaseSaver - LangGraph checkpoint saver implementation using Tencent CloudBase
+ *
+ * Storage Strategy:
+ * - Uses 2 collections: checkpoints and checkpoint_writes
+ * - Data is serialized using BaseCheckpointSaver's serde (base64 encoded)
+ * - Multi-tenant isolation via userId field
+ */
+declare class CloudBaseSaver extends BaseCheckpointSaver {
+    private db;
+    private userId;
+    private agentId;
+    private checkpointsCollection;
+    private writesCollection;
+    constructor(config: CloudBaseSaverConfig);
+    /**
+     * Setup the required collections in CloudBase.
+     * Call this once before using the saver. Safe to call multiple times.
+     */
+    setup(): Promise<void>;
+    /**
+     * Serialize data to JSON object using serde.
+     * CloudBase is a document database, so we store JSON directly instead of Base64.
+     * Binary data (Uint8Array) is not supported - fail early if encountered.
+     */
+    private serialize;
+    /**
+     * Deserialize JSON object back to data using serde.
+     */
+    private deserialize;
+    /**
+     * Retrieves a checkpoint from CloudBase based on the provided config.
+     */
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    /**
+     * List checkpoints from CloudBase, ordered by checkpoint_id descending.
+     */
+    list(config: RunnableConfig, options?: CheckpointListOptions$1): AsyncGenerator<CheckpointTuple>;
+    /**
+     * Save a checkpoint to CloudBase.
+     */
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
+    /**
+     * Save intermediate writes to CloudBase.
+     */
+    putWrites(config: RunnableConfig, writes: PendingWrite$1[], taskId: string): Promise<void>;
+    /**
+     * Delete all checkpoints and writes for a thread.
+     */
+    deleteThread(threadId: string): Promise<void>;
+}
+
 /**
  * TDAI Store configuration
  */
@@ -296,4 +364,4 @@ declare class TDAIStore extends BaseStore {
     }): Promise<Item[]>;
 }
 
-export { ClientPropertiesAnnotation, type ClientState, ClientStateAnnotation, LanggraphAgent, TDAISaver, type TDAISaverConfig, TDAIStore, type TDAIStoreConfig };
+export { ClientPropertiesAnnotation, type ClientState, ClientStateAnnotation, CloudBaseSaver, type CloudBaseSaverConfig, LanggraphAgent, TDAISaver, type TDAISaverConfig, TDAIStore, type TDAIStoreConfig };