@copilotkit/react-core 1.1.2 → 1.1.3-feat-runtime-remote-actions.0

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.2",
+  "version": "1.1.3-feat-runtime-remote-actions.0",
   "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -36,14 +36,14 @@
     "tsup": "^6.7.0",
     "typescript": "^5.2.3",
     "@types/react-dom": "^18.2.4",
-    "eslint-config-custom": "1.1.1",
-    "tsconfig": "1.1.1"
+    "eslint-config-custom": "1.1.2-feat-runtime-remote-actions.0",
+    "tsconfig": "1.1.2-feat-runtime-remote-actions.0"
   },
   "dependencies": {
     "@scarf/scarf": "^1.3.0",
     "untruncate-json": "^0.0.1",
-    "@copilotkit/runtime-client-gql": "1.1.2",
-    "@copilotkit/shared": "1.1.2"
+    "@copilotkit/runtime-client-gql": "1.1.3-feat-runtime-remote-actions.0",
+    "@copilotkit/shared": "1.1.3-feat-runtime-remote-actions.0"
   },
   "keywords": [
     "copilotkit",

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,12 +187,21 @@ const emptyCopilotContext: CopilotContextParams = {
   addChatSuggestionConfiguration: () => {},
   removeChatSuggestionConfiguration: () => {},
   showDevConsole: "auto",
+  coagentStates: {},
+  setCoagentStates: () => {},
+
+  agentSession: null,
+  setAgentSession: () => {},
 };
 
 export const CopilotContext = React.createContext<CopilotContextParams>(emptyCopilotContext);
 
 export function useCopilotContext(): CopilotContextParams {
-  return React.useContext(CopilotContext);
+  const context = React.useContext(CopilotContext);
+  if (context === emptyCopilotContext) {
+    throw new Error("Remember to wrap your app in a `<CopilotKit> {...} </CopilotKit>` !!!");
+  }
+  return context;
 }
 
 function returnAndThrowInDebug<T>(value: T): T {

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,
@@ -17,9 +17,13 @@ import {
   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 +36,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 +75,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 +127,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 } : {}),
@@ -143,6 +181,7 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
               description: action.description || "",
               jsonSchema: JSON.stringify(actionParametersToJsonSchema(action.parameters || [])),
             })),
+            url: window.location.href,
           },
           threadId: threadIdRef.current,
           runId: runIdRef.current,
@@ -168,6 +207,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,
@@ -179,7 +227,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) {
@@ -222,13 +271,38 @@ export function useChat(options: UseChatOptions): UseChatHelpers {
           for (const message of messages) {
             newMessages.push(message);
 
+            if (message instanceof AgentStateMessage) {
+              if (message.running) {
+                setCoagentStates((prevAgentStates) => ({
+                  ...prevAgentStates,
+                  [message.agentName]: {
+                    name: message.agentName,
+                    state: message.state,
+                    running: message.running,
+                    active: message.active,
+                    threadId: message.threadId,
+                    nodeName: message.nodeName,
+                    runId: message.runId,
+                  },
+                }));
+                setAgentSession({
+                  threadId: message.threadId,
+                  agentName: message.agentName,
+                  nodeName: message.nodeName,
+                });
+              } else {
+                setAgentSession(null);
+              }
+            }
+
+            // 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;
@@ -239,29 +313,77 @@ 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);
+            }
           }
         }
 
         if (newMessages.length > 0) {
-          setMessages([...previousMessages, ...newMessages]);
+          // Construct filteredMessages inline to remove adjacent AgentStateMessage instances
+          // with the same agentName, keeping only the last one.
+          const filteredMessages = [...previousMessages, ...newMessages].reduce(
+            (acc: Message[], message: Message) => {
+              if (
+                // If the current message is an AgentStateMessage
+                message instanceof AgentStateMessage &&
+                // And there is at least one message in the accumulator
+                acc.length > 0 &&
+                // And the last message in the accumulator is also an AgentStateMessage
+                acc[acc.length - 1] instanceof AgentStateMessage &&
+                // And the agentName, nodeName, and runId are the same
+                (acc[acc.length - 1] as AgentStateMessage).agentName === message.agentName &&
+                (acc[acc.length - 1] as AgentStateMessage).nodeName === message.nodeName &&
+                (acc[acc.length - 1] as AgentStateMessage).runId === message.runId
+              ) {
+                // If the conditions are met, replace the last message in the accumulator with the current message
+                acc[acc.length - 1] = message;
+              } else {
+                // Otherwise, add the current message to the accumulator
+                acc.push(message);
+              }
+              return acc;
+            },
+            [],
+          );
+
+          // Update the state with the filtered messages
+          setMessages(filteredMessages);
         }
       }
 
       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)
       ) {
@@ -288,6 +410,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" />