@ai-sdk/langchain 0.0.0-02dba89b-20251009204516 → 0.0.0-17394c74-20260122151521

package/src/adapter.ts

@@ -0,0 +1,520 @@
+import {
+  SystemMessage,
+  BaseMessage,
+  AIMessageChunk,
+} from '@langchain/core/messages';
+import {
+  type UIMessage,
+  type UIMessageChunk,
+  convertToModelMessages,
+  type ModelMessage,
+} from 'ai';
+import {
+  convertToolResultPart,
+  convertAssistantContent,
+  convertUserContent,
+  processModelChunk,
+  processLangGraphEvent,
+  isToolResultPart,
+  extractReasoningFromContentBlocks,
+} from './utils';
+import { type LangGraphEventState } from './types';
+import { type StreamCallbacks } from './stream-callbacks';
+
+/**
+ * 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);
+ * ```
+ */
+export async function toBaseMessages(
+  messages: UIMessage[],
+): Promise<BaseMessage[]> {
+  const modelMessages = await convertToModelMessages(messages);
+  return convertModelMessages(modelMessages);
+}
+
+/**
+ * Converts ModelMessages to LangChain BaseMessage objects.
+ *
+ * @param modelMessages - Array of ModelMessage objects from convertToModelMessages.
+ * @returns Array of LangChain BaseMessage objects.
+ */
+export function convertModelMessages(
+  modelMessages: ModelMessage[],
+): BaseMessage[] {
+  const result: BaseMessage[] = [];
+
+  for (const message of modelMessages) {
+    switch (message.role) {
+      case 'tool': {
+        // Tool messages contain an array of tool results
+        for (const item of message.content) {
+          if (isToolResultPart(item)) {
+            result.push(convertToolResultPart(item));
+          }
+        }
+        break;
+      }
+
+      case 'assistant': {
+        result.push(convertAssistantContent(message.content));
+        break;
+      }
+
+      case 'system': {
+        result.push(new SystemMessage({ content: message.content }));
+        break;
+      }
+
+      case 'user': {
+        result.push(convertUserContent(message.content));
+        break;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Type guard to check if a value is a streamEvents event object.
+ * streamEvents produces objects with `event` and `data` properties.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a streamEvents event object.
+ */
+function isStreamEventsEvent(
+  value: unknown,
+): value is { event: string; data: Record<string, unknown> } {
+  if (value == null || typeof value !== 'object') return false;
+  const obj = value as Record<string, unknown>;
+  // Check for event property being a string
+  if (!('event' in obj) || typeof obj.event !== 'string') return false;
+  // Check for data property being an object (but allow null/undefined)
+  if (!('data' in obj)) return false;
+  // data can be null in some events, treat as empty object
+  return obj.data === null || typeof obj.data === 'object';
+}
+
+/**
+ * Processes a streamEvents event and emits UI message chunks.
+ *
+ * @param event - The streamEvents event to process.
+ * @param state - The state for tracking stream progress.
+ * @param controller - The controller to emit UI message chunks.
+ */
+function processStreamEventsEvent(
+  event: {
+    event: string;
+    data: Record<string, unknown> | null;
+    run_id?: string;
+    name?: string;
+  },
+  state: {
+    started: boolean;
+    messageId: string;
+    reasoningStarted: boolean;
+    textStarted: boolean;
+    textMessageId: string | null;
+    reasoningMessageId: string | null;
+  },
+  controller: ReadableStreamDefaultController<UIMessageChunk>,
+): void {
+  /**
+   * Capture run_id from event level if available (streamEvents v2 format)
+   */
+  if (event.run_id && !state.started) {
+    state.messageId = event.run_id;
+  }
+
+  /**
+   * Skip events with null/undefined data
+   */
+  if (!event.data) return;
+
+  switch (event.event) {
+    case 'on_chat_model_start': {
+      /**
+       * Handle model start - capture message metadata if available
+       * run_id is at event level in v2, but check data for backwards compatibility
+       */
+      const runId = event.run_id || (event.data.run_id as string | undefined);
+      if (runId) {
+        state.messageId = runId;
+      }
+      break;
+    }
+
+    case 'on_chat_model_stream': {
+      /**
+       * Handle streaming token chunks
+       */
+      const chunk = event.data.chunk;
+      if (chunk && typeof chunk === 'object') {
+        /**
+         * Get message ID from chunk if available
+         */
+        const chunkId = (chunk as { id?: string }).id;
+        if (chunkId) {
+          state.messageId = chunkId;
+        }
+
+        /**
+         * Handle reasoning content from contentBlocks
+         */
+        const reasoning = extractReasoningFromContentBlocks(chunk);
+        if (reasoning) {
+          if (!state.reasoningStarted) {
+            // Track the ID used for reasoning-start to ensure reasoning-end uses the same ID
+            state.reasoningMessageId = state.messageId;
+            controller.enqueue({
+              type: 'reasoning-start',
+              id: state.messageId,
+            });
+            state.reasoningStarted = true;
+            state.started = true;
+          }
+          controller.enqueue({
+            type: 'reasoning-delta',
+            delta: reasoning,
+            id: state.reasoningMessageId ?? state.messageId,
+          });
+        }
+
+        /**
+         * Extract text content from chunk
+         */
+        const content = (chunk as { content?: unknown }).content;
+        const text =
+          typeof content === 'string'
+            ? content
+            : Array.isArray(content)
+              ? content
+                  .filter(
+                    (c): c is { type: 'text'; text: string } =>
+                      typeof c === 'object' &&
+                      c !== null &&
+                      'type' in c &&
+                      c.type === 'text',
+                  )
+                  .map(c => c.text)
+                  .join('')
+              : '';
+
+        if (text) {
+          /**
+           * If reasoning was streamed before text, close reasoning first
+           */
+          if (state.reasoningStarted && !state.textStarted) {
+            controller.enqueue({
+              type: 'reasoning-end',
+              id: state.reasoningMessageId ?? state.messageId,
+            });
+            state.reasoningStarted = false;
+          }
+
+          if (!state.textStarted) {
+            // Track the ID used for text-start to ensure text-end uses the same ID
+            state.textMessageId = state.messageId;
+            controller.enqueue({ type: 'text-start', id: state.messageId });
+            state.textStarted = true;
+            state.started = true;
+          }
+          controller.enqueue({
+            type: 'text-delta',
+            delta: text,
+            id: state.textMessageId ?? state.messageId,
+          });
+        }
+      }
+      break;
+    }
+
+    case 'on_tool_start': {
+      /**
+       * Handle tool call start
+       * run_id and name are at event level in v2, check data for backwards compatibility
+       */
+      const runId = event.run_id || (event.data.run_id as string | undefined);
+      const name = event.name || (event.data.name as string | undefined);
+
+      if (runId && name) {
+        controller.enqueue({
+          type: 'tool-input-start',
+          toolCallId: runId,
+          toolName: name,
+          dynamic: true,
+        });
+      }
+      break;
+    }
+
+    case 'on_tool_end': {
+      /**
+       * Handle tool call end
+       * run_id is at event level in v2, check data for backwards compatibility
+       */
+      const runId = event.run_id || (event.data.run_id as string | undefined);
+      const output = event.data.output;
+
+      if (runId) {
+        controller.enqueue({
+          type: 'tool-output-available',
+          toolCallId: runId,
+          output,
+        });
+      }
+      break;
+    }
+  }
+}
+
+/**
+ * Converts a LangChain stream to an AI SDK UIMessageStream.
+ *
+ * This function automatically detects the stream type and handles:
+ * - Direct model streams (AsyncIterable from `model.stream()`)
+ * - LangGraph streams (ReadableStream with `streamMode: ['values', 'messages']`)
+ * - streamEvents streams (from `agent.streamEvents()` or `model.streamEvents()`)
+ *
+ * @param stream - A stream from LangChain model.stream(), graph.stream(), or streamEvents().
+ * @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),
+ * });
+ *
+ * // With streamEvents
+ * const streamEvents = agent.streamEvents(
+ *   { messages },
+ *   { version: "v2" }
+ * );
+ * return createUIMessageStreamResponse({
+ *   stream: toUIMessageStream(streamEvents),
+ * });
+ * ```
+ */
+export function toUIMessageStream(
+  stream: AsyncIterable<AIMessageChunk> | ReadableStream,
+  callbacks?: StreamCallbacks,
+): ReadableStream<UIMessageChunk> {
+  /**
+   * Track text chunks for onFinal callback
+   */
+  const textChunks: string[] = [];
+
+  /**
+   * State for model stream handling
+   */
+  const modelState = {
+    started: false,
+    messageId: 'langchain-msg-1',
+    reasoningStarted: false,
+    textStarted: false,
+    /** Track the ID used for text-start to ensure text-end uses the same ID */
+    textMessageId: null as string | null,
+    /** Track the ID used for reasoning-start to ensure reasoning-end uses the same ID */
+    reasoningMessageId: null as string | null,
+  };
+
+  /**
+   * State for LangGraph stream handling
+   */
+  const langGraphState: LangGraphEventState = {
+    messageSeen: {} as Record<
+      string,
+      { text?: boolean; reasoning?: boolean; tool?: Record<string, boolean> }
+    >,
+    messageConcat: {} as Record<string, AIMessageChunk>,
+    emittedToolCalls: new Set<string>(),
+    emittedImages: new Set<string>(),
+    emittedReasoningIds: new Set<string>(),
+    messageReasoningIds: {} as Record<string, string>,
+    toolCallInfoByIndex: {} as Record<
+      string,
+      Record<number, { id: string; name: string }>
+    >,
+    currentStep: null as number | null,
+    emittedToolCallsByKey: new Map<string, string>(),
+  };
+
+  /**
+   * Track detected stream type: null = not yet detected
+   */
+  let streamType: 'model' | 'langgraph' | 'streamEvents' | null = null;
+
+  /**
+   * Get async iterator from the stream (works for both AsyncIterable and ReadableStream)
+   */
+  const getAsyncIterator = (): AsyncIterator<unknown> => {
+    if (Symbol.asyncIterator in stream) {
+      return (stream as AsyncIterable<unknown>)[Symbol.asyncIterator]();
+    }
+    /**
+     * For ReadableStream without Symbol.asyncIterator
+     */
+    const reader = (stream as ReadableStream).getReader();
+    return {
+      async next() {
+        const { done, value } = await reader.read();
+        return { done, value };
+      },
+    };
+  };
+
+  const iterator = getAsyncIterator();
+
+  /**
+   * Create a wrapper around the controller to intercept text chunks for callbacks
+   */
+  const createCallbackController = (
+    originalController: ReadableStreamDefaultController<UIMessageChunk>,
+  ): ReadableStreamDefaultController<UIMessageChunk> => {
+    return {
+      get desiredSize() {
+        return originalController.desiredSize;
+      },
+      close: () => originalController.close(),
+      error: (e?: unknown) => originalController.error(e),
+      enqueue: (chunk: UIMessageChunk) => {
+        /**
+         * Intercept text-delta chunks for callbacks
+         */
+        if (callbacks && chunk.type === 'text-delta' && chunk.delta) {
+          textChunks.push(chunk.delta);
+          callbacks.onToken?.(chunk.delta);
+          callbacks.onText?.(chunk.delta);
+        }
+        originalController.enqueue(chunk);
+      },
+    };
+  };
+
+  return new ReadableStream<UIMessageChunk>({
+    async start(controller) {
+      await callbacks?.onStart?.();
+
+      const wrappedController = createCallbackController(controller);
+      controller.enqueue({ type: 'start' });
+
+      try {
+        while (true) {
+          const { done, value } = await iterator.next();
+          if (done) break;
+
+          /**
+           * Detect stream type on first value
+           */
+          if (streamType === null) {
+            if (Array.isArray(value)) {
+              streamType = 'langgraph';
+            } else if (isStreamEventsEvent(value)) {
+              streamType = 'streamEvents';
+            } else {
+              streamType = 'model';
+            }
+          }
+
+          /**
+           * Process based on detected type
+           */
+          if (streamType === 'model') {
+            processModelChunk(
+              value as AIMessageChunk,
+              modelState,
+              wrappedController,
+            );
+          } else if (streamType === 'streamEvents') {
+            processStreamEventsEvent(
+              value as {
+                event: string;
+                data: Record<string, unknown> | null;
+                run_id?: string;
+                name?: string;
+              },
+              modelState,
+              wrappedController,
+            );
+          } else {
+            processLangGraphEvent(
+              value as unknown[],
+              langGraphState,
+              wrappedController,
+            );
+          }
+        }
+
+        /**
+         * Finalize based on stream type
+         */
+        if (streamType === 'model' || streamType === 'streamEvents') {
+          if (modelState.reasoningStarted) {
+            controller.enqueue({
+              type: 'reasoning-end',
+              id: modelState.reasoningMessageId ?? modelState.messageId,
+            });
+          }
+          if (modelState.textStarted) {
+            /**
+             * Use the same ID that was used for text-start
+             */
+            controller.enqueue({
+              type: 'text-end',
+              id: modelState.textMessageId ?? modelState.messageId,
+            });
+          }
+          controller.enqueue({ type: 'finish' });
+        } else if (streamType === 'langgraph') {
+          /**
+           * Emit finish-step if a step was started
+           */
+          if (langGraphState.currentStep !== null) {
+            controller.enqueue({ type: 'finish-step' });
+          }
+          controller.enqueue({ type: 'finish' });
+        }
+
+        /**
+         * Call onFinal callback with aggregated text
+         */
+        await callbacks?.onFinal?.(textChunks.join(''));
+      } catch (error) {
+        controller.enqueue({
+          type: 'error',
+          errorText: error instanceof Error ? error.message : 'Unknown error',
+        });
+      } finally {
+        controller.close();
+      }
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export {
+  toBaseMessages,
+  toUIMessageStream,
+  convertModelMessages,
+} from './adapter';
+
+export {
+  LangSmithDeploymentTransport,
+  type LangSmithDeploymentTransportOptions,
+} from './transport';
+
+export { type StreamCallbacks } from './stream-callbacks';

package/src/stream-callbacks.ts

@@ -0,0 +1,65 @@
+/**
+ * Configuration options and helper callback methods for stream lifecycle events.
+ */
+export interface StreamCallbacks {
+  /** `onStart`: Called once when the stream is initialized. */
+  onStart?: () => Promise<void> | void;
+
+  /** `onFinal`: Called once when the stream is closed with the final completion message. */
+  onFinal?: (completion: string) => Promise<void> | void;
+
+  /** `onToken`: Called for each tokenized message. */
+  onToken?: (token: string) => Promise<void> | void;
+
+  /** `onText`: Called for each text chunk. */
+  onText?: (text: string) => Promise<void> | void;
+}
+
+/**
+ * Creates a transform stream that encodes input messages and invokes optional callback functions.
+ * The transform stream uses the provided callbacks to execute custom logic at different stages of the stream's lifecycle.
+ * - `onStart`: Called once when the stream is initialized.
+ * - `onToken`: Called for each tokenized message.
+ * - `onFinal`: Called once when the stream is closed with the final completion message.
+ *
+ * This function is useful when you want to process a stream of messages and perform specific actions during the stream's lifecycle.
+ *
+ * @param {StreamCallbacks} [callbacks] - An object containing the callback functions.
+ * @return {TransformStream<string, string>} A transform stream that allows the execution of custom logic through callbacks.
+ *
+ * @example
+ * const callbacks = {
+ *   onStart: async () => console.log('Stream started'),
+ *   onToken: async (token) => console.log(`Token: ${token}`),
+ *   onFinal: async () => data.close()
+ * };
+ * const transformer = createCallbacksTransformer(callbacks);
+ */
+export function createCallbacksTransformer(
+  callbacks: StreamCallbacks | undefined = {},
+): TransformStream<string, string> {
+  let aggregatedResponse = '';
+
+  return new TransformStream({
+    async start(): Promise<void> {
+      if (callbacks.onStart) await callbacks.onStart();
+    },
+
+    async transform(message, controller): Promise<void> {
+      controller.enqueue(message);
+
+      aggregatedResponse += message;
+
+      if (callbacks.onToken) await callbacks.onToken(message);
+      if (callbacks.onText && typeof message === 'string') {
+        await callbacks.onText(message);
+      }
+    },
+
+    async flush(): Promise<void> {
+      if (callbacks.onFinal) {
+        await callbacks.onFinal(aggregatedResponse);
+      }
+    },
+  });
+}

package/src/transport.ts

@@ -0,0 +1,88 @@
+import { AIMessageChunk } from '@langchain/core/messages';
+import {
+  type UIMessage,
+  type UIMessageChunk,
+  type ChatTransport,
+  type ChatRequestOptions,
+} from 'ai';
+import {
+  RemoteGraph,
+  type RemoteGraphParams,
+} from '@langchain/langgraph/remote';
+import { toBaseMessages, toUIMessageStream } from './adapter';
+
+/**
+ * Options for configuring a LangSmith deployment transport.
+ * Extends RemoteGraphParams but makes graphId optional (defaults to 'agent').
+ */
+export 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',
+ *   }),
+ * });
+ * ```
+ */
+export class LangSmithDeploymentTransport<UI_MESSAGE extends UIMessage>
+  implements ChatTransport<UI_MESSAGE>
+{
+  protected graph: RemoteGraph;
+
+  constructor(options: LangSmithDeploymentTransportOptions) {
+    this.graph = new RemoteGraph({
+      ...options,
+      graphId: options.graphId ?? 'agent',
+    });
+  }
+
+  async sendMessages(
+    options: {
+      trigger: 'submit-message' | 'regenerate-message';
+      chatId: string;
+      messageId: string | undefined;
+      messages: UI_MESSAGE[];
+      abortSignal: AbortSignal | undefined;
+    } & ChatRequestOptions,
+  ): Promise<ReadableStream<UIMessageChunk>> {
+    const baseMessages = await toBaseMessages(options.messages);
+
+    const stream = await this.graph.stream(
+      { messages: baseMessages },
+      { streamMode: ['values', 'messages'] },
+    );
+
+    return toUIMessageStream(
+      stream as AsyncIterable<AIMessageChunk> | ReadableStream,
+    );
+  }
+
+  async reconnectToStream(
+    _options: {
+      chatId: string;
+    } & ChatRequestOptions,
+  ): Promise<ReadableStream<UIMessageChunk> | null> {
+    throw new Error('Method not implemented.');
+  }
+}