Skip to content

The Open Standard for Generative UI

14.1 KB
Raw Blame
import { EventType, type AGUIEvent } from "@ag-ui/core";
import type { ProtocolEvent, StreamTransformer, ToolsEventData } from "@langchain/langgraph";
import { StreamChannel } from "@langchain/langgraph";
import type { ContentBlock, MessagesData } from "@langchain/protocol";

import { createId } from "./id";

const OPENUI_CHANNEL_NAME = "openui";
const OPENUI_CHANNEL_METHOD = `custom:${OPENUI_CHANNEL_NAME}`;

const TOOL_BLOCK_TYPES = new Set([
  "tool_call",
  "tool_call_chunk",
  "server_tool_call",
  "server_tool_call_chunk",
]);

/** Provider-executed tool results (Cloud artifacts, search, MCP). */
const TOOL_RESULT_BLOCK_TYPES = new Set(["server_tool_call_result", "server_tool_result"]);

interface ToolCallState {
  id: string;
  name: string;
  started: boolean;
  ended: boolean;
  argsEmitted: boolean;
  /** Args already emitted as AG-UI deltas — used to diff snapshot-style updates. */
  argsEmittedSoFar: string;
}

/**
 * Projects LangGraph's protocol-v2 `messages` and `tools` streams into AG-UI
 * events and publishes them on the remote `custom:openui` channel.
 *
 * Add the returned factory to an agent's `streamTransformers` array. Remote
 * clients can then subscribe to `custom:openui`, or use {@link streamOpenUI}
 * and {@link createLangChainStreamResponse} to relay that channel as AG-UI
 * Server-Sent Events.
 *
 * Provider-executed Cloud tools (artifacts, search, MCP) never hit LangGraph's
 * `tools` channel. ChatOpenAI surfaces their `function_call_output` as
 * passthrough `provider` events (or occasionally as `server_tool_*_result`
 * content blocks). Those are mapped to `TOOL_CALL_RESULT` here so the browser
 * can render artifact previews live — without waiting for a storage reload.
 */
