CopilotKit

useConfigureSuggestions

Vue 3 composable for configuring chat suggestions

Overview

useConfigureSuggestions 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 registered while the composable's reactive scope is active and removed automatically on scope cleanup (component unmount). Because the config is tracked reactively, changing it (or any value in the optional deps watch sources) reloads suggestions automatically without manual teardown.

useConfigureSuggestions must be called within a component that has access to the CopilotKit instance provided by CopilotKitProvider. Like all Vue composables, call it synchronously inside <script setup> or a setup() function so its reactive scope is bound to the component lifecycle.

Signature

import { useConfigureSuggestions } from "@copilotkit/vue/v2";

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

Parameters

Prop

Type

Prop

Type

Usage

Static Suggestions

<script setup lang="ts">
import { useConfigureSuggestions } from "@copilotkit/vue/v2";

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",
});
</script>

<template>
  <div>Suggestions configured</div>
</template>

Dynamic Suggestions

<script setup lang="ts">
import { useConfigureSuggestions } from "@copilotkit/vue/v2";

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",
});
</script>

<template>
  <div>Smart suggestions enabled</div>
</template>

Dynamic Suggestions with Reactive Dependencies

Pass watch sources as the second argument so suggestions reload whenever the underlying reactive state changes.

<script setup lang="ts">
import { ref } from "vue";
import { useConfigureSuggestions } from "@copilotkit/vue/v2";

const reloadKey = ref(0);

// `deps` re-runs (reloads) suggestion generation whenever a watch source
// changes. The `config` -- including the `instructions` string -- is captured
// once when the composable runs and is not re-read.
useConfigureSuggestions(
  {
    instructions: "Suggest concise next steps based on the current conversation",
    maxSuggestions: 3,
  },
  [reloadKey],
);
</script>

<template>
  <button @click="reloadKey++">Refresh suggestions</button>
</template>

The config object is captured once from the surrounding scope when the composable runs. Internally it is serialized and watched, so the registration does re-run if the config's reactive contents change — but a config built from plain (non-reactive) locals never changes, so in practice it is read once. Use deps to reload (regenerate) suggestions from that captured config. To change the instructions themselves at runtime (for example to inject a reactive topic), remount the component that calls useConfigureSuggestions -- e.g. give it a :key that changes -- so the composable re-runs with the new values.

Conditionally Disabling Suggestions

Pass null (or a config with available: "disabled") to skip registering a configuration.

<script setup lang="ts">
import { computed } from "vue";
import { useConfigureSuggestions } from "@copilotkit/vue/v2";

const props = defineProps<{ enabled: boolean }>();

useConfigureSuggestions(
  props.enabled
    ? { suggestions: [{ title: "Help", message: "I need help" }] }
    : null,
);
</script>

<template>
  <div>Conditional suggestions</div>
</template>

Like the dynamic config above, the enabled branch is evaluated once when the composable runs — flipping props.enabled later does not re-register or remove the configuration. To turn suggestions on or off at runtime, conditionally render the component that calls useConfigureSuggestions (for example with v-if) so the composable re-runs and its previous configuration is removed on cleanup.

Targeting a Specific Agent

<script setup lang="ts">
import { useConfigureSuggestions } from "@copilotkit/vue/v2";

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

<template>
  <div>Agent-specific suggestions</div>
</template>

Behavior

  • Scope lifecycle: The configuration is registered with the core via addSuggestionsConfig while the composable's reactive scope is active and removed via removeSuggestionsConfig on scope cleanup (component unmount). No manual cleanup is required.
  • Reactive change detection: The hook serializes the normalized configuration to JSON for comparison. When the serialized value changes, the registration is updated and a reload is triggered.
  • Dependency tracking: When a deps array of watch sources is provided, any change in those sources 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" removes any previously registered configuration and produces no suggestions.
  • isLoading normalization: For static suggestions, the isLoading field defaults to false if not explicitly provided.
  • Consumer resolution: A config with consumerAgentId of "*" (or unset) is treated as global and applies to all agents; otherwise it targets the named agent. The resolved consumer falls back to the chat configuration's agentId, then to the default agent ID.
  • Reload while running: Global reloads are deferred for any agent that is currently running and flushed once that run finishes, so suggestions are not reloaded mid-run.

Related