@ai-sdk/langchain 2.0.0-beta.98 → 2.0.0

package/README.md

@@ -1,3 +1,202 @@
 # AI SDK - LangChain Adapter
 
-This package contains a LangChain adapter for the AI SDK.
+The **[AI SDK](https://ai-sdk.dev)** LangChain adapter provides seamless integration between [LangChain](https://langchain.com/) and the AI SDK, enabling you to use LangChain agents and graphs with AI SDK UI components.
+
+## Installation
+
+```bash
+npm install @ai-sdk/langchain @langchain/core
+```
+
+> **Note:** `@langchain/core` is a required peer dependency.
+
+## Features
+
+- Convert AI SDK `UIMessage` to LangChain `BaseMessage` format
+- Transform LangChain/LangGraph streams to AI SDK `UIMessageStream`
+- `ChatTransport` implementation for LangSmith deployments
+- Full support for text, tool calls, and tool results
+- Custom data streaming with typed events (`data-{type}`)
+
+## Usage
+
+### Converting Messages
+
+Use `toBaseMessages` to convert AI SDK messages to LangChain format:
+
+```ts
+import { toBaseMessages } from '@ai-sdk/langchain';
+
+// Convert UI messages to LangChain format
+const langchainMessages = await toBaseMessages(uiMessages);
+
+// Use with any LangChain model
+const response = await model.invoke(langchainMessages);
+```
+
+### Streaming from LangGraph
+
+Use `toUIMessageStream` to convert LangGraph streams to AI SDK format:
+
+```ts
+import { toBaseMessages, toUIMessageStream } from '@ai-sdk/langchain';
+import { createUIMessageStreamResponse } from 'ai';
+
+// Convert messages and stream from a LangGraph graph
+const langchainMessages = await toBaseMessages(uiMessages);
+
+const langchainStream = await graph.stream(
+  { messages: langchainMessages },
+  { streamMode: ['values', 'messages'] },
+);
+
+// Convert to UI message stream response
+return createUIMessageStreamResponse({
+  stream: toUIMessageStream(langchainStream),
+});
+```
+
+### Custom Data Streaming
+
+LangChain tools can emit custom data events using `config.writer()`. The adapter converts these to typed `data-{type}` parts:
+
+```ts
+import { tool, type ToolRuntime } from 'langchain';
+
+const analyzeDataTool = tool(
+  async ({ query }, config: ToolRuntime) => {
+    // Emit progress updates - becomes 'data-progress' in the UI
+    config.writer?.({
+      type: 'progress',
+      id: 'analysis-1', // Include 'id' to persist in message.parts
+      step: 'fetching',
+      message: 'Fetching data...',
+      progress: 50,
+    });
+
+    // ... perform analysis ...
+
+    // Emit status update - becomes 'data-status' in the UI
+    config.writer?.({
+      type: 'status',
+      id: 'analysis-1-status',
+      status: 'complete',
+      message: 'Analysis finished',
+    });
+
+    return 'Analysis complete';
+  },
+  {
+    name: 'analyze_data',
+    description: 'Analyze data with progress updates',
+    schema: z.object({ query: z.string() }),
+  },
+);
+```
+
+Enable the `custom` stream mode to receive these events:
+
+```ts
+const stream = await graph.stream(
+  { messages: langchainMessages },
+  { streamMode: ['values', 'messages', 'custom'] },
+);
+```
+
+**Custom data behavior:**
+
+- Data with an `id` field is **persistent** (added to `message.parts` for rendering)
+- Data without an `id` is **transient** (only delivered via the `onData` callback)
+- The `type` field determines the event name: `{ type: 'progress' }` → `data-progress`
+
+### LangSmith Deployment Transport
+
+Use `LangSmithDeploymentTransport` with the AI SDK `useChat` hook to connect directly to a LangGraph deployment from the browser:
+
+```tsx
+import { useChat } from 'ai/react';
+import { LangSmithDeploymentTransport } from '@ai-sdk/langchain';
+import { useMemo } from 'react';
+
+function Chat() {
+  const transport = useMemo(
+    () =>
+      new LangSmithDeploymentTransport({
+        url: 'https://your-deployment.us.langgraph.app',
+        apiKey: process.env.LANGSMITH_API_KEY,
+      }),
+    [],
+  );
+
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    transport,
+  });
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>{m.parts.map(part => part.text).join('')}</div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### `toBaseMessages(messages)`
+
+Converts AI SDK `UIMessage` objects to LangChain `BaseMessage` objects.
+
+**Parameters:**
+
+- `messages`: `UIMessage[]` - Array of AI SDK UI messages
+
+**Returns:** `Promise<BaseMessage[]>`
+
+### `convertModelMessages(modelMessages)`
+
+Converts AI SDK `ModelMessage` objects to LangChain `BaseMessage` objects.
+
+**Parameters:**
+
+- `modelMessages`: `ModelMessage[]` - Array of model messages
+
+**Returns:** `BaseMessage[]`
+
+### `toUIMessageStream(stream)`
+
+Converts a LangChain/LangGraph stream to an AI SDK `UIMessageStream`.
+
+**Parameters:**
+
+- `stream`: `ReadableStream` - LangGraph stream with `streamMode: ['values', 'messages']`
+
+**Returns:** `ReadableStream<UIMessageChunk>`
+
+**Supported stream events:**
+
+- `messages` - Streaming message chunks (text, tool calls)
+- `values` - State updates that finalize pending message chunks
+- `custom` - Custom data events (emitted as `data-{type}` chunks)
+
+### `LangSmithDeploymentTransport`
+
+A `ChatTransport` implementation for LangSmith/LangGraph deployments.
+
+**Constructor Parameters:**
+
+- `options`: `LangSmithDeploymentTransportOptions` - Configuration for the RemoteGraph connection
+  - `url`: `string` - LangSmith deployment URL or local server URL
+  - `apiKey?`: `string` - API key for authentication (optional for local development)
+  - `graphId?`: `string` - The ID of the graph to connect to (defaults to `'agent'`)
+
+**Implements:** `ChatTransport`
+
+## Documentation
+
+Please check out the [AI SDK documentation](https://ai-sdk.dev) for more information.

package/dist/index.d.mts

@@ -1,4 +1,6 @@
-import { UIMessageChunk } from 'ai';
+import { BaseMessage, AIMessageChunk } from '@langchain/core/messages';
+import { UIMessage, UIMessageChunk, ModelMessage, ChatTransport, ChatRequestOptions } from 'ai';
+import { RemoteGraph, RemoteGraphParams } from '@langchain/langgraph/remote';
 
 /**
  * Configuration options and helper callback methods for stream lifecycle events.
@@ -14,38 +16,108 @@ interface StreamCallbacks {
     onText?: (text: string) => Promise<void> | void;
 }
 
-type LangChainImageDetail = 'auto' | 'low' | 'high';
-type LangChainMessageContentText = {
-    type: 'text';
-    text: string;
-};
-type LangChainMessageContentImageUrl = {
-    type: 'image_url';
-    image_url: string | {
-        url: string;
-        detail?: LangChainImageDetail;
-    };
-};
-type LangChainMessageContentComplex = LangChainMessageContentText | LangChainMessageContentImageUrl | (Record<string, any> & {
-    type?: 'text' | 'image_url' | string;
-}) | (Record<string, any> & {
-    type?: never;
-});
-type LangChainMessageContent = string | LangChainMessageContentComplex[];
-type LangChainAIMessageChunk = {
-    content: LangChainMessageContent;
-};
-type LangChainStreamEvent = {
-    event: string;
-    data: any;
-};
 /**
-Converts LangChain output streams to an AI SDK Data Stream.
+ * Converts AI SDK UIMessages to LangChain BaseMessage objects.
+ *
+ * This function transforms the AI SDK's message format into LangChain's message
+ * format, enabling seamless integration between the two frameworks.
+ *
+ * @param messages - Array of AI SDK UIMessage objects to convert.
+ * @returns Promise resolving to an array of LangChain BaseMessage objects.
+ *
+ * @example
+ * ```ts
+ * import { toBaseMessages } from '@ai-sdk/langchain';
+ *
+ * const langchainMessages = await toBaseMessages(uiMessages);
+ *
+ * // Use with LangChain
+ * const response = await model.invoke(langchainMessages);
+ * ```
+ */
+declare function toBaseMessages(messages: UIMessage[]): Promise<BaseMessage[]>;
+/**
+ * Converts ModelMessages to LangChain BaseMessage objects.
+ *
+ * @param modelMessages - Array of ModelMessage objects from convertToModelMessages.
+ * @returns Array of LangChain BaseMessage objects.
+ */
+declare function convertModelMessages(modelMessages: ModelMessage[]): BaseMessage[];
+/**
+ * Converts a LangChain stream to an AI SDK UIMessageStream.
+ *
+ * This function automatically detects the stream type and handles both:
+ * - Direct model streams (AsyncIterable from `model.stream()`)
+ * - LangGraph streams (ReadableStream with `streamMode: ['values', 'messages']`)
+ *
+ * @param stream - A stream from LangChain model.stream() or LangGraph graph.stream().
+ * @param callbacks - Optional callbacks for stream lifecycle events.
+ * @returns A ReadableStream of UIMessageChunk objects.
+ *
+ * @example
+ * ```ts
+ * // With a direct model stream
+ * const model = new ChatOpenAI({ model: 'gpt-4o-mini' });
+ * const stream = await model.stream(messages);
+ * return createUIMessageStreamResponse({
+ *   stream: toUIMessageStream(stream),
+ * });
+ *
+ * // With a LangGraph stream
+ * const graphStream = await graph.stream(
+ *   { messages },
+ *   { streamMode: ['values', 'messages'] }
+ * );
+ * return createUIMessageStreamResponse({
+ *   stream: toUIMessageStream(graphStream),
+ * });
+ * ```
+ */
+declare function toUIMessageStream(stream: AsyncIterable<AIMessageChunk> | ReadableStream, callbacks?: StreamCallbacks): ReadableStream<UIMessageChunk>;
 
-The following streams are supported:
-- `LangChainAIMessageChunk` streams (LangChain `model.stream` output)
-- `string` streams (LangChain `StringOutputParser` output)
+/**
+ * Options for configuring a LangSmith deployment transport.
+ * Extends RemoteGraphParams but makes graphId optional (defaults to 'agent').
  */
-declare function toUIMessageStream(stream: ReadableStream<LangChainStreamEvent> | ReadableStream<LangChainAIMessageChunk> | ReadableStream<string>, callbacks?: StreamCallbacks): ReadableStream<UIMessageChunk>;
+type LangSmithDeploymentTransportOptions = Omit<RemoteGraphParams, 'graphId'> & {
+    /**
+     * The ID of the graph to connect to.
+     * @default 'agent'
+     */
+    graphId?: string;
+};
+/**
+ * A ChatTransport implementation for LangSmith/LangGraph deployments.
+ *
+ * This transport enables seamless integration between the AI SDK's useChat hook
+ * and LangSmith deployed LangGraph agents.
+ *
+ * @example
+ * ```ts
+ * import { LangSmithDeploymentTransport } from '@ai-sdk/langchain';
+ *
+ * // Use with useChat
+ * const { messages, input, handleSubmit } = useChat({
+ *   transport: new LangSmithDeploymentTransport({
+ *     url: 'https://your-deployment.us.langgraph.app',
+ *     apiKey: 'my-api-key',
+ *   }),
+ * });
+ * ```
+ */
+declare class LangSmithDeploymentTransport<UI_MESSAGE extends UIMessage> implements ChatTransport<UI_MESSAGE> {
+    protected graph: RemoteGraph;
+    constructor(options: LangSmithDeploymentTransportOptions);
+    sendMessages(options: {
+        trigger: 'submit-message' | 'regenerate-message';
+        chatId: string;
+        messageId: string | undefined;
+        messages: UI_MESSAGE[];
+        abortSignal: AbortSignal | undefined;
+    } & ChatRequestOptions): Promise<ReadableStream<UIMessageChunk>>;
+    reconnectToStream(_options: {
+        chatId: string;
+    } & ChatRequestOptions): Promise<ReadableStream<UIMessageChunk> | null>;
+}
 
-export { toUIMessageStream };
+export { LangSmithDeploymentTransport, type LangSmithDeploymentTransportOptions, type StreamCallbacks, convertModelMessages, toBaseMessages, toUIMessageStream };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-import { UIMessageChunk } from 'ai';
+import { BaseMessage, AIMessageChunk } from '@langchain/core/messages';
+import { UIMessage, UIMessageChunk, ModelMessage, ChatTransport, ChatRequestOptions } from 'ai';
+import { RemoteGraph, RemoteGraphParams } from '@langchain/langgraph/remote';
 
 /**
  * Configuration options and helper callback methods for stream lifecycle events.
@@ -14,38 +16,108 @@ interface StreamCallbacks {
     onText?: (text: string) => Promise<void> | void;
 }
 
-type LangChainImageDetail = 'auto' | 'low' | 'high';
-type LangChainMessageContentText = {
-    type: 'text';
-    text: string;
-};
-type LangChainMessageContentImageUrl = {
-    type: 'image_url';
-    image_url: string | {
-        url: string;
-        detail?: LangChainImageDetail;
-    };
-};
-type LangChainMessageContentComplex = LangChainMessageContentText | LangChainMessageContentImageUrl | (Record<string, any> & {
-    type?: 'text' | 'image_url' | string;
-}) | (Record<string, any> & {
-    type?: never;
-});
-type LangChainMessageContent = string | LangChainMessageContentComplex[];
-type LangChainAIMessageChunk = {
-    content: LangChainMessageContent;
-};
-type LangChainStreamEvent = {
-    event: string;
-    data: any;
-};
 /**
-Converts LangChain output streams to an AI SDK Data Stream.
+ * Converts AI SDK UIMessages to LangChain BaseMessage objects.
+ *
+ * This function transforms the AI SDK's message format into LangChain's message
+ * format, enabling seamless integration between the two frameworks.
+ *
+ * @param messages - Array of AI SDK UIMessage objects to convert.
+ * @returns Promise resolving to an array of LangChain BaseMessage objects.
+ *
+ * @example
+ * ```ts
+ * import { toBaseMessages } from '@ai-sdk/langchain';
+ *
+ * const langchainMessages = await toBaseMessages(uiMessages);
+ *
+ * // Use with LangChain
+ * const response = await model.invoke(langchainMessages);
+ * ```
+ */
+declare function toBaseMessages(messages: UIMessage[]): Promise<BaseMessage[]>;
+/**
+ * Converts ModelMessages to LangChain BaseMessage objects.
+ *
+ * @param modelMessages - Array of ModelMessage objects from convertToModelMessages.
+ * @returns Array of LangChain BaseMessage objects.
+ */
+declare function convertModelMessages(modelMessages: ModelMessage[]): BaseMessage[];
+/**
+ * Converts a LangChain stream to an AI SDK UIMessageStream.
+ *
+ * This function automatically detects the stream type and handles both:
+ * - Direct model streams (AsyncIterable from `model.stream()`)
+ * - LangGraph streams (ReadableStream with `streamMode: ['values', 'messages']`)
+ *
+ * @param stream - A stream from LangChain model.stream() or LangGraph graph.stream().
+ * @param callbacks - Optional callbacks for stream lifecycle events.
+ * @returns A ReadableStream of UIMessageChunk objects.
+ *
+ * @example
+ * ```ts
+ * // With a direct model stream
+ * const model = new ChatOpenAI({ model: 'gpt-4o-mini' });
+ * const stream = await model.stream(messages);
+ * return createUIMessageStreamResponse({
+ *   stream: toUIMessageStream(stream),
+ * });
+ *
+ * // With a LangGraph stream
+ * const graphStream = await graph.stream(
+ *   { messages },
+ *   { streamMode: ['values', 'messages'] }
+ * );
+ * return createUIMessageStreamResponse({
+ *   stream: toUIMessageStream(graphStream),
+ * });
+ * ```
+ */
+declare function toUIMessageStream(stream: AsyncIterable<AIMessageChunk> | ReadableStream, callbacks?: StreamCallbacks): ReadableStream<UIMessageChunk>;
 
-The following streams are supported:
-- `LangChainAIMessageChunk` streams (LangChain `model.stream` output)
-- `string` streams (LangChain `StringOutputParser` output)
+/**
+ * Options for configuring a LangSmith deployment transport.
+ * Extends RemoteGraphParams but makes graphId optional (defaults to 'agent').
  */
-declare function toUIMessageStream(stream: ReadableStream<LangChainStreamEvent> | ReadableStream<LangChainAIMessageChunk> | ReadableStream<string>, callbacks?: StreamCallbacks): ReadableStream<UIMessageChunk>;
+type LangSmithDeploymentTransportOptions = Omit<RemoteGraphParams, 'graphId'> & {
+    /**
+     * The ID of the graph to connect to.
+     * @default 'agent'
+     */
+    graphId?: string;
+};
+/**
+ * A ChatTransport implementation for LangSmith/LangGraph deployments.
+ *
+ * This transport enables seamless integration between the AI SDK's useChat hook
+ * and LangSmith deployed LangGraph agents.
+ *
+ * @example
+ * ```ts
+ * import { LangSmithDeploymentTransport } from '@ai-sdk/langchain';
+ *
+ * // Use with useChat
+ * const { messages, input, handleSubmit } = useChat({
+ *   transport: new LangSmithDeploymentTransport({
+ *     url: 'https://your-deployment.us.langgraph.app',
+ *     apiKey: 'my-api-key',
+ *   }),
+ * });
+ * ```
+ */
+declare class LangSmithDeploymentTransport<UI_MESSAGE extends UIMessage> implements ChatTransport<UI_MESSAGE> {
+    protected graph: RemoteGraph;
+    constructor(options: LangSmithDeploymentTransportOptions);
+    sendMessages(options: {
+        trigger: 'submit-message' | 'regenerate-message';
+        chatId: string;
+        messageId: string | undefined;
+        messages: UI_MESSAGE[];
+        abortSignal: AbortSignal | undefined;
+    } & ChatRequestOptions): Promise<ReadableStream<UIMessageChunk>>;
+    reconnectToStream(_options: {
+        chatId: string;
+    } & ChatRequestOptions): Promise<ReadableStream<UIMessageChunk> | null>;
+}
 
-export { toUIMessageStream };
+export { LangSmithDeploymentTransport, type LangSmithDeploymentTransportOptions, type StreamCallbacks, convertModelMessages, toBaseMessages, toUIMessageStream };