@copilotkit/react-core 1.2.0 → 1.2.2-feat-runtime-remote-actions.0

package/src/components/copilot-provider/copilotkit-props.tsx

@@ -73,4 +73,9 @@ export interface CopilotKitProps {
    * If set to "auto", the dev console will be show on localhost only.
    */
   showDevConsole?: boolean | "auto";
+
+  /**
+   * The name of the agent to use.
+   */
+  agent?: string;
 }

package/src/components/copilot-provider/copilotkit.tsx

@@ -35,6 +35,8 @@ import {
   CopilotContext,
   CopilotApiConfig,
   InChatRenderFunction,
+  ChatComponentsCache,
+  AgentSession,
 } from "../../context/copilot-context";
 import useTree from "../../hooks/use-tree";
 import { CopilotChatSuggestionConfiguration, DocumentPointer } from "../../types";
@@ -44,11 +46,13 @@ import {
   CopilotCloudConfig,
   FunctionCallHandler,
 } from "@copilotkit/shared";
-import { Message } from "@copilotkit/runtime-client-gql";
+import { AgentStateMessage, Message } from "@copilotkit/runtime-client-gql";
 
 import { FrontendAction } from "../../types/frontend-action";
 import useFlatCategoryStore from "../../hooks/use-flat-category-store";
 import { CopilotKitProps } from "./copilotkit-props";
+import { CoagentAction } from "../../types/coagent-action";
+import { CoagentState } from "../../types/coagent-state";
 
 export function CopilotKit({ children, ...props }: CopilotKitProps) {
   // Compute all the functions and properties that we need to pass
@@ -63,7 +67,11 @@ export function CopilotKit({ children, ...props }: CopilotKitProps) {
   const chatApiEndpoint = props.runtimeUrl || COPILOT_CLOUD_CHAT_URL;
 
   const [actions, setActions] = useState<Record<string, FrontendAction<any>>>({});
-  const chatComponentsCache = useRef<Record<string, InChatRenderFunction | string>>({});
+  const [coagentActions, setCoagentActions] = useState<Record<string, CoagentAction<any>>>({});
+  const chatComponentsCache = useRef<ChatComponentsCache>({
+    actions: {},
+    coagentActions: {},
+  });
   const { addElement, removeElement, printTree } = useTree();
   const [messages, setMessages] = useState<Message[]>([]);
   const [isLoading, setIsLoading] = useState(false);
@@ -92,6 +100,23 @@ export function CopilotKit({ children, ...props }: CopilotKitProps) {
     });
   }, []);
 
+  const setCoagentAction = useCallback((id: string, action: CoagentAction<any>) => {
+    setCoagentActions((prevPoints) => {
+      return {
+        ...prevPoints,
+        [id]: action,
+      };
+    });
+  }, []);
+
+  const removeCoagentAction = useCallback((id: string) => {
+    setCoagentActions((prevPoints) => {
+      const newPoints = { ...prevPoints };
+      delete newPoints[id];
+      return newPoints;
+    });
+  }, []);
+
   const getContextString = useCallback(
     (documents: DocumentPointer[], categories: string[]) => {
       const documentsString = documents
@@ -206,6 +231,16 @@ export function CopilotKit({ children, ...props }: CopilotKitProps) {
     });
   };
 
