@copilotkit/react-core 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

package/src/hooks/use-coagent-state-render.ts

@@ -0,0 +1,152 @@
+/**
+ * The useCoAgentStateRender hook allows you to render UI or text based components on a Agentic Copilot's state in the chat.
+ * This is particularly useful for showing intermediate state or progress during Agentic Copilot operations.
+ *
+ * ## Usage
+ *
+ * ### Simple Usage
+ *
+ * ```tsx
+ * import { useCoAgentStateRender } from "@copilotkit/react-core";
+ *
+ * type YourAgentState = {
+ *   agent_state_property: string;
+ * }
+ *
+ * useCoAgentStateRender<YourAgentState>({
+ *   name: "basic_agent",
+ *   nodeName: "optionally_specify_a_specific_node",
+ *   render: ({ status, state, nodeName }) => {
+ *     return (
+ *       <YourComponent
+ *         agentStateProperty={state.agent_state_property}
+ *         status={status}
+ *         nodeName={nodeName}
+ *       />
+ *     );
+ *   },
+ * });
+ * ```
+ *
+ * This allows for you to render UI components or text based on what is happening within the agent.
+ *
+ * ### Example
+ * A great example of this is in our Perplexity Clone where we render the progress of an agent's internet search as it is happening.
+ * You can play around with it below or learn how to build it with its [demo](/coagents/videos/perplexity-clone).
+ *
+ * <Callout type="info">
+ *   This example is hosted on Vercel and may take a few seconds to load.
+ * </Callout>
+ *
+ * <iframe src="https://examples-coagents-ai-researcher-ui.vercel.app/" className="w-full rounded-lg border h-[700px] my-4" />
+ */
+
+import { useRef, useContext, useEffect } from "react";
+import { CopilotContext } from "../context/copilot-context";
+import { randomId, CopilotKitAgentDiscoveryError } from "@copilotkit/shared";
+import { CoAgentStateRender } from "../types/coagent-action";
+import { useToast } from "../components/toast/toast-provider";
+import { useCoAgentStateRenders } from "../context/coagent-state-renders-context";
+
+/**
+ * This hook is used to render agent state with custom UI components or text. This is particularly
+ * useful for showing intermediate state or progress during Agentic Copilot operations.
+ * To get started using rendering intermediate state through this hook, checkout the documentation.
+ *
+ * https://docs.copilotkit.ai/coagents/shared-state/predictive-state-updates
+ */
+
+// We implement useCoAgentStateRender dependency handling so that
+// the developer has the option to not provide any dependencies.
+// see useCopilotAction for more details about this approach.
+export function useCoAgentStateRender<T = any>(
+  action: CoAgentStateRender<T>,
+  dependencies?: any[],
+): void {
+  const { chatComponentsCache, availableAgents } = useContext(CopilotContext);
+  const { setCoAgentStateRender, removeCoAgentStateRender, coAgentStateRenders } =
+    useCoAgentStateRenders();
+  const idRef = useRef<string>(randomId());
+  const { setBannerError, addToast } = useToast();
+
+  useEffect(() => {
+    if (availableAgents?.length && !availableAgents.some((a) => a.name === action.name)) {
+      const message = `(useCoAgentStateRender): Agent "${action.name}" not found. Make sure the agent exists and is properly configured.`;
+
+      // Route to banner instead of toast for consistency
+      const agentError = new CopilotKitAgentDiscoveryError({
+        agentName: action.name,
+        availableAgents: availableAgents.map((a) => ({ name: a.name, id: a.id })),
+      });
+      setBannerError(agentError);
+    }
+  }, [availableAgents]);
+
+  const key = `${action.name}-${action.nodeName || "global"}`;
+
+  if (dependencies === undefined) {
+    if (coAgentStateRenders[idRef.current]) {
+      coAgentStateRenders[idRef.current].handler = action.handler as any;
+      if (typeof action.render === "function") {
+        if (chatComponentsCache.current !== null) {
+          chatComponentsCache.current.coAgentStateRenders[key] = action.render;
+        }
+      }
+    }
+  }
+
+  useEffect(() => {
+    // Check for duplicates by comparing against all other actions
+    const currentId = idRef.current;
+    const hasDuplicate = Object.entries(coAgentStateRenders).some(([id, otherAction]) => {
+      // Skip comparing with self
+      if (id === currentId) return false;
+
+      // Different agent names are never duplicates
+      if (otherAction.name !== action.name) return false;
+
+      // Same agent names:
+      const hasNodeName = !!action.nodeName;
+      const hasOtherNodeName = !!otherAction.nodeName;
+
+      // If neither has nodeName, they're duplicates
+      if (!hasNodeName && !hasOtherNodeName) return true;
+
+      // If one has nodeName and other doesn't, they're not duplicates
+      if (hasNodeName !== hasOtherNodeName) return false;
+
+      // If both have nodeName, they're duplicates only if the names match
+      return action.nodeName === otherAction.nodeName;
+    });
+
+    if (hasDuplicate) {
+      const message = action.nodeName
+        ? `Found multiple state renders for agent ${action.name} and node ${action.nodeName}. State renders might get overridden`
+        : `Found multiple state renders for agent ${action.name}. State renders might get overridden`;
+
+      addToast({
+        type: "warning",
+        message,
+        id: `dup-action-${action.name}`,
+      });
+    }
+  }, [coAgentStateRenders]);
+
+  useEffect(() => {
+    setCoAgentStateRender(idRef.current, action as any);
+    if (chatComponentsCache.current !== null && action.render !== undefined) {
+      chatComponentsCache.current.coAgentStateRenders[key] = action.render;
+    }
+    return () => {
+      removeCoAgentStateRender(idRef.current);
+    };
+  }, [
+    setCoAgentStateRender,
+    removeCoAgentStateRender,
+    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,366 @@
+/**
+ * <Callout type="info">
+ *   Usage of this hook assumes some additional setup in your application, for more information
+ *   on that see the CoAgents <span className="text-blue-500">[getting started guide](/coagents/quickstart/langgraph)</span>.
+ * </Callout>
+ * <Frame className="my-12">
+ *   <img
+ *     src="https://cdn.copilotkit.ai/docs/copilotkit/images/coagents/SharedStateCoAgents.gif"
+ *     alt="CoAgents demonstration"
+ *     className="w-auto"
+ *   />
+ * </Frame>
+ *
+ * This hook is used to integrate an agent into your application. With its use, you can
+ * render and update the state of an agent, allowing for a dynamic and interactive experience.
+ * We call these shared state experiences agentic copilots, or CoAgents for short.
+ *
+ * ## Usage
+ *
+ * ### Simple Usage
+ *
+ * ```tsx
+ * import { useCoAgent } from "@copilotkit/react-core";
+ *
+ * type AgentState = {
+ *   count: number;
+ * }
+ *
+ * const agent = useCoAgent<AgentState>({
+ *   name: "my-agent",
+ *   initialState: {
+ *     count: 0,
+ *   },
+ * });
+ *
+ * ```
+ *
+ * `useCoAgent` returns an object with the following properties:
+ *
+ * ```tsx
+ * const {
+ *   name,     // The name of the agent currently being used.
+ *   nodeName, // The name of the current LangGraph node.
+ *   state,    // The current state of the agent.
+ *   setState, // A function to update the state of the agent.
+ *   running,  // A boolean indicating if the agent is currently running.
+ *   start,    // A function to start the agent.
+ *   stop,     // A function to stop the agent.
+ *   run,      // A function to re-run the agent. Takes a HintFunction to inform the agent why it is being re-run.
+ * } = agent;
+ * ```
+ *
+ * Finally we can leverage these properties to create reactive experiences with the agent!
+ *
+ * ```tsx
+ * const { state, setState } = useCoAgent<AgentState>({
+ *   name: "my-agent",
+ *   initialState: {
+ *     count: 0,
+ *   },
+ * });
+ *
+ * return (
+ *   <div>
+ *     <p>Count: {state.count}</p>
+ *     <button onClick={() => setState({ count: state.count + 1 })}>Increment</button>
+ *   </div>
+ * );
+ * ```
+ *
+ * This reactivity is bidirectional, meaning that changes to the state from the agent will be reflected in the UI and vice versa.
+ *
+ * ## Parameters
+ * <PropertyReference name="options" type="UseCoagentOptions<T>" required>
+ *   The options to use when creating the coagent.
+ *   <PropertyReference name="name" type="string" required>
+ *     The name of the agent to use.
+ *   </PropertyReference>
+ *   <PropertyReference name="initialState" type="T | any">
+ *     The initial state of the agent.
+ *   </PropertyReference>
+ *   <PropertyReference name="state" type="T | any">
+ *     State to manage externally if you are using this hook with external state management.
+ *   </PropertyReference>
+ *   <PropertyReference name="setState" type="(newState: T | ((prevState: T | undefined) => T)) => void">
+ *     A function to update the state of the agent if you are using this hook with external state management.
+ *   </PropertyReference>
+ * </PropertyReference>
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Message } from "@copilotkit/shared";
+import { useAgent, useCopilotKit } from "@copilotkitnext/react";
+import { type AgentSubscriber } from "@ag-ui/client";
+import { useAgentNodeName } from "./use-agent-nodename";
+
+interface UseCoagentOptionsBase {
+  /**
+   * The name of the agent being used.
+   */
+  name: string;
+  /**
+   * @deprecated - use "config.configurable"
+   * Config to pass to a LangGraph Agent
+   */
+  configurable?: Record<string, any>;
+  /**
+   * Config to pass to a LangGraph Agent
+   */
+  config?: {
+    configurable?: Record<string, any>;
+    [key: string]: any;
+  };
+}
+
+interface WithInternalStateManagementAndInitial<T> extends UseCoagentOptionsBase {
+  /**
+   * The initial state of the agent.
+   */
+  initialState: T;
+}
+
+interface WithInternalStateManagement extends UseCoagentOptionsBase {
+  /**
+   * Optional initialState with default type any
+   */
+  initialState?: any;
+}
+
+interface WithExternalStateManagement<T> extends UseCoagentOptionsBase {
+  /**
+   * The current state of the agent.
+   */
+  state: T;
+  /**
+   * A function to update the state of the agent.
+   */
+  setState: (newState: T | ((prevState: T | undefined) => T)) => void;
+}
+
+type UseCoagentOptions<T> =
+  | WithInternalStateManagementAndInitial<T>
+  | WithInternalStateManagement
+  | WithExternalStateManagement<T>;
+
+export interface UseCoagentReturnType<T> {
+  /**
+   * The name of the agent being used.
+   */
+  name: string;
+  /**
+   * The name of the current LangGraph node.
+   */
+  nodeName?: string;
+  /**
+   * The ID of the thread the agent is running in.
+   */
+  threadId?: string;
+  /**
+   * A boolean indicating if the agent is currently running.
+   */
+  running: boolean;
+  /**
+   * The current state of the agent.
+   */
+  state: T;
+  /**
+   * A function to update the state of the agent.
+   */
+  setState: (newState: T | ((prevState: T | undefined) => T)) => void;
+  /**
+   * A function to start the agent.
+   */
+  start: () => void;
+  /**
+   * A function to stop the agent.
+   */
+  stop: () => void;
+  /**
+   * A function to re-run the agent. The hint function can be used to provide a hint to the agent
+   * about why it is being re-run again.
+   */
+  run: (...args: any[]) => Promise<any>;
+}
+
+export interface HintFunctionParams {
+  /**
+   * The previous state of the agent.
+   */
+  previousState: any;
+  /**
+   * The current state of the agent.
+   */
+  currentState: any;
+}
+
+export type HintFunction = (params: HintFunctionParams) => Message | undefined;
+
+/**
+ * This hook is used to integrate an agent into your application. With its use, you can
+ * render and update the state of the agent, allowing for a dynamic and interactive experience.
+ * We call these shared state experiences "agentic copilots". To get started using agentic copilots, which
+ * we refer to as CoAgents, checkout the documentation at https://docs.copilotkit.ai/coagents/quickstart/langgraph.
+ */
+export function useCoAgent<T = any>(options: UseCoagentOptions<T>): UseCoagentReturnType<T> {
+  const { agent } = useAgent({ agentId: options.name });
+  const { copilotkit } = useCopilotKit();
+  const nodeName = useAgentNodeName(options.name);
+
+  const handleStateUpdate = useCallback(
+    (newState: T | ((prevState: T | undefined) => T)) => {
+      if (!agent) return;
+
+      if (typeof newState === "function") {
+        const updater = newState as (prevState: T | undefined) => T;
+        agent.setState(updater(agent.state));
+      } else {
+        agent.setState({ ...agent.state, ...newState });
+      }
+    },
+    [agent?.state, agent?.setState],
+  );
+
+  useEffect(() => {
+    if (!options.config && !options.configurable) return;
+
+    let config = options.config ?? {};
+    if (options.configurable) {
+      config = {
+        ...config,
+        configurable: {
+          ...options.configurable,
+          ...config.configurable,
+        },
+      };
+    }
+    copilotkit.setProperties(config);
+  }, [options.config, options.configurable]);
+
+  const externalStateStr = useMemo(
+    () => (isExternalStateManagement(options) ? JSON.stringify(options.state) : undefined),
+    [isExternalStateManagement(options) ? JSON.stringify(options.state) : undefined],
+  );
+
+  // Sync internal state with external state if state management is external
+  useEffect(() => {
+    if (
+      agent?.state &&
+      isExternalStateManagement(options) &&
+      JSON.stringify(options.state) !== JSON.stringify(agent.state)
+    ) {
+      handleStateUpdate(options.state);
+    }
+  }, [agent, externalStateStr, handleStateUpdate]);
+
+  const hasStateValues = useCallback((value?: Record<string, any>) => {
+    return Boolean(value && Object.keys(value).length);
+  }, []);
+
+  const initialStateRef = useRef<any>(
+    isExternalStateManagement(options)
+      ? options.state
+      : "initialState" in options
+        ? options.initialState
+        : undefined,
+  );
+
+  useEffect(() => {
+    if (isExternalStateManagement(options)) {
+      initialStateRef.current = options.state;
+    } else if ("initialState" in options) {
+      initialStateRef.current = options.initialState;
+    }
+  }, [
+    isExternalStateManagement(options)
+      ? JSON.stringify(options.state)
+      : "initialState" in options
+        ? JSON.stringify(options.initialState)
+        : undefined,
+  ]);
+
+  useEffect(() => {
+    if (!agent) return;
+    const subscriber: AgentSubscriber = {
+      onStateChanged: (args: any) => {
+        if (isExternalStateManagement(options)) {
+          options.setState(args.state);
+        }
+      },
+      onRunInitialized: (args: any) => {
+        const runHasState = hasStateValues(args.state);
+        if (runHasState) {
+          handleStateUpdate(args.state);
+          return;
+        }
+
+        if (hasStateValues(agent.state)) {
+          return;
+        }
+
+        if (initialStateRef.current !== undefined) {
+          handleStateUpdate(initialStateRef.current);
+        }
+      },
+    };
+
+    const subscription = agent.subscribe(subscriber);
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [agent, handleStateUpdate, hasStateValues]);
+
+  // Return a consistent shape whether or not the agent is available
+  return useMemo<UseCoagentReturnType<T>>(() => {
+    if (!agent) {
+      const noop = () => {};
+      const noopAsync = async () => {};
+      const initialState =
+        // prefer externally provided state if available
+        ("state" in options && (options as any).state) ??
+        // then initialState if provided
+        ("initialState" in options && (options as any).initialState) ??
+        ({} as T);
+      return {
+        name: options.name,
+        nodeName,
+        threadId: undefined,
+        running: false,
+        state: initialState as T,
+        setState: noop,
+        start: noop,
+        stop: noop,
+        run: noopAsync,
+      };
+    }
+
+    return {
+      name: agent?.agentId ?? options.name,
+      nodeName,
+      threadId: agent.threadId,
+      running: agent.isRunning,
+      state: agent.state,
+      setState: handleStateUpdate,
+      // TODO: start and run both have same thing. need to figure out
+      start: agent.runAgent,
+      stop: agent.abortRun,
+      run: agent.runAgent,
+    };
+  }, [
+    agent?.state,
+    agent?.runAgent,
+    agent?.abortRun,
+    agent?.runAgent,
+    agent?.threadId,
+    agent?.isRunning,
+    agent?.agentId,
+    handleStateUpdate,
+    options.name,
+  ]);
+}
+
+const isExternalStateManagement = <T>(
+  options: UseCoagentOptions<T>,
+): options is WithExternalStateManagement<T> => {
+  return "state" in options && "setState" in options;
+};

package/src/hooks/use-configure-chat-suggestions.tsx

@@ -0,0 +1,86 @@
+import {
+  useConfigureSuggestions,
+  useCopilotChatConfiguration,
+  useCopilotKit,
+  useSuggestions,
+} from "@copilotkitnext/react";
+import { StaticSuggestionsConfig, Suggestion } from "@copilotkitnext/core";
+import { useCopilotContext } from "../context";
+import { useEffect, useMemo } from "react";
+
+type StaticSuggestionInput = Omit<Suggestion, "isLoading"> & Partial<Pick<Suggestion, "isLoading">>;
+
+type StaticSuggestionsConfigInput = Omit<StaticSuggestionsConfig, "suggestions"> & {
+  suggestions: StaticSuggestionInput[];
+};
+
+type DynamicSuggestionsConfigInput = {
+  /**
+   * A prompt or instructions for the GPT to generate suggestions.
+   */
+  instructions: string;
+  /**
+   * The minimum number of suggestions to generate. Defaults to `1`.
+   * @default 1
+   */
+  minSuggestions?: number;
+  /**
+   * The maximum number of suggestions to generate. Defaults to `3`.
+   * @default 1
+   */
+  maxSuggestions?: number;
+
+  /**
+   * Whether the suggestions are available. Defaults to `enabled`.
+   * @default enabled
+   */
+  available?: "enabled" | "disabled" | "always" | "before-first-message" | "after-first-message";
+
+  /**
+   * An optional class name to apply to the suggestions.
+   */
+  className?: string;
+};
+
+export type UseCopilotChatSuggestionsConfiguration =
+  | DynamicSuggestionsConfigInput
+  | StaticSuggestionsConfigInput;
+
+export function useConfigureChatSuggestions(
+  config: UseCopilotChatSuggestionsConfiguration,
+  dependencies: any[] = [],
+): ReturnType<typeof useSuggestions> {
+  const existingConfig = useCopilotChatConfiguration();
+  const resolvedAgentId = existingConfig?.agentId ?? "default";
+  const { copilotkit } = useCopilotKit();
+
+  const available = config.available === "enabled" ? "always" : config.available;
+
+  const finalSuggestionConfig = {
+    ...config,
+    available,
+    consumerAgentId: resolvedAgentId, // Use chatConfig.agentId here
+  };
+  useConfigureSuggestions(finalSuggestionConfig, dependencies);
+
+  const result = useSuggestions({ agentId: resolvedAgentId });
+
+  useEffect(() => {
+    if (finalSuggestionConfig.available === "disabled") return;
+    const subscription = copilotkit.subscribe({
+      onAgentsChanged: () => {
+        // When agents change, check if our target agent now exists and reload
+        const agent = copilotkit.getAgent(resolvedAgentId);
+        if (agent && !agent.isRunning && !result.suggestions.length) {
+          copilotkit.reloadSuggestions(resolvedAgentId);
+        }
+      },
+    });
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [resolvedAgentId]);
+
+  return result;
+}