feat: langgraph interrupt hook (CopilotKit#1273)

Author: ranst91

CopilotKit/.changeset/large-laws-reply.md

@@ -0,0 +1,11 @@
+---
+"@copilotkit/react-core": patch
+"@copilotkit/react-ui": patch
+"@copilotkit/runtime-client-gql": patch
+"@copilotkit/runtime": patch
+"@copilotkit/shared": patch
+---
+
+- feat(interrupt): support LG interrupt with useLangGraphInterrupt hook
+- chore(interrupt): add e2e test to interrupt functionality
+- feat(interrupt): add support for multiple interrupts and conditions

CopilotKit/packages/react-core/src/components/copilot-provider/copilotkit.tsx

@@ -45,6 +45,10 @@ import { useCopilotRuntimeClient } from "../../hooks/use-copilot-runtime-client"
 import { shouldShowDevConsole } from "../../utils";
 import { CopilotErrorBoundary } from "../error-boundary/error-boundary";
 import { Agent, ExtensionsInput } from "@copilotkit/runtime-client-gql";
+import {
+  LangGraphInterruptAction,
+  LangGraphInterruptActionSetterArgs,
+} from "../../types/interrupt-action";
 
 export function CopilotKit({ children, ...props }: CopilotKitProps) {
   const showDevConsole = props.showDevConsole === undefined ? "auto" : props.showDevConsole;
@@ -337,6 +341,24 @@ export function CopilotKitInternal(cpkProps: CopilotKitProps) {
 
   const showDevConsole = props.showDevConsole === undefined ? "auto" : props.showDevConsole;
 
+  const [langGraphInterruptAction, _setLangGraphInterruptAction] =
+    useState<LangGraphInterruptAction | null>(null);
+  const setLangGraphInterruptAction = useCallback((action: LangGraphInterruptActionSetterArgs) => {
+    _setLangGraphInterruptAction((prev) => {
+      if (prev == null) return action as LangGraphInterruptAction;
+      if (action == null) return null;
+      let event = prev.event;
+      if (action.event) {
+        // @ts-ignore
+        event = { ...prev.event, ...action.event };
+      }
+      return { ...prev, ...action, event };
+    });
+  }, []);
+  const removeLangGraphInterruptAction = useCallback((): void => {
+    setLangGraphInterruptAction(null);
+  }, []);
+
   return (
     <CopilotContext.Provider
       value={{
@@ -383,6 +405,9 @@ export function CopilotKitInternal(cpkProps: CopilotKitProps) {
         setAuthStates_c: setAuthStates,
         extensions,
         setExtensions,
+        langGraphInterruptAction,
+        setLangGraphInterruptAction,
+        removeLangGraphInterruptAction,
       }}
     >
       <CopilotMessages>{children}</CopilotMessages>

CopilotKit/packages/react-core/src/context/copilot-context.tsx

@@ -16,6 +16,10 @@ import {
   ForwardedParametersInput,
 } from "@copilotkit/runtime-client-gql";
 import { Agent } from "@copilotkit/runtime-client-gql";
+import {
+  LangGraphInterruptAction,
+  LangGraphInterruptActionSetter,
+} from "../types/interrupt-action";
 
 /**
  * Interface for the configuration of the Copilot API.
@@ -77,9 +81,8 @@ export interface CopilotApiConfig {
   credentials?: RequestCredentials;
 }
 
-export type InChatRenderFunction = (
-  props: ActionRenderProps<any> | CatchAllActionRenderProps<any>,
-) => string | JSX.Element;
+export type InChatRenderFunction<TProps = ActionRenderProps<any> | CatchAllActionRenderProps<any>> =
+  (props: TProps) => string | JSX.Element;
 export type CoagentInChatRenderFunction = (
   props: CoAgentStateRenderProps<any>,
 ) => string | JSX.Element | undefined | null;
@@ -200,6 +203,9 @@ export interface CopilotContextParams {
 
   extensions: ExtensionsInput;
   setExtensions: React.Dispatch<React.SetStateAction<ExtensionsInput>>;
+  langGraphInterruptAction: LangGraphInterruptAction | null;
+  setLangGraphInterruptAction: LangGraphInterruptActionSetter;
+  removeLangGraphInterruptAction: () => void;
 }
 
 const emptyCopilotContext: CopilotContextParams = {
@@ -263,6 +269,9 @@ const emptyCopilotContext: CopilotContextParams = {
   availableAgents: [],
   extensions: {},
   setExtensions: () => {},
+  langGraphInterruptAction: null,
+  setLangGraphInterruptAction: () => null,
+  removeLangGraphInterruptAction: () => null,
 };
 
 export const CopilotContext = React.createContext<CopilotContextParams>(emptyCopilotContext);

CopilotKit/packages/react-core/src/hooks/index.ts

@@ -10,3 +10,5 @@ export { useCopilotReadable } from "./use-copilot-readable";
 export { useCoAgent, type HintFunction, runAgent, startAgent, stopAgent } from "./use-coagent";
 export { useCopilotRuntimeClient } from "./use-copilot-runtime-client";
 export { useCopilotAuthenticatedAction_c } from "./use-copilot-authenticated-action";
+export { useLangGraphInterrupt } from "./use-langgraph-interrupt";
+export { useLangGraphInterruptRender } from "./use-langgraph-interrupt-render";

CopilotKit/packages/react-core/src/hooks/use-chat.ts

@@ -1,4 +1,4 @@
-import { useRef } from "react";
+import React, { useCallback, useRef } from "react";
 import {
   FunctionCallHandler,
   COPILOT_CLOUD_PUBLIC_API_KEY_HEADER,
@@ -21,6 +21,7 @@ import {
   loadMessagesFromJsonRepresentation,
   ExtensionsInput,
   CopilotRuntimeClient,
+  langGraphInterruptEvent,
 } from "@copilotkit/runtime-client-gql";
 
 import { CopilotApiConfig } from "../context";
@@ -29,6 +30,11 @@ import { CoagentState } from "../types/coagent-state";
 import { AgentSession } from "../context/copilot-context";
 import { useCopilotRuntimeClient } from "./use-copilot-runtime-client";
 import { useAsyncCallback, useErrorToast } from "../components/error-boundary/error-utils";
+import {
+  LangGraphInterruptAction,
+  LangGraphInterruptActionSetter,
+} from "../types/interrupt-action";
+import { MetaEvent, MetaEventName } from "@copilotkit/runtime-client-gql";
 
 export type UseChatOptions = {
   /**
@@ -138,6 +144,10 @@ export type UseChatOptions = {
    * The setState-powered method to update the extensions.
    */
   setExtensions: React.Dispatch<React.SetStateAction<ExtensionsInput>>;
+
+  langGraphInterruptAction: LangGraphInterruptAction | null;
+
+  setLangGraphInterruptAction: LangGraphInterruptActionSetter;
 };
 
 export type UseChatHelpers = {
@@ -195,6 +205,8 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
     agentLock,
     extensions,
     setExtensions,
+    langGraphInterruptAction,
+    setLangGraphInterruptAction,
   } = options;
   const runChatCompletionRef = useRef<(previousMessages: Message[]) => Promise<Message[]>>();
   const addErrorToast = useErrorToast();
@@ -256,6 +268,7 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
             threadId: threadId,
             runId: runIdRef.current,
             extensions: extensionsRef.current,
+            metaEvents: composeAndFlushMetaEventsInput([langGraphInterruptAction?.event]),
             messages: convertMessagesToGqlInput(filterAgentStateMessages(messagesWithContext)),
             ...(copilotConfig.cloud
               ? {
@@ -344,6 +357,14 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
             filterAdjacentAgentStateMessages(value.generateCopilotResponse.messages),
           );
 
+          (value.generateCopilotResponse?.metaEvents ?? []).forEach((ev) => {
+            if (ev.name === "LangGraphInterruptEvent") {
+              setLangGraphInterruptAction({
+                event: langGraphInterruptEvent(ev),
+              });
+            }
+          });
+
           if (messages.length === 0) {
             continue;
           }
@@ -608,6 +629,36 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
     [messages],
   );
 
+  // Go over all events and see that they include data that should be returned to the agent
+  const composeAndFlushMetaEventsInput = useCallback(
+    (metaEvents: (MetaEvent | undefined | null)[]) => {
+      return metaEvents.reduce((acc: MetaEvent[], event) => {
+        if (!event) return acc;
+
+        switch (event.name) {
+          case MetaEventName.LangGraphInterruptEvent:
+            if (event.response) {
+              // Flush interrupt event from state
+              setLangGraphInterruptAction(null);
+              return [
+                ...acc,
+                {
+                  type: event.type,
+                  name: event.name,
+                  value: event.value,
+                  response: event.response,
+                },
+              ];
+            }
+            return acc;
+          default:
+            return acc;
+        }
+      }, []);
+    },
+    [setLangGraphInterruptAction],
+  );
+
   const append = useAsyncCallback(
     async (message: Message, options?: AppendMessageOptions): Promise<void> => {
       if (isLoading) {

CopilotKit/packages/react-core/src/hooks/use-copilot-chat.ts

@@ -112,6 +112,8 @@ export function useCopilotChat({
     chatAbortControllerRef,
     extensions,
     setExtensions,
+    langGraphInterruptAction,
+    setLangGraphInterruptAction,
   } = useCopilotContext();
   const { messages, setMessages } = useCopilotMessagesContext();
 
@@ -179,6 +181,8 @@ export function useCopilotChat({
     agentLock,
     extensions,
     setExtensions,
+    langGraphInterruptAction,
+    setLangGraphInterruptAction,
   });
 
   // this is a workaround born out of a bug that Athena incessantly ran into.

CopilotKit/packages/react-core/src/hooks/use-langgraph-interrupt-render.ts

@@ -0,0 +1,63 @@
+import { useCopilotContext } from "../context";
+import React, { useCallback } from "react";
+import { executeConditions } from "@copilotkit/shared";
+
+type InterruptProps = {
+  event: any;
+  result: any;
+  render: (props: {
+    event: any;
+    result: any;
+    resolve: (response: string) => void;
+  }) => string | React.ReactElement;
+  resolve: (response: string) => void;
+};
+
+const InterruptRenderer: React.FC<InterruptProps> = ({ event, result, render, resolve }) => {
+  return render({ event, result, resolve });
+};
+
+export function useLangGraphInterruptRender(): string | React.ReactElement | null {
+  const { langGraphInterruptAction, setLangGraphInterruptAction } = useCopilotContext();
+
+  const responseRef = React.useRef<string>();
+  const resolveInterrupt = useCallback(
+    (response: string) => {
+      responseRef.current = response;
+      // Use setTimeout to defer the state update to next tick
+      setTimeout(() => {
+        setLangGraphInterruptAction({ event: { response } });
+      }, 0);
+    },
+    [setLangGraphInterruptAction],
+  );
+
+  if (
+    !langGraphInterruptAction ||
+    !langGraphInterruptAction.event ||
+    !langGraphInterruptAction.render
+  )
+    return null;
+
+  const { render, handler, event, conditions } = langGraphInterruptAction;
+
+  const conditionsMet = executeConditions({ conditions, value: event.value });
+  if (!conditionsMet) {
+    return null;
+  }
+
+  let result = null;
+  if (handler) {
+    result = handler({
+      event,
+      resolve: resolveInterrupt,
+    });
+  }
+
+  return React.createElement(InterruptRenderer, {
+    event,
+    result,
+    render,
+    resolve: resolveInterrupt,
+  });
+}

CopilotKit/packages/react-core/src/hooks/use-langgraph-interrupt.ts

@@ -0,0 +1,62 @@
+import { useContext, useEffect, useMemo } from "react";
+import { CopilotContext } from "../context/copilot-context";
+import { LangGraphInterruptRender } from "../types/interrupt-action";
+import { useCopilotChat } from "./use-copilot-chat";
+import { useToast } from "../components/toast/toast-provider";
+import { dataToUUID } from "@copilotkit/shared";
+
+export function useLangGraphInterrupt(
+  action: Omit<LangGraphInterruptRender, "id">,
+  dependencies?: any[],
+) {
+  const { setLangGraphInterruptAction, removeLangGraphInterruptAction, langGraphInterruptAction } =
+    useContext(CopilotContext);
+  const { runChatCompletion } = useCopilotChat();
+  const { addToast } = useToast();
+
+  const actionId = dataToUUID(JSON.stringify(action), "lgAction");
+  // We only consider action to be defined once the ID is there
+  const hasAction = useMemo(
+    () => Boolean(langGraphInterruptAction?.id),
+    [langGraphInterruptAction],
+  );
+
+  const isCurrentAction = useMemo(
+    () => langGraphInterruptAction?.id && langGraphInterruptAction?.id === actionId,
+    [langGraphInterruptAction],
+  );
+
+  // Run chat completion to submit a response event. Only if it's the current action
+  useEffect(() => {
+    if (hasAction && isCurrentAction && langGraphInterruptAction?.event?.response) {
+      runChatCompletion();
+    }
+  }, [langGraphInterruptAction?.event?.response, runChatCompletion, hasAction, isCurrentAction]);
+
+  useEffect(() => {
+    if (!action) return;
+    // console.log(2, { hasAction, isCurrentAction, conditions: action.conditions })
+    // An action was already set, with no conditions and it's not the action we're using right now.
+    // Show a warning, as this action will not be executed
+    if (hasAction && !isCurrentAction && !action.conditions?.length) {
+      addToast({
+        type: "warning",
+        message: "An action is already registered for the interrupt event",
+      });
+      return;
+    }
+
+    if (hasAction && isCurrentAction) {
+      return;
+    }
+
+    setLangGraphInterruptAction({ ...action, id: actionId });
+  }, [
+    action,
+    hasAction,
+    isCurrentAction,
+    setLangGraphInterruptAction,
+    removeLangGraphInterruptAction,
+    ...(dependencies || []),
+  ]);
+}

CopilotKit/packages/react-core/src/types/interrupt-action.ts

@@ -0,0 +1,35 @@
+import { LangGraphInterruptEvent } from "@copilotkit/runtime-client-gql";
+import { Condition } from "@copilotkit/shared";
+
+export interface LangGraphInterruptRender {
+  id: string;
+  /**
+   * The handler function to handle the event.
+   */
+  handler?: (props: {
+    event: LangGraphInterruptEvent;
+    resolve: (resolution: string) => void;
+  }) => unknown | Promise<unknown>;
+  /**
+   * The render function to handle the event.
+   */
+  render?: (props: {
+    result: unknown;
+    event: LangGraphInterruptEvent;
+    resolve: (resolution: string) => void;
+  }) => string | React.ReactElement;
+  /**
+   * Conditions to render based on.
+   * Useful when using multiple interrupts
+   */
+  conditions?: Condition[];
+}
+
+export type LangGraphInterruptAction = LangGraphInterruptRender & {
+  event?: LangGraphInterruptEvent;
+};
+
+export type LangGraphInterruptActionSetterArgs =
+  | (Partial<LangGraphInterruptRender> & { event?: Partial<LangGraphInterruptEvent> })
+  | null;
+export type LangGraphInterruptActionSetter = (action: LangGraphInterruptActionSetterArgs) => void;