+  const [coagentStates, setCoagentStates] = useState<Record<string, CoagentState>>({});
+  let initialAgentSession: AgentSession | null = null;
+  if (props.agent) {
+    initialAgentSession = {
+      agentName: props.agent,
+    };
+  }
+
+  const [agentSession, setAgentSession] = useState<AgentSession | null>(initialAgentSession);
+
   return (
     <CopilotContext.Provider
       value={{
@@ -214,6 +249,9 @@ export function CopilotKit({ children, ...props }: CopilotKitProps) {
         getFunctionCallHandler,
         setAction,
         removeAction,
+        coagentActions,
+        setCoagentAction,
+        removeCoagentAction,
         getContextString,
         addContext,
         removeContext,
@@ -231,6 +269,10 @@ export function CopilotKit({ children, ...props }: CopilotKitProps) {
         chatInstructions,
         setChatInstructions,
         showDevConsole: props.showDevConsole === undefined ? "auto" : props.showDevConsole,
+        coagentStates,
+        setCoagentStates,
+        agentSession,
+        setAgentSession,
       }}
     >
       {children}
@@ -253,7 +295,7 @@ function entryPointsToFunctionCallHandler(actions: FrontendAction<any>[]): Funct
       await new Promise<void>((resolve, reject) => {
         flushSync(async () => {
           try {
-            result = await action.handler(args);
+            result = await action.handler?.(args);
             resolve();
           } catch (error) {
             reject(error);

package/src/context/copilot-context.tsx

@@ -5,6 +5,8 @@ import React from "react";
 import { TreeNodeId } from "../hooks/use-tree";
 import { DocumentPointer } from "../types";
 import { CopilotChatSuggestionConfiguration } from "../types/chat-suggestion-configuration";
+import { CoagentAction, CoagentActionRenderProps } from "../types/coagent-action";
+import { CoagentState } from "../types/coagent-state";
 
 /**
  * Interface for the configuration of the Copilot API.
@@ -67,13 +69,33 @@ export interface CopilotApiConfig {
 }
 
 export type InChatRenderFunction = (props: ActionRenderProps<any>) => string | JSX.Element;
+export type CoagentInChatRenderFunction = (
+  props: CoagentActionRenderProps<any>,
+) => string | JSX.Element;
+
+export interface ChatComponentsCache {
+  actions: Record<string, InChatRenderFunction | string>;
+  coagentActions: Record<string, CoagentInChatRenderFunction | string>;
+}
+
+export interface AgentSession {
+  agentName: string;
+  threadId?: string;
+  nodeName?: string;
+}
 
 export interface CopilotContextParams {
   // function-calling
   actions: Record<string, FrontendAction<any>>;
   setAction: (id: string, action: FrontendAction<any>) => void;
   removeAction: (id: string) => void;
-  chatComponentsCache: React.RefObject<Record<string, InChatRenderFunction | string>>;
+
+  // coagent actions
+  coagentActions: Record<string, CoagentAction<any>>;
+  setCoagentAction: (id: string, action: CoagentAction<any>) => void;
+  removeCoagentAction: (id: string) => void;
+
+  chatComponentsCache: React.RefObject<ChatComponentsCache>;
 
   getFunctionCallHandler: (
     customEntryPoints?: Record<string, FrontendAction<any>>,
@@ -110,6 +132,12 @@ export interface CopilotContextParams {
   copilotApiConfig: CopilotApiConfig;
 
   showDevConsole: boolean | "auto";
+
+  // agents
+  coagentStates: Record<string, CoagentState>;
+  setCoagentStates: React.Dispatch<React.SetStateAction<Record<string, CoagentState>>>;
+  agentSession: AgentSession | null;
+  setAgentSession: React.Dispatch<React.SetStateAction<AgentSession | null>>;
 }
 
 const emptyCopilotContext: CopilotContextParams = {
@@ -117,7 +145,11 @@ const emptyCopilotContext: CopilotContextParams = {
   setAction: () => {},
   removeAction: () => {},
 
-  chatComponentsCache: { current: {} },
+  coagentActions: {},
+  setCoagentAction: () => {},
+  removeCoagentAction: () => {},
+
+  chatComponentsCache: { current: { actions: {}, coagentActions: {} } },
   getContextString: (documents: DocumentPointer[], categories: string[]) =>
     returnAndThrowInDebug(""),
   addContext: () => "",
@@ -155,6 +187,11 @@ const emptyCopilotContext: CopilotContextParams = {
   addChatSuggestionConfiguration: () => {},
   removeChatSuggestionConfiguration: () => {},
   showDevConsole: "auto",
+  coagentStates: {},
+  setCoagentStates: () => {},
+
+  agentSession: null,
+  setAgentSession: () => {},
 };
 
 export const CopilotContext = React.createContext<CopilotContextParams>(emptyCopilotContext);

package/src/hooks/index.ts

@@ -3,6 +3,8 @@ export type { UseCopilotChatOptions } from "./use-copilot-chat";
 export type { UseCopilotChatReturn } from "./use-copilot-chat";
 
 export { useCopilotAction } from "./use-copilot-action";
+export { useCoAgentAction } from "./use-coagent-action";
 export { useMakeCopilotDocumentReadable } from "./use-make-copilot-document-readable";
 export { type UseChatHelpers } from "./use-chat";
 export { useCopilotReadable } from "./use-copilot-readable";
+export { useCoAgent } from "./use-coagent";

package/src/hooks/use-chat.ts

@@ -2,8 +2,8 @@ import { useRef } from "react";
 import {
   FunctionCallHandler,
   COPILOT_CLOUD_PUBLIC_API_KEY_HEADER,
-  Action,
   actionParametersToJsonSchema,
+  CoagentActionHandler,
 } from "@copilotkit/shared";
 import {
   Message,
@@ -12,14 +12,20 @@ import {
   ResultMessage,
   CopilotRuntimeClient,
   convertMessagesToGqlInput,
+  filterAdjacentAgentStateMessages,
+  filterAgentStateMessages,
   convertGqlOutputToMessages,
   MessageStatusCode,
   MessageRole,
   Role,
   CopilotRequestType,
+  AgentStateMessage,
 } from "@copilotkit/runtime-client-gql";
 
 import { CopilotApiConfig } from "../context";
+import { FrontendAction } from "../types/frontend-action";
+import { CoagentState } from "../types/coagent-state";
+import { AgentSession } from "../context/copilot-context";
 
 export type UseChatOptions = {
   /**
@@ -32,10 +38,16 @@ export type UseChatOptions = {
    * automatically to the API and will be used to update the chat.
    */
   onFunctionCall?: FunctionCallHandler;
+
+  /**
+   * Callback function to be called when a coagent action is received.
+   */
+  onCoagentAction?: CoagentActionHandler;
+
   /**
    * Function definitions to be sent to the API.
    */
-  actions: Action[];
+  actions: FrontendAction<any>[];
 
   /**
    * The CopilotKit API configuration.
@@ -65,6 +77,26 @@ export type UseChatOptions = {
    * setState-powered method to update the isChatLoading value
    */
   setIsLoading: React.Dispatch<React.SetStateAction<boolean>>;
+
+  /**
+   * The current list of coagent states.
+   */
+  coagentStates: Record<string, CoagentState>;
+
+  /**
+   * setState-powered method to update the agent states
+   */
+  setCoagentStates: React.Dispatch<React.SetStateAction<Record<string, CoagentState>>>;
+
+  /**
+   * The current agent session.
+   */
+  agentSession: AgentSession | null;
+
+  /**
+   * setState-powered method to update the agent session
+   */
+  setAgentSession: React.Dispatch<React.SetStateAction<AgentSession | null>>;
 };
 
 export type UseChatHelpers = {
@@ -97,11 +129,19 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
     isLoading,
     actions,
     onFunctionCall,
+    onCoagentAction,
+    setCoagentStates,
+    coagentStates,
+    agentSession,
+    setAgentSession,
   } = options;
+
   const abortControllerRef = useRef<AbortController>();
   const threadIdRef = useRef<string | null>(null);
   const runIdRef = useRef<string | null>(null);
+
   const publicApiKey = copilotConfig.publicApiKey;
+
   const headers = {
     ...(copilotConfig.headers || {}),
     ...(publicApiKey ? { [COPILOT_CLOUD_PUBLIC_API_KEY_HEADER]: publicApiKey } : {}),
@@ -147,7 +187,7 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
           },
           threadId: threadIdRef.current,
           runId: runIdRef.current,
-          messages: convertMessagesToGqlInput(messagesWithContext),
+          messages: convertMessagesToGqlInput(filterAgentStateMessages(messagesWithContext)),
           ...(copilotConfig.cloud
             ? {
                 cloud: {
@@ -169,6 +209,15 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
           metadata: {
             requestType: CopilotRequestType.Chat,
           },
+          ...(agentSession
+            ? {
+                agentSession,
+              }
+            : {}),
+          agentStates: Object.values(coagentStates).map((state) => ({
+            agentName: state.name,
+            state: JSON.stringify(state.state),
+          })),
         },
         properties: copilotConfig.properties,
         signal: abortControllerRef.current?.signal,
@@ -180,7 +229,8 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
 
     const reader = stream.getReader();
 
-    let results: { [id: string]: string } = {};
+    let actionResults: { [id: string]: string } = {};
+    let executedCoagentActions: string[] = [];
 
     try {
       while (true) {
@@ -197,7 +247,9 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
         threadIdRef.current = value.generateCopilotResponse.threadId || null;
         runIdRef.current = value.generateCopilotResponse.runId || null;
 
-        const messages = convertGqlOutputToMessages(value.generateCopilotResponse.messages);
+        const messages = convertGqlOutputToMessages(
+          filterAdjacentAgentStateMessages(value.generateCopilotResponse.messages),
+        );
 
         if (messages.length === 0) {
           continue;
@@ -222,14 +274,14 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
         else {
           for (const message of messages) {
             newMessages.push(message);
-
+            // execute regular action executions
             if (
               message instanceof ActionExecutionMessage &&
               message.status.code !== MessageStatusCode.Pending &&
               message.scope === "client" &&
               onFunctionCall
             ) {
-              if (!(message.id in results)) {
+              if (!(message.id in actionResults)) {
                 // Do not execute a function call if guardrails are enabled but the status is not known
                 if (guardrailsEnabled && value.generateCopilotResponse.status === undefined) {
                   break;
@@ -240,29 +292,76 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
                   name: message.name,
                   args: message.arguments,
                 });
-                results[message.id] = result;
+                actionResults[message.id] = result;
               }
-
               // add the result message
               newMessages.push(
                 new ResultMessage({
-                  result: ResultMessage.encodeResult(results[message.id]),
+                  result: ResultMessage.encodeResult(actionResults[message.id]),
                   actionExecutionId: message.id,
                   actionName: message.name,
                 }),
               );
             }
+            // execute coagent actions
+            if (
+              message instanceof AgentStateMessage &&
+              !message.active &&
+              !executedCoagentActions.includes(message.id) &&
+              onCoagentAction
+            ) {
+              // Do not execute a coagent action if guardrails are enabled but the status is not known
+              if (guardrailsEnabled && value.generateCopilotResponse.status === undefined) {
+                break;
+              }
+              // execute coagent action
+              await onCoagentAction({
+                name: message.agentName,
+                nodeName: message.nodeName,
+                state: message.state,
+              });
+              executedCoagentActions.push(message.id);
+            }
+          }
+
+          const lastAgentStateMessage = [...messages]
+            .reverse()
+            .find((message) => message instanceof AgentStateMessage);
+
+          if (lastAgentStateMessage) {
+            if (lastAgentStateMessage.running) {
+              setCoagentStates((prevAgentStates) => ({
+                ...prevAgentStates,
+                [lastAgentStateMessage.agentName]: {
+                  name: lastAgentStateMessage.agentName,
+                  state: lastAgentStateMessage.state,
+                  running: lastAgentStateMessage.running,
+                  active: lastAgentStateMessage.active,
+                  threadId: lastAgentStateMessage.threadId,
+                  nodeName: lastAgentStateMessage.nodeName,
+                  runId: lastAgentStateMessage.runId,
+                },
+              }));
+              setAgentSession({
+                threadId: lastAgentStateMessage.threadId,
+                agentName: lastAgentStateMessage.agentName,
+                nodeName: lastAgentStateMessage.nodeName,
+              });
+            } else {
+              setAgentSession(null);
+            }
           }
         }
 
         if (newMessages.length > 0) {
+          // Update message state
           setMessages([...previousMessages, ...newMessages]);
         }
       }
 
       if (
         // if we have client side results
-        Object.values(results).length ||
+        Object.values(actionResults).length ||
         // or the last message we received is a result
         (newMessages.length && newMessages[newMessages.length - 1] instanceof ResultMessage)
       ) {
@@ -289,6 +388,7 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
     if (isLoading) {
       return;
     }
+
     const newMessages = [...messages, message];
     setMessages(newMessages);
     return runChatCompletionAndHandleFunctionCall(newMessages);

package/src/hooks/use-coagent-action.ts

@@ -0,0 +1,44 @@
+import { useRef, useContext, useEffect } from "react";
+import { CopilotContext } from "../context/copilot-context";
+import { randomId } from "@copilotkit/shared";
+import { CoagentAction } from "../types/coagent-action";
+
+// We implement useCoAgentAction dependency handling so that
+// the developer has the option to not provide any dependencies.
+// see useCopilotAction for more details about this approach.
+export function useCoAgentAction<T = any>(action: CoagentAction<T>, dependencies?: any[]): void {
+  const { setCoagentAction, removeCoagentAction, coagentActions, chatComponentsCache } =
+    useContext(CopilotContext);
+  const idRef = useRef<string>(randomId());
+
+  const key = `${action.name}-${action.nodeName || "global"}`;
+
+  if (dependencies === undefined) {
+    if (coagentActions[idRef.current]) {
+      coagentActions[idRef.current].handler = action.handler as any;
+      if (typeof action.render === "function") {
+        if (chatComponentsCache.current !== null) {
+          chatComponentsCache.current.coagentActions[key] = action.render;
+        }
+      }
+    }
+  }
+
+  useEffect(() => {
+    setCoagentAction(idRef.current, action as any);
+    if (chatComponentsCache.current !== null && action.render !== undefined) {
+      chatComponentsCache.current.coagentActions[key] = action.render;
+    }
+    return () => {
+      removeCoagentAction(idRef.current);
+    };
+  }, [
+    setCoagentAction,
+    removeCoagentAction,
+    action.name,
+    // include render only if it's a string
+    typeof action.render === "string" ? action.render : undefined,
+    // dependencies set by the developer
+    ...(dependencies || []),
+  ]);
+}

package/src/hooks/use-coagent.ts

@@ -0,0 +1,133 @@
+import { useEffect } from "react";
+import { useCopilotContext } from "../context";
+import { CoagentState } from "../types/coagent-state";
+
+interface WithInternalStateManagementAndInitial<T> {
+  name: string;
+  initialState: T;
+}
+
+interface WithInternalStateManagement {
+  name: string;
+  initialState?: any; // Optional initialState with default type any
+}
+
+interface WithExternalStateManagement<T> {
+  name: string;
+  state: T;
+  setState: (newState: T | ((prevState: T | undefined) => T)) => void;
+}
+
+type UseCoagentOptions<T> =
+  | WithInternalStateManagementAndInitial<T>
+  | WithInternalStateManagement
+  | WithExternalStateManagement<T>;
+
+export interface UseCoagentReturnType<T> {
+  name: string;
+  nodeName?: string;
+  threadId?: string;
+  running: boolean;
+  state: T;
+  setState: (newState: T | ((prevState: T | undefined) => T)) => void;
+  start: () => void;
+  stop: () => void;
+}
+
+export function useCoAgent<T = any>(options: UseCoagentOptions<T>): UseCoagentReturnType<T> {
+  const isExternalStateManagement = (
+    options: UseCoagentOptions<T>,
+  ): options is WithExternalStateManagement<T> => {
+    return "state" in options && "setState" in options;
+  };
+
+  const { name } = options;
+
+  const isInternalStateManagementWithInitial = (
+    options: UseCoagentOptions<T>,
+  ): options is WithInternalStateManagementAndInitial<T> => {
+    return "initialState" in options;
+  };
+
+  const { coagentStates, setCoagentStates } = useCopilotContext();
+
+  const getCoagentState = (coagentStates: Record<string, CoagentState>, name: string) => {
+    if (coagentStates[name]) {
+      return coagentStates[name];
+    } else {
+      return {
+        name,
+        state: isInternalStateManagementWithInitial(options) ? options.initialState : {},
+        running: false,
+        active: false,
+        threadId: undefined,
+        nodeName: undefined,
+        runId: undefined,
+      };
+    }
+  };
+
+  // if we manage state internally, we need to provide a function to set the state
+  const setState = (newState: T | ((prevState: T | undefined) => T)) => {
+    setCoagentStates((prevAgentStates) => {
+      let coagentState: CoagentState = getCoagentState(prevAgentStates, name);
+
+      const updatedState =
+        typeof newState === "function" ? (newState as Function)(coagentState.state) : newState;
+
+      return {
+        ...prevAgentStates,
+        [name]: {
+          ...coagentState,
+          state: updatedState,
+        },
+      };
+    });
+  };
+
+  const coagentState = getCoagentState(coagentStates, name);
+
+  const state = isExternalStateManagement(options) ? options.state : coagentState.state;
+
+  // Sync internal state with external state if state management is external
+  useEffect(() => {
+    if (isExternalStateManagement(options)) {
+      setState(options.state);
+    } else if (coagentStates[name] === undefined) {
+      setState(options.initialState === undefined ? {} : options.initialState);
+    }
+  }, [isExternalStateManagement(options) ? JSON.stringify(options.state) : undefined]);
+
+  // Return the state and setState function
+  return {
+    name,
+    nodeName: coagentState.nodeName,
+    state,
+    setState,
+    running: coagentState.running,
+    start: () => {
+      startAgent(name);
+    },
+    stop: () => {
+      stopAgent(name);
+    },
+  };
+}
+
+function startAgent(name: string) {
+  const { setAgentSession } = useCopilotContext();
+  setAgentSession({
+    agentName: name,
+  });
+}
+
+function stopAgent(name: string) {
+  const { agentSession, setAgentSession } = useCopilotContext();
+  if (agentSession && agentSession.agentName === name) {
+    setAgentSession(null);
+  } else {
+    console.warn(`No agent session found for ${name}`);
+  }
+}
+
+// <CopilotKit agent="lockedInAgentName" />

package/src/hooks/use-copilot-action.ts

@@ -27,7 +27,7 @@ export function useCopilotAction<const T extends Parameter[] | [] = []>(
       actions[idRef.current].handler = action.handler as any;
       if (typeof action.render === "function") {
         if (chatComponentsCache.current !== null) {
-          chatComponentsCache.current[action.name] = action.render;
+          chatComponentsCache.current.actions[action.name] = action.render;
         }
       }
     }
@@ -39,7 +39,7 @@ export function useCopilotAction<const T extends Parameter[] | [] = []>(
     }
     setAction(idRef.current, action as any);
     if (chatComponentsCache.current !== null && action.render !== undefined) {
-      chatComponentsCache.current[action.name] = action.render;
+      chatComponentsCache.current.actions[action.name] = action.render;
     }
     return () => {
       // NOTE: For now, we don't remove the chatComponentsCache entry when the action is removed.