@copilotkit/react-core 1.57.3 → 1.58.0

package/src/hooks/use-coagent.ts

@@ -1,377 +0,0 @@
-/**
- * <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 "../v2";
-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

@@ -1,96 +0,0 @@
-import {
-  useConfigureSuggestions,
-  useCopilotChatConfiguration,
-  useCopilotKit,
-  useSuggestions,
-} from "../v2";
-import { StaticSuggestionsConfig, Suggestion } from "@copilotkit/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;
-}

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

@@ -1,245 +0,0 @@
-/**
- * Example usage of useCopilotAction with complex parameters:
- *
- * @example
- * useCopilotAction({
- *   name: "myAction",
- *   parameters: [
- *     { name: "arg1", type: "string", enum: ["option1", "option2", "option3"], required: false },
- *     { name: "arg2", type: "number" },
- *     {
- *       name: "arg3",
- *       type: "object",
- *       attributes: [
- *         { name: "nestedArg1", type: "boolean" },
- *         { name: "xyz", required: false },
- *       ],
- *     },
- *     { name: "arg4", type: "number[]" },
- *   ],
- *   handler: ({ arg1, arg2, arg3, arg4 }) => {
- *     const x = arg3.nestedArg1;
- *     const z = arg3.xyz;
- *     console.log(arg1, arg2, arg3);
- *   },
- * });
- *
- * @example
- * // Simple action without parameters
- * useCopilotAction({
- *   name: "myAction",
- *   handler: () => {
- *     console.log("No parameters provided.");
- *   },
- * });
- *
- * @example
- * // Interactive action with UI rendering and response handling
- * useCopilotAction({
- *   name: "handleMeeting",
- *   description: "Handle a meeting by booking or canceling",
- *   parameters: [
- *     {
- *       name: "meeting",
- *       type: "string",
- *       description: "The meeting to handle",
- *       required: true,
- *     },
- *     {
- *       name: "date",
- *       type: "string",
- *       description: "The date of the meeting",
- *       required: true,
- *     },
- *     {
- *       name: "title",
- *       type: "string",
- *       description: "The title of the meeting",
- *       required: true,
- *     },
- *   ],
- *   renderAndWaitForResponse: ({ args, respond, status }) => {
- *     const { meeting, date, title } = args;
- *     return (
- *       <MeetingConfirmationDialog
- *         meeting={meeting}
- *         date={date}
- *         title={title}
- *         onConfirm={() => respond('meeting confirmed')}
- *         onCancel={() => respond('meeting canceled')}
- *       />
- *     );
- *   },
- * });
- *
- * @example
- * // Catch all action allows you to render actions that are not defined in the frontend
- * useCopilotAction({
- *   name: "*",
- *   render: ({ name, args, status, result, handler, respond }) => {
- *     return <div>Rendering action: {name}</div>;
- *   },
- * });
- */
-
-/**
- * <img src="https://cdn.copilotkit.ai/docs/copilotkit/images/use-copilot-action/useCopilotAction.gif" width="500" />
- * `useCopilotAction` is a React hook that you can use in your application to provide
- * custom actions that can be called by the AI. Essentially, it allows the Copilot to
- * execute these actions contextually during a chat, based on the user's interactions
- * and needs.
- *
- * Here's how it works:
- *
- * Use `useCopilotAction` to set up actions that the Copilot can call. To provide
- * more context to the Copilot, you can provide it with a `description` (for example to explain
- * what the action does, under which conditions it can be called, etc.).
- *
- * Then you define the parameters of the action, which can be simple, e.g. primitives like strings or numbers,
- * or complex, e.g. objects or arrays.
- *
- * Finally, you provide a `handler` function that receives the parameters and returns a result.
- * CopilotKit takes care of automatically inferring the parameter types, so you get type safety
- * and autocompletion for free.
- *
- * To render a custom UI for the action, you can provide a `render()` function. This function
- * lets you render a custom component or return a string to display.
- *
- * ## Usage
- *
- * ### Simple Usage
- *
- * ```tsx
- * useCopilotAction({
- *   name: "sayHello",
- *   description: "Say hello to someone.",
- *   parameters: [
- *     {
- *       name: "name",
- *       type: "string",
- *       description: "name of the person to say greet",
- *     },
- *   ],
- *   handler: async ({ name }) => {
- *     alert(`Hello, ${name}!`);
- *   },
- * });
- * ```
- *
- * ## Generative UI
- *
- * This hooks enables you to dynamically generate UI elements and render them in the copilot chat. For more information, check out the [Generative UI](/guides/generative-ui) page.
- */
-import { useEffect, useRef, useState } from "react";
-import { Parameter } from "@copilotkit/shared";
-import {
-  CatchAllFrontendAction,
-  FrontendAction,
-} from "../types/frontend-action";
-import { useFrontendTool, UseFrontendToolArgs } from "./use-frontend-tool";
-import {
-  useRenderToolCall,
-  UseRenderToolCallArgs,
-} from "./use-render-tool-call";
-import {
-  useHumanInTheLoop,
-  UseHumanInTheLoopArgs,
-} from "./use-human-in-the-loop";
-import { useCopilotContext } from "../context";
-
-// Helper to determine which component and action config to use
-function getActionConfig<const T extends Parameter[] | [] = []>(
-  action: FrontendAction<T> | CatchAllFrontendAction,
-) {
-  if (action.name === "*") {
-    return {
-      type: "render" as const,
-      action: action as UseRenderToolCallArgs<T>,
-    };
-  }
-
-  if ("renderAndWaitForResponse" in action || "renderAndWait" in action) {
-    let render = action.render;
-    if (!render && "renderAndWaitForResponse" in action) {
-      // @ts-expect-error -- renderAndWaitForResponse is deprecated, but we need to support it for backwards compatibility
-      render = action.renderAndWaitForResponse;
-    }
-    if (!render && "renderAndWait" in action) {
-      // @ts-expect-error -- renderAndWait is deprecated, but we need to support it for backwards compatibility
-      render = action.renderAndWait;
-    }
-
-    return {
-      type: "hitl" as const,
-      action: { ...action, render } as UseHumanInTheLoopArgs<T>,
-    };
-  }
-
-  if ("available" in action) {
-    if (action.available === "enabled" || action.available === "remote") {
-      return {
-        type: "frontend" as const,
-        action: action as UseFrontendToolArgs<T>,
-      };
-    }
-    if (action.available === "frontend" || action.available === "disabled") {
-      return {
-        type: "render" as const,
-        action: action as UseRenderToolCallArgs<T>,
-      };
-    }
-  }
-
-  if ("handler" in action) {
-    return {
-      type: "frontend" as const,
-      action: action as UseFrontendToolArgs<T>,
-    };
-  }
-
-  throw new Error("Invalid action configuration");
-}
-
-/**
- * useCopilotAction is a legacy hook maintained for backwards compatibility.
- *
- * To avoid violating React's Rules of Hooks (which prohibit conditional hook calls),
- * we use a registration pattern:
- * 1. This hook registers the action configuration with the CopilotContext
- * 2. A renderer component in CopilotKit actually renders the appropriate hook wrapper
- * 3. React properly manages hook state since components are rendered, not conditionally called
- *
- * This allows action types to change between renders without corrupting React's hook state.
- */
-export function useCopilotAction<const T extends Parameter[] | [] = []>(
-  action: FrontendAction<T> | CatchAllFrontendAction,
-  dependencies?: any[],
-): void {
-  const [initialActionConfig] = useState(getActionConfig(action));
-  const currentActionConfig = getActionConfig(action);
-
-  /**
-   * Calling hooks conditionally violates React's Rules of Hooks. This rule exists because
-   * React maintains the call stack for hooks like useEffect or useState, and conditionally
-   * calling a hook would result in inconsistent call stacks between renders.
-   *
-   * Unfortunately, useCopilotAction _has_ to conditionally call a hook based on the
-   * supplied parameters. In order to avoid breaking React's call stack tracking, while
-   * breaking the Rule of Hooks, we use a ref to store the initial action configuration
-   * and throw an error if the _configuration_ changes such that we would call a different hook.
-   */
-  if (initialActionConfig.type !== currentActionConfig.type) {
-    throw new Error("Action configuration changed between renders");
-  }
-
-  switch (currentActionConfig.type) {
-    case "render":
-      return useRenderToolCall(currentActionConfig.action, dependencies);
-    case "hitl":
-      return useHumanInTheLoop(currentActionConfig.action, dependencies);
-    case "frontend":
-      return useFrontendTool(currentActionConfig.action, dependencies);
-    default:
-      throw new Error("Invalid action configuration");
-  }
-}