useConfigureSuggestions

Overview

useConfigureSuggestions is a React hook that registers a suggestions configuration with the CopilotKit core. It supports two modes: static suggestions (a fixed list) and dynamic suggestions (generated by the agent based on instructions).

The configuration is automatically registered on mount and removed on unmount. When the configuration changes, suggestions are reloaded automatically.

Signature

tsx

import { useConfigureSuggestions } from "@copilotkit/react-core/v2";

function useConfigureSuggestions(
  config: SuggestionsConfigInput | null | undefined,
  deps?: ReadonlyArray<unknown>,
): void;

Parameters

<PropertyReference name="config" type="SuggestionsConfigInput | null | undefined"> The suggestions configuration. Pass `null` or `undefined` to disable suggestions. Can be either a `DynamicSuggestionsConfig` or a `StaticSuggestionsConfigInput`.

Dynamic Configuration

Used when suggestions should be generated by the agent at runtime.

<PropertyReference name="instructions" type="string" required> A prompt or instructions for the model to generate suggestions. This is the key that distinguishes a dynamic config from a static one. </PropertyReference> <PropertyReference name="minSuggestions" type="number" default="1"> The minimum number of suggestions to generate. </PropertyReference> <PropertyReference name="maxSuggestions" type="number" default="3"> The maximum number of suggestions to generate. </PropertyReference>

<PropertyReference name="available" type="SuggestionAvailability" default='"after-first-message"'

When the suggestions should be available. Options: - "before-first-message" -- Show suggestions before any messages are sent. - "after-first-message" -- Show suggestions after the first message (default for dynamic). - "always" -- Always show suggestions. - "disabled" -- Disable suggestions. </PropertyReference>

<PropertyReference name="providerAgentId" type="string" default='"default"'> The agent ID of the provider that generates the suggestions. </PropertyReference> <PropertyReference name="consumerAgentId" type="string" default='"*"'> The agent ID of the consumer that displays the suggestions. Defaults to `"*"` (all agents). </PropertyReference>

Static Configuration

Used when suggestions are a predefined list.

<PropertyReference name="suggestions" type="StaticSuggestionInput[]" required> Array of suggestion objects. Each suggestion has: - `title: string` -- Short display title for the suggestion. - `message: string` -- The message content to send when selected. - `isLoading?: boolean` -- Optional loading state (defaults to `false`). </PropertyReference>

<PropertyReference name="available" type="SuggestionAvailability" default='"before-first-message"'

When the suggestions should be available. Same options as dynamic configuration. </PropertyReference>

<PropertyReference name="consumerAgentId" type="string" default='"*"'> The agent ID of the consumer that displays the suggestions. Defaults to `"*"` (all agents). </PropertyReference> </PropertyReference> <PropertyReference name="deps" type="ReadonlyArray<unknown>"> Optional dependency array. When any value in this array changes, suggestions are reloaded. This is useful for dynamic suggestions that depend on external state. </PropertyReference>

Usage

Static Suggestions

tsx

function WelcomeSuggestions() {
  useConfigureSuggestions({
    suggestions: [
      { title: "Get started", message: "Help me get started with my project" },
      { title: "Show examples", message: "Show me some example use cases" },
      {
        title: "Documentation",
        message: "Where can I find the documentation?",
      },
    ],
    available: "before-first-message",
  });

  return null;
}

Dynamic Suggestions

tsx

function SmartSuggestions() {
  useConfigureSuggestions({
    instructions:
      "Suggest follow-up questions based on the conversation so far. " +
      "Focus on actionable next steps the user might want to take.",
    maxSuggestions: 3,
    minSuggestions: 1,
    available: "after-first-message",
  });

  return null;
}

Dynamic Suggestions with Dependencies

tsx

function ContextualSuggestions() {
  const [topic, setTopic] = useState("general");

  useConfigureSuggestions(
    {
      instructions: `Generate suggestions related to the topic: ${topic}`,
      maxSuggestions: 3,
    },
    [topic],
  );

  return (
    <select value={topic} onChange={(e) => setTopic(e.target.value)}>
      <option value="general">General</option>
      <option value="technical">Technical</option>
      <option value="business">Business</option>
    </select>
  );
}

Conditionally Disabling Suggestions

tsx

function ConditionalSuggestions({ enabled }: { enabled: boolean }) {
  useConfigureSuggestions(
    enabled
      ? {
          suggestions: [{ title: "Help", message: "I need help" }],
        }
      : null,
  );

  return null;
}

Targeting a Specific Agent

tsx

function AgentSpecificSuggestions() {
  useConfigureSuggestions({
    instructions: "Suggest data analysis tasks the user can perform.",
    maxSuggestions: 4,
    providerAgentId: "analyst",
    consumerAgentId: "analyst",
    available: "always",
  });

  return null;
}

Behavior

Automatic Registration: The configuration is registered with the core on mount and removed on unmount. This ensures clean lifecycle management.
Change Detection: The hook serializes the configuration to JSON for comparison. If the serialized value changes, the old config is removed and the new one is registered, triggering a reload.
Dependency Tracking: When a deps array is provided, any change in its values triggers a suggestion reload, even if the serialized config itself has not changed.
Config Discrimination: The hook distinguishes between dynamic and static configs by checking for the presence of the instructions property. If instructions is present, it is treated as a dynamic config.
Disabled State: Passing null, undefined, or a config with available: "disabled" will remove any previously registered configuration and produce no suggestions.
isLoading Normalization: For static suggestions, the isLoading field defaults to false if not explicitly provided.

useSuggestions -- Read and interact with configured suggestions