export function openUIStreamTransformer(): StreamTransformer<{
  openui: StreamChannel<AGUIEvent>;
}> {
  const channel = StreamChannel.remote<AGUIEvent>(OPENUI_CHANNEL_NAME);

  let currentMessageId: string = createId();
  let acceptsCurrentMessage = false;
  let textMessageId: string | undefined;
  let textStarted = false;
  let textEnded = false;
  let runErrorEmitted = false;

  const toolCallsByIndex = new Map<string, ToolCallState>();
  const toolOutputByCallId = new Map<string, string>();
  // Dedup across tools-channel + provider `added`/`done` + content-block paths.
  const emittedToolResultIds = new Set<string>();

  const emit = (event: AGUIEvent) => channel.push(event);

  const ensureTextStart = () => {
    if (textStarted) return;
    textMessageId = currentMessageId;
    emit({
      type: EventType.TEXT_MESSAGE_START,
      messageId: textMessageId,
      role: "assistant",
    });
    textStarted = true;
  };

  const emitTextDelta = (delta: string) => {
    if (!delta) return;
    ensureTextStart();
    emit({
      type: EventType.TEXT_MESSAGE_CONTENT,
      messageId: textMessageId ?? currentMessageId,
      delta,
    });
  };

  const endText = () => {
    if (!textStarted || textEnded) return;
    emit({
      type: EventType.TEXT_MESSAGE_END,
      messageId: textMessageId ?? currentMessageId,
    });
    textEnded = true;
  };

  const syncToolCall = (
    index: number | string,
    block: Partial<ContentBlock> & Record<string, unknown>,
    emitArgs: boolean,
  ): ToolCallState => {
    const key = String(index);
    let state = toolCallsByIndex.get(key);

    if (!state) {
      state = {
        id: getToolCallId(block) ?? `tool-${key}`,
        name: getToolCallName(block) ?? "",
        started: false,
        ended: false,
        argsEmitted: false,
        argsEmittedSoFar: "",
      };
      toolCallsByIndex.set(key, state);
    } else if (!state.started) {
      state.id = getToolCallId(block) ?? state.id;
      state.name = getToolCallName(block) ?? state.name;
    }

    if (state.ended) return state;

    if (!state.started && state.name) {
      emit({
        type: EventType.TOOL_CALL_START,
        toolCallId: state.id,
        toolCallName: state.name,
      });
      state.started = true;
    }

    const args = getArgsString(block);
    if (emitArgs && args && state.started) {
      // ChatOpenAI Responses stream sends the FULL accumulated args string on
      // every block-delta. AG-UI TOOL_CALL_ARGS deltas are append-only, so
      // re-emitting the snapshot would corrupt JSON (and blank Cloud artifact
      // previews that parse artifact_content from args). Emit only the suffix.
      const delta = args.startsWith(state.argsEmittedSoFar)
        ? args.slice(state.argsEmittedSoFar.length)
        : args;
      if (delta) {
        emit({
          type: EventType.TOOL_CALL_ARGS,
          toolCallId: state.id,
          delta,
        });
        state.argsEmittedSoFar = args.startsWith(state.argsEmittedSoFar)
          ? args
          : state.argsEmittedSoFar + args;
        state.argsEmitted = true;
      }
    }

    return state;
  };

  const endToolCall = (state: ToolCallState) => {
    if (state.ended || !state.started) return;
    emit({ type: EventType.TOOL_CALL_END, toolCallId: state.id });
    state.ended = true;
  };

  const endAllToolCalls = () => {
    for (const state of toolCallsByIndex.values()) endToolCall(state);
  };

  const endToolCallById = (toolCallId: string) => {
    const state = Array.from(toolCallsByIndex.values()).find(({ id }) => id === toolCallId);
    if (state) endToolCall(state);
  };

  const emitToolResult = (
    toolCallId: string,
    content: string,
    options?: { isError?: boolean; error?: string; messageId?: string },
  ) => {
    if (!toolCallId || emittedToolResultIds.has(toolCallId)) return;
    emittedToolResultIds.add(toolCallId);
    endToolCallById(toolCallId);
    emit({
      type: EventType.TOOL_CALL_RESULT,
      messageId: options?.messageId ?? `tool-result-${toolCallId}`,
      toolCallId,
      content,
      role: "tool",
      ...(options?.isError ? { isError: true, error: options.error ?? content } : {}),
    });
  };

  const emitServerToolResultBlock = (block: Partial<ContentBlock> & Record<string, unknown>) => {
    const toolCallId = getServerToolResultCallId(block);
    if (!toolCallId) return;
    const isError = block.status === "error";
    emitToolResult(toolCallId, serializeToolOutput(block.output), {
      isError,
      ...(isError ? { error: serializeToolOutput(block.output) } : {}),
    });
  };

  const emitProviderFunctionCallOutput = (payload: unknown) => {
    const item = getFunctionCallOutputItem(payload);
    if (!item) return;
    emitToolResult(item.call_id, serializeToolOutput(item.output), {
      messageId: item.id ?? `tool-result-${item.call_id}`,
    });
  };

  const resetMessage = (data: Extract<MessagesData, { event: "message-start" }>) => {
    endAllToolCalls();
    endText();

    currentMessageId = data.id || createId();
    // StreamProtocolMessagesHandler intentionally omits `role` only for live
    // AI model output and attaches its model run id. Replayed human/system/tool
    // messages always carry an explicit role. Requiring that run id keeps the
    // compatibility path from failing open for arbitrary role-less messages.
    const { role: runtimeRole, run_id: runtimeRunId } = data as {
      role?: unknown;
      run_id?: unknown;
    };
    acceptsCurrentMessage =
      runtimeRole === "ai" ||
      runtimeRole === "assistant" ||
      (runtimeRole == null && typeof runtimeRunId === "string" && runtimeRunId.length > 0);
    textMessageId = undefined;
    textStarted = false;
    textEnded = false;
    toolCallsByIndex.clear();
  };

  const processMessages = (data: MessagesData | ProviderMessageEvent) => {
    if (data.event === "message-start") {
      resetMessage(data);
      return;
    }

    if (!acceptsCurrentMessage) return;

    switch (data.event) {
      case "content-block-start": {
        const block = data.content;
        if (isTextBlock(block)) {
          ensureTextStart();
          emitTextDelta(typeof block.text === "string" ? block.text : "");
        } else if (isToolResultBlock(block)) {
          emitServerToolResultBlock(block);
        } else if (isToolBlock(block)) {
          syncToolCall(data.index, block, true);
        }
        return;
      }

      case "content-block-delta": {
        const delta = data.delta;
        if (delta.type === "text-delta") {
          emitTextDelta(typeof delta.text === "string" ? delta.text : "");
        } else if (delta.type === "block-delta") {
          const fields = delta.fields as Partial<ContentBlock> & Record<string, unknown>;
          if (toolCallsByIndex.has(String(data.index)) || isToolBlock(fields)) {
            syncToolCall(data.index, fields, true);
          }
        }
        return;
      }

      case "content-block-finish": {
        const block = data.content;
        if (isToolResultBlock(block)) {
          emitServerToolResultBlock(block);
        } else if (isToolBlock(block)) {
          const state = syncToolCall(data.index, block, false);
          if (!state.argsEmitted) {
            syncToolCall(data.index, block, true);
          }
          endToolCall(state);
        }
        return;
      }

      case "message-finish":
        endAllToolCalls();
        endText();
        return;

      case "error":
        endAllToolCalls();
        emit({ type: EventType.RUN_ERROR, message: data.message });
        runErrorEmitted = true;
        return;

      case "provider":
        // ChatOpenAI's Responses stream maps unknown items (including Cloud
        // function_call_output) to provider passthrough events.
        if (
          data.name === "response.output_item.added" ||
          data.name === "response.output_item.done"
        ) {
          emitProviderFunctionCallOutput(data.payload);
        }
        return;

      default:
        return;
    }
  };

  const processTools = (data: ToolsEventData) => {
    const toolCallId = data.tool_call_id;

    switch (data.event) {
      case "tool-output-delta":
        toolOutputByCallId.set(toolCallId, (toolOutputByCallId.get(toolCallId) ?? "") + data.delta);
        return;

      case "tool-finished": {
        const streamedOutput = toolOutputByCallId.get(toolCallId);
        toolOutputByCallId.delete(toolCallId);
        emitToolResult(toolCallId, serializeToolOutput(data.output, streamedOutput));
        return;
      }

      case "tool-error":
        toolOutputByCallId.delete(toolCallId);
        emitToolResult(toolCallId, data.message, {
          isError: true,
          error: data.message,
        });
        return;

      case "tool-started":
      default:
        return;
    }
  };

  return {
    init: () => ({ openui: channel }),
    process: (event: ProtocolEvent) => {
      // Ignore the events emitted by this transformer to avoid re-entry.
      if (event.method === OPENUI_CHANNEL_METHOD) return true;
      // Do not filter by namespace: DeepAgents emits model and tool events
      // from nested `model_request:*` and `tools:*` namespaces.
      if (event.method === "messages") {
        processMessages(event.params.data as MessagesData | ProviderMessageEvent);
      } else if (event.method === "tools") {
        processTools(event.params.data as ToolsEventData);
      }
      return true;
    },
    finalize: () => {
      endAllToolCalls();
      endText();
    },
    fail: (error) => {
      endAllToolCalls();
      if (!runErrorEmitted) {
        emit({
          type: EventType.RUN_ERROR,
          message: error instanceof Error ? error.message : "LangGraph run failed",
        });
        runErrorEmitted = true;
      }
    },
  };
}

