@cloudbase/agent-adapter-langgraph 0.0.12 → 0.0.13

package/README.md

@@ -1,125 +1,136 @@
 # @cloudbase/agent-adapter-langgraph
 
-LangGraph adapter for AG-Kit agents. This package provides integration between AG-Kit and LangGraph framework, enabling you to use LangGraph workflows with AG-Kit's agent infrastructure.
+将 LangGraph 工作流转换为符合 [AG-UI 协议](https://docs.ag-ui.com) 的 Agent。
 
-## Installation
+## 安装
 
 ```bash
-npm install @cloudbase/agent-agents @cloudbase/agent-adapter-langgraph
+npm install @cloudbase/agent-adapter-langgraph
 ```
 
-## Features
+## 功能
 
-- **LangGraphAgent**: Agent implementation that works with compiled LangGraph workflows
-- **TDAISaver**: Checkpoint saver implementation using TDAI Memory
-- **TDAIStore**: Store implementation for LangGraph using TDAI Memory
-- **AGKitStateAnnotation**: Pre-configured state annotation for AG-Kit integration
+- **LanggraphAgent**：将编译后的 LangGraph 工作流包装为 AG-UI 兼容的 Agent
+- **ClientStateAnnotation**：工作流状态定义，包含 messages 和 client tools
 
-## Usage
+## 快速开始
 
-### Basic Agent Setup
+### 配合 @cloudbase/agent-server 使用
 
 ```typescript
+import { run } from "@cloudbase/agent-server";
 import { StateGraph, START, END } from "@langchain/langgraph";
-import { AGKitStateAnnotation, LanggraphAgent } from "@cloudbase/agent-adapter-langgraph";
-import { AgentConfig } from "@cloudbase/agent-agents/abstract";
+import { ClientStateAnnotation, LanggraphAgent } from "@cloudbase/agent-adapter-langgraph";
 
-// Create your LangGraph workflow
-const workflow = new StateGraph(AGKitStateAnnotation)
+// 创建 LangGraph 工作流
+const workflow = new StateGraph(ClientStateAnnotation)
   .addNode("chat_node", chatNode)
   .addEdge(START, "chat_node")
   .addEdge("chat_node", END);
 
 const compiledWorkflow = workflow.compile();
 
-// Create the agent
-const agent = new LanggraphAgent({
-  name: "my-langgraph-agent",
-  description: "A LangGraph agent",
-  compiledWorkflow,
+// 部署为 HTTP 服务
+run({
+  createAgent: () => ({
+    agent: new LanggraphAgent({ compiledWorkflow }),
+  }),
+  port: 9000,
 });
 ```
 
-### Using TDAISaver for Checkpoints
+## API 参考
 
-```typescript
-import { TDAISaver } from "@cloudbase/agent-adapter-langgraph";
-import { MemoryClient } from "@cloudbase/agent-agents";
+### LanggraphAgent
 
-const memoryClient = new MemoryClient({
-  endpoint: "https://api.tdai.com",
-  apiKey: "your-api-key",
-  memoryId: "your-memory-id",
-});
+将编译后的 LangGraph 工作流转换为 AG-UI 兼容的 Agent。
 
-const checkpointer = new TDAISaver({
-  endpoint: "https://api.tdai.com",
-  apiKey: "your-api-key",
-  memoryId: "your-memory-id",
-});
+```typescript
+type LanggraphAgentConfig = AgentConfig & {
+  compiledWorkflow: CompiledStateGraph; // 编译后的 LangGraph 工作流
+  logger?: Logger;                      // 可选，日志实例
+};
 
-const compiledWorkflow = workflow.compile({
-  checkpointer,
-});
+const agent = new LanggraphAgent(config);
 ```
 
-### Using TDAIStore
+- `AgentConfig`：来自 [AG-UI 协议](https://docs.ag-ui.com)
+- `Logger`：日志接口，详见 [@cloudbase/agent-server 文档](https://www.npmjs.com/package/@cloudbase/agent-server)
 
-```typescript
-import { TDAIStore } from "@cloudbase/agent-adapter-langgraph";
-import { MemoryClient } from "@cloudbase/agent-agents";
+### ClientStateAnnotation
 
-const memoryClient = new MemoryClient({
-  endpoint: "https://api.tdai.com",
-  apiKey: "your-api-key",
-  memoryId: "your-memory-id",
-});
+创建 LangGraph 工作流时使用的状态定义，已包含 AG-UI 需要的字段：
 
-const store = new TDAIStore({
-  memoryClient,
-  sessionId: "session-123",
-});
+- `messages`：消息历史
+- `client.tools`：客户端传来的工具列表
+
+```typescript
+const workflow = new StateGraph(ClientStateAnnotation)
+  .addNode("chat_node", chatNode)
+  // ...
 ```
 
-## API Reference
+## 使用客户端工具
 
-### LanggraphAgent
+AG-UI 支持**客户端工具**（Client Tools）：客户端定义工具，Agent 调用后由客户端执行并返回结果。
+
+适用场景：
+- 需要访问客户端 API（如获取地理位置、访问剪贴板）
+- 需要用户确认的操作（如发送邮件前确认）
+- 需要展示 UI 交互（如让用户选择文件）
 
-Agent class that extends `AbstractAgent` and works with compiled LangGraph workflows.
+### 在 chatNode 中使用客户端工具
 
-**Constructor:**
 ```typescript
-constructor(config: AgentConfig & { compiledWorkflow: CompiledStateGraph })
-```
+import { ClientState } from "@cloudbase/agent-adapter-langgraph";
 
-### TDAISaver
+async function chatNode(state: ClientState) {
+  const model = new ChatOpenAI({ model: "gpt-4o" });
 
-Checkpoint saver implementation for LangGraph using TDAI Memory.
+  // 合并服务端工具和客户端工具
+  const modelWithTools = model.bindTools([
+    ...serverTools,              // 服务端定义的工具
+    ...(state.client?.tools || []) // 客户端传来的工具
+  ]);
 
-**Constructor:**
-```typescript
-constructor(config: TDAISaverConfig)
+  const response = await modelWithTools.invoke([...state.messages]);
+  return { messages: [response] };
+}
 ```
 
-### TDAIStore
+### 区分服务端工具和客户端工具
 
-Store implementation for LangGraph using TDAI Memory.
+当 Agent 调用工具时，需要判断是服务端执行还是交给客户端：
 
-**Constructor:**
 ```typescript
-constructor(config: TDAIStoreConfig)
-```
+const serverToolNames = new Set(serverTools.map(t => t.name));
+
+function shouldContinue(state: ClientState): "tools" | "end" {
+  const lastMessage = state.messages.at(-1) as AIMessage;
+
+  if (lastMessage.tool_calls?.length) {
+    // 如果是服务端工具，继续执行
+    const hasServerTool = lastMessage.tool_calls.some(
+      tc => serverToolNames.has(tc.name)
+    );
+    if (hasServerTool) return "tools";
+  }
+
+  // 客户端工具或无工具调用，结束并返回给客户端
+  return "end";
+}
+``` 
+
+## 依赖
 
-## Requirements
+- `@langchain/langgraph`：LangGraph 框架
+- `@langchain/core`：LangChain 核心工具
 
-- `@cloudbase/agent-agents`: Core agent functionality
-- `@langchain/langgraph`: LangGraph framework
-- `@langchain/core`: LangChain core utilities
-- `rxjs`: Reactive extensions for JavaScript
+## 文档
 
-## Related Resources
+📚 完整文档请参阅 [云开发 Agent 开发指南](https://docs.cloudbase.net/ai/agent-development/)
 
-- [AG-Kit Documentation](https://docs.agkit.dev)
-- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
-- [AG-Kit Examples](https://github.com/agkit/agkit/tree/main/typescript-sdk/packages/examples)
+## 相关资源
 
+- [AG-UI 协议](https://docs.ag-ui.com)
+- [LangGraph 文档](https://langchain-ai.github.io/langgraph/)

package/dist/index.d.mts

@@ -4,6 +4,8 @@ import { AnnotationRoot, StateDefinition, StateGraph, BaseCheckpointSaver, Check
 import { AbstractAgent, AgentConfig, RunAgentInput, EventType, BaseEvent } from '@ag-ui/client';
 import { Observable, Subscriber } from 'rxjs';
 import { InteropZodObject } from '@langchain/core/utils/types';
+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';
 
@@ -59,8 +61,14 @@ declare const ClientStateAnnotation: AnnotationRoot<{
 type ClientState = typeof ClientStateAnnotation.State;
 declare class LanggraphAgent extends AbstractAgent {
     compiledWorkflow?: CompiledStateGraph<ClientStateDefinition>;
+    private logger;
     constructor(agentConfig: AgentConfig & {
         compiledWorkflow: any;
+        /**
+         * Logger instance for structured logging.
+         * @default noopLogger (silent)
+         */
+        logger?: Logger;
     });
     run(input: RunAgentInput): Observable<{
         type: EventType;
@@ -68,7 +76,7 @@ declare class LanggraphAgent extends AbstractAgent {
         rawEvent?: any;
     }>;
     _run(subscriber: Subscriber<BaseEvent>, input: RunAgentInput): Promise<void>;
-    clone(): any;
+    clone(): LanggraphAgent;
 }
 
 type PendingWrite = [string, any];

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { AnnotationRoot, StateDefinition, StateGraph, BaseCheckpointSaver, Check
 import { AbstractAgent, AgentConfig, RunAgentInput, EventType, BaseEvent } from '@ag-ui/client';
 import { Observable, Subscriber } from 'rxjs';
 import { InteropZodObject } from '@langchain/core/utils/types';
+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';
 
@@ -59,8 +61,14 @@ declare const ClientStateAnnotation: AnnotationRoot<{
 type ClientState = typeof ClientStateAnnotation.State;
 declare class LanggraphAgent extends AbstractAgent {
     compiledWorkflow?: CompiledStateGraph<ClientStateDefinition>;
+    private logger;
     constructor(agentConfig: AgentConfig & {
         compiledWorkflow: any;
+        /**
+         * Logger instance for structured logging.
+         * @default noopLogger (silent)
+         */
+        logger?: Logger;
     });
     run(input: RunAgentInput): Observable<{
         type: EventType;
@@ -68,7 +76,7 @@ declare class LanggraphAgent extends AbstractAgent {
         rawEvent?: any;
     }>;
     _run(subscriber: Subscriber<BaseEvent>, input: RunAgentInput): Promise<void>;
-    clone(): any;
+    clone(): LanggraphAgent;
 }
 
 type PendingWrite = [string, any];