[feat] [sdk] @cozeloop/langchain@0.0.3 LangGraph span type and peer with langchain v1 (#22)

* feat(cozeloop-langchain): add graph span type for LangGraph Node

* feat(cozeloop-langchain): peer with langchain v1

* feat(cozeloop-langchain): bump to 0.0.3

Author: mocayo

packages/cozeloop-langchain/CHANGELOG.md

@@ -1,7 +1,14 @@
 # 🕗 Change Log - @cozeloop/langchain
 
+## 0.0.3
+
+* [feat]: LangGraph Node type
+* [feat]: peer with langchain v1
+
 ## 0.0.2
-fix: DEFAULT_SCHEDULE_DELAY to 1_000 ms
+
+* [fix]: DEFAULT_SCHEDULE_DELAY to 1_000 ms
 
 ## 0.0.1
+
 🌱 Initial version

packages/cozeloop-langchain/README.md

@@ -3,119 +3,120 @@
 [![npm version](https://img.shields.io/npm/v/%40cozeloop%2Flangchain)](https://www.npmjs.com/package/@cozeloop/langchain)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Integrate Langchain with Cozeloop via `@cozeloop/langchain`, supports:
-* `CozeloopCallbackHandler`: report trace to Cozeloop
+Official LangChain integration for [CozeLoop](https://loop.coze.cn) - seamlessly report traces from your LangChain and LangGraph applications.
 
-## Quick Start
+## Features
 
-### 1. Installation
+- **CozeloopCallbackHandler**: Automatically capture and report traces to CozeLoop
+- Support for both LangChain and LangGraph
+- W3C trace context propagation for distributed tracing
+
+## Installation
 
 ```sh
 npm install @cozeloop/langchain
 # or
 pnpm install @cozeloop/langchain
 ```
 
-### 2. Basic Usage
-
-1. Environment variables
-
-The following variables are optional, and will be used if values provided.
+## Configuration
 
-|Variable|Comment|Example|
-|----|----|------|
-|COZELOOP_WORKSPACE_ID|Cozeloop workspace id, used to identify the workspace to which resource such as trace belongs|'7487806534651887643'|
-|COZELOOP_API_TOKEN|Cozeloop api token, see [authentication-for-sdk](https://loop.coze.cn/open/docs/cozeloop/authentication-for-sdk) |'pat_xxxx'|
-|COZELOOP_OTLP_ENDPOINT|Trace endpoint|'https://api.coze.cn/v1/loop/opentelemetry/v1/trace'|
+### Environment Variables
 
+The following environment variables can be used to configure the integration:
 
-2. `CozeloopCallbackHandler`
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `COZELOOP_WORKSPACE_ID` | Workspace ID for resource association | `'7487806534651887643'` |
+| `COZELOOP_API_TOKEN` | API token for authentication. See [Authentication Guide](https://loop.coze.cn/open/docs/cozeloop/authentication-for-sdk) | `'pat_xxxx'` |
+| `COZELOOP_OTLP_ENDPOINT` | Trace reporting endpoint | `'https://api.coze.cn/v1/loop/opentelemetry/v1/traces'` |
 
-Callbacks can be used with LangChain and LangGraph.
+## Usage
 
-Since the traces exporting is asynchronous, it can be interrupted by the termination of Node.js process.
+### CozeloopCallbackHandler
 
-(1) When you run a file in command line, call `await callback.flush();` to ensure all traces exported.
+The callback handler integrates with LangChain and LangGraph to automatically capture traces.
 
-(2) If you are running a server-side application, there is no need to flush, but it's recommended to call `await callback.shutdown();` to clean resource.
+> **Note**: Since trace exporting is asynchronous, proper cleanup is required:
+>
+> - **CLI scripts**: Call `await callback.flush()` before exit to ensure all traces are exported.
+> - **Server applications**: Call `await callback.shutdown()` during graceful shutdown to release resources.
 
-* Initialize
+#### Initialization
 
 ```typescript
 import { CozeloopCallbackHandler } from '@cozeloop/langchain';
 
-// initialize callback
 const callback = new CozeloopCallbackHandler({
-  // Common callback params
+  // Span exporter configuration
+  spanExporter: {
+    workspaceId: 'xxx',
+    token: 'pat_xxx',
+    traceEndpoint: 'https://api.coze.cn/v1/loop/opentelemetry/v1/traces',
+  },
+  // Optional: Filter specific trace types
   // ignoreAgent: false,
   // ignoreChain: false,
   // ignoreCustomEvent: false,
   // ignoreLLM: false,
   // ignoreRetriever: false,
   // ignorePrompt: false,
-  /** Span exporter */
-  spanExporter: {
-    workspaceId: 'xxx',
-    token: 'pat_xxx',
-    traceEndpoint: 'https://api.coze.cn/v1/loop/opentelemetry/v1/traces',
-  },
-  /** Propagate with upstream services */
+
+  // Optional: Propagate trace context from upstream services
   // propagationHeaders: {
-  //   tracestate: '',
   //   traceparent: '00-b3691bfe8af1415029177821d4114cef-ddd0307891d51ce3-01',
+  //   tracestate: '',
   // },
 });
 
-// use to propagate with downstream services
-// callback.w3cPropagationHeaders
+// Access W3C propagation headers for downstream services
+// const headers = callback.w3cPropagationHeaders;
 ```
 
-* With LangChain
+#### With LangChain
+
 ```typescript
 import { CozeloopCallbackHandler } from '@cozeloop/langchain';
 import { ChatPromptTemplate } from '@langchain/core/prompts';
 
-// Chain
+const callback = new CozeloopCallbackHandler({ /* options */ });
+
 const prompt = ChatPromptTemplate.fromTemplate('What is 1 + {number}?');
 const model = new CustomLLM({});
 const chain = prompt.pipe(model);
-const callback = new CozeloopCallbackHandler({ /** options */});
 
 const resp = await chain.invoke(
   { number: 1 },
   {
     runName: 'SuperChain',
-    callbacks: [callback], // set callback
+    callbacks: [callback],
   },
 );
 
-// call `flush` to ensure trace exported in script run
+// Ensure traces are exported before script exits
 await callback.flush();
 ```
 
-* With LangGraph
+#### With LangGraph
+
 ```typescript
 import { CozeloopCallbackHandler } from '@cozeloop/langchain';
-
 import { createReactAgent } from '@langchain/langgraph/prebuilt';
 
+const callback = new CozeloopCallbackHandler({ /* options */ });
+
 const agent = createReactAgent({
   llm: model,
   tools: [tool1, tool2],
 });
 
-const resp = await graphAgent.invoke(
+const resp = await agent.invoke(
   {
-    messages: [
-      {
-        role: 'user',
-        content: 'xxx',
-      },
-    ],
+    messages: [{ role: 'user', content: 'Hello!' }],
   },
-  { callbacks: [callback] }, // set callback
+  { callbacks: [callback] },
 );
 
-// call `flush` to ensure trace exported in script run
+// Ensure traces are exported before script exits
 await callback.flush();
 ```

packages/cozeloop-langchain/__tests__/callback/utils/chain.test.ts

@@ -3,6 +3,7 @@
 import {
   guessChainInput,
   guessChainOutput,
+  isLangGraphNode,
 } from '@cozeloop/langchain/callbacks/utils';
 
 describe('guessChainInput', () => {
@@ -65,3 +66,16 @@ describe('guessChainOutput', () => {
     expect(guessChainOutput(output)).toBe(output.returnValues.text);
   });
 });
+
+describe('isLangGraphNode', () => {
+  it('🧪 should return true for "LangGraph" name', () => {
+    expect(isLangGraphNode('LangGraph')).toBe(true);
+  });
+
+  it('🧪 should return false for other names', () => {
+    expect(isLangGraphNode('SomeOtherNode')).toBe(false);
+    expect(isLangGraphNode('langgraph')).toBe(false);
+    expect(isLangGraphNode('LANGGRAPH')).toBe(false);
+    expect(isLangGraphNode('')).toBe(false);
+  });
+});

packages/cozeloop-langchain/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cozeloop/langchain",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Integration LangChain with CozeLoop | 扣子罗盘 LangChain 集成",
   "keywords": [
     "cozeloop",
@@ -70,7 +70,7 @@
     "vitest": "~2.1.4"
   },
   "peerDependencies": {
-    "@langchain/core": "^0.3.61",
-    "@langchain/langgraph": "^0.3.1"
+    "@langchain/core": "^0.3.61 || ^1.0.0",
+    "@langchain/langgraph": "^0.3.1 || ^1.0.0"
   }
 }

packages/cozeloop-langchain/src/callbacks/callback-handler.ts

@@ -28,6 +28,7 @@ import {
   generateUUID,
   guessChainInput,
   guessChainOutput,
+  isLangGraphNode,
   parseBaseMessages,
   parseLLMResult,
   stringifyVal,
@@ -334,7 +335,9 @@ export class CozeloopCallbackHandler
     const spanName = runName || 'ChainStart';
     this._startSpan(spanName, runId, parentRunId, span => {
       span.setAttributes({
-        [CozeloopAttr.SPAN_TYPE]: CozeloopSpanType.CHAIN,
+        [CozeloopAttr.SPAN_TYPE]: isLangGraphNode(spanName)
+          ? CozeloopSpanType.GRAPH
+          : CozeloopSpanType.CHAIN,
         [CozeloopAttr.INPUT]: stringifyVal(guessChainInput(inputs)),
       });
     });

packages/cozeloop-langchain/src/callbacks/constants.ts

@@ -37,6 +37,7 @@ export enum CozeloopSpanType {
   RETRIEVER = 'retriever',
   TOOL = 'tool',
   CHAIN = 'chain',
+  GRAPH = 'graph',
   AGENT = 'agent',
   CUSTOM = 'custom',
 }

packages/cozeloop-langchain/src/callbacks/utils/chain.ts

@@ -27,3 +27,7 @@ export function guessChainOutput(outputs?: ChainValues) {
     outputs
   );
 }
+
+export function isLangGraphNode(name: string) {
+  return name === 'LangGraph';
+}

packages/cozeloop-langchain/src/callbacks/utils/index.ts

@@ -1,6 +1,6 @@
 // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
 // SPDX-License-Identifier: MIT
-export { guessChainInput, guessChainOutput } from './chain';
+export { guessChainInput, guessChainOutput, isLangGraphNode } from './chain';
 export { generateUUID, stringifyVal } from './common';
 export { parseBaseMessages, parseRawMessage } from './message';
 export {