/** ChatOpenAI Responses passthrough — not in MessagesData, but forwarded live. */
interface ProviderMessageEvent {
  event: "provider";
  provider?: string;
  name: string;
  payload: unknown;
}

function serializeToolOutput(output: unknown, streamedOutput?: string): string {
  if (typeof output === "string") return output;
  if (output === undefined && streamedOutput !== undefined) return streamedOutput;
  if (output === undefined) return "";

  try {
    return JSON.stringify(output) ?? String(output);
  } catch {
    return String(output);
  }
}

function isTextBlock(block: Partial<ContentBlock> & Record<string, unknown>): boolean {
  return block.type === "text";
}

function isToolBlock(block: Partial<ContentBlock> & Record<string, unknown>): boolean {
  return typeof block.type === "string" && TOOL_BLOCK_TYPES.has(block.type);
}

function isToolResultBlock(block: Partial<ContentBlock> & Record<string, unknown>): boolean {
  return typeof block.type === "string" && TOOL_RESULT_BLOCK_TYPES.has(block.type);
}

function getToolCallId(block: Partial<ContentBlock> & Record<string, unknown>): string | undefined {
  return typeof block.id === "string" && block.id.length > 0 ? block.id : undefined;
}

function getToolCallName(
  block: Partial<ContentBlock> & Record<string, unknown>,
): string | undefined {
  return typeof block.name === "string" && block.name.length > 0 ? block.name : undefined;
}

function getServerToolResultCallId(
  block: Partial<ContentBlock> & Record<string, unknown>,
): string | undefined {
  // LangChain core uses camelCase; protocol-v2 uses snake_case.
  const camel = block["toolCallId"];
  if (typeof camel === "string" && camel.length > 0) return camel;
  const snake = block["tool_call_id"];
  if (typeof snake === "string" && snake.length > 0) return snake;
  return undefined;
}

function getArgsString(block: Partial<ContentBlock> & Record<string, unknown>): string {
  if (typeof block.args === "string") return block.args;
  if (block.args != null && typeof block.args === "object") return JSON.stringify(block.args);
  return "";
}

function getFunctionCallOutputItem(
  payload: unknown,
): { call_id: string; output: unknown; id?: string } | null {
  if (typeof payload !== "object" || payload === null) return null;
  const item = (payload as { item?: unknown }).item;
  if (typeof item !== "object" || item === null) return null;
  const record = item as { type?: unknown; call_id?: unknown; output?: unknown; id?: unknown };
  if (record.type !== "function_call_output") return null;
  if (typeof record.call_id !== "string" || record.call_id.length === 0) return null;
  return {
    call_id: record.call_id,
    output: record.output,
    ...(typeof record.id === "string" && record.id.length > 0 ? { id: record.id } : {}),
  };
}