@copilotkit/react-core
Version:
<img src="https://github.com/user-attachments/assets/0a6b64d9-e193-4940-a3f6-60334ac34084" alt="banner" style="border-radius: 12px; border: 2px solid #d6d4fa;" />
245 lines (242 loc) • 8.15 kB
TypeScript
import { SystemMessageFunction } from '../types/system-message.js';
import { Message as Message$1 } from '@copilotkit/runtime-client-gql';
import { Message } from '@copilotkit/shared';
import { useAgent } from '@copilotkitnext/react';
import { Suggestion } from '@copilotkitnext/core';
/**
* The type of suggestions to use in the chat.
*
* `auto` - Suggestions are generated automatically.
* `manual` - Suggestions are controlled programmatically.
* `SuggestionItem[]` - Static suggestions array.
*/
type ChatSuggestions = "auto" | "manual" | Omit<Suggestion, "isLoading">[];
interface AppendMessageOptions {
/**
* Whether to run the chat completion after appending the message. Defaults to `true`.
*/
followUp?: boolean;
/**
* Whether to clear the suggestions after appending the message. Defaults to `true`.
*/
clearSuggestions?: boolean;
}
interface OnStopGenerationArguments {
/**
* The name of the currently executing agent.
*/
currentAgentName: string | undefined;
/**
* The messages in the chat.
*/
messages: Message[];
}
type OnReloadMessagesArguments = OnStopGenerationArguments & {
/**
* The message on which "regenerate" was pressed
*/
messageId: string;
};
type OnStopGeneration = (args: OnStopGenerationArguments) => void;
type OnReloadMessages = (args: OnReloadMessagesArguments) => void;
interface UseCopilotChatOptions {
/**
* A unique identifier for the chat. If not provided, a random one will be
* generated. When provided, the `useChat` hook with the same `id` will
* have shared states across components.
*/
id?: string;
/**
* HTTP headers to be sent with the API request.
*/
headers?: Record<string, string> | Headers;
/**
* Initial messages to populate the chat with.
*/
initialMessages?: Message[];
/**
* A function to generate the system message. Defaults to `defaultSystemMessage`.
*/
makeSystemMessage?: SystemMessageFunction;
/**
* Disables inclusion of CopilotKit’s default system message. When true, no system message is sent (this also suppresses any custom message from <code>makeSystemMessage</code>).
*/
disableSystemMessage?: boolean;
/**
* Controls the behavior of suggestions in the chat interface.
*
* `auto` (default) - Suggestions are generated automatically:
* - When the chat is first opened (empty state)
* - After each message exchange completes
* - Uses configuration from `useCopilotChatSuggestions` hooks
*
* `manual` - Suggestions are controlled programmatically:
* - Use `setSuggestions()` to set custom suggestions
* - Use `generateSuggestions()` to trigger AI generation
* - Access via `useCopilotChat` hook
*
* `SuggestionItem[]` - Static suggestions array:
* - Always shows the same suggestions
* - No AI generation involved
*/
suggestions?: ChatSuggestions;
onInProgress?: (isLoading: boolean) => void;
onSubmitMessage?: (messageContent: string) => Promise<void> | void;
onStopGeneration?: OnStopGeneration;
onReloadMessages?: OnReloadMessages;
}
interface MCPServerConfig {
endpoint: string;
apiKey?: string;
}
interface UseCopilotChatReturn {
/**
* @deprecated use `messages` instead, this is an old non ag-ui version of the messages
* Array of messages currently visible in the chat interface
*
* This is the visible messages, not the raw messages from the runtime client.
*/
visibleMessages: Message$1[];
/**
* The messages that are currently in the chat in AG-UI format.
*/
messages: Message[];
/** @deprecated use `sendMessage` in `useCopilotChatHeadless_c` instead. This will be removed in a future major version. */
appendMessage: (message: Message$1, options?: AppendMessageOptions) => Promise<void>;
/**
* Send a new message to the chat
*
* ```tsx
* await sendMessage({
* id: "123",
* role: "user",
* content: "Hello, process this request",
* });
* ```
*/
sendMessage: (message: Message, options?: AppendMessageOptions) => Promise<void>;
/**
* Replace all messages in the chat
*
* ```tsx
* setMessages([
* { id: "123", role: "user", content: "Hello, process this request" },
* { id: "456", role: "assistant", content: "Hello, I'm the assistant" },
* ]);
* ```
*
* **Deprecated** non-ag-ui version:
*
* ```tsx
* setMessages([
* new TextMessage({
* content: "Hello, process this request",
* role: gqlRole.User,
* }),
* new TextMessage({
* content: "Hello, I'm the assistant",
* role: gqlRole.Assistant,
* ]);
* ```
*
*/
setMessages: (messages: Message[] | Message$1[]) => void;
/**
* Remove a specific message by ID
*
* ```tsx
* deleteMessage("123");
* ```
*/
deleteMessage: (messageId: string) => void;
/**
* Regenerate the response for a specific message
*
* ```tsx
* reloadMessages("123");
* ```
*/
reloadMessages: (messageId: string) => Promise<void>;
/**
* Stop the current message generation
*
* ```tsx
* if (isLoading) {
* stopGeneration();
* }
* ```
*/
stopGeneration: () => void;
/**
* Clear all messages and reset chat state
*
* ```tsx
* reset();
* console.log(messages); // []
* ```
*/
reset: () => void;
/**
* Whether the chat is currently generating a response
*
* ```tsx
* if (isLoading) {
* console.log("Loading...");
* } else {
* console.log("Not loading");
* }
*/
isLoading: boolean;
/**
* Whether the chat agent is available to generate responses
*
* ```tsx
* if (isAvailable) {
* console.log("Loading...");
* } else {
* console.log("Not loading");
* }
*/
isAvailable: boolean;
/** Manually trigger chat completion (advanced usage) */
runChatCompletion: () => Promise<Message[]>;
/** MCP (Model Context Protocol) server configurations */
mcpServers: MCPServerConfig[];
/** Update MCP server configurations */
setMcpServers: (mcpServers: MCPServerConfig[]) => void;
/**
* Current suggestions array
* Use this to read the current suggestions or in conjunction with setSuggestions for manual control
*/
suggestions: Suggestion[];
/**
* Manually set suggestions
* Useful for manual mode or custom suggestion workflows
*/
setSuggestions: (suggestions: Omit<Suggestion, "isLoading">[]) => void;
/**
* Trigger AI-powered suggestion generation
* Uses configurations from useCopilotChatSuggestions hooks
* Respects global debouncing - only one generation can run at a time
*
* ```tsx
* generateSuggestions();
* console.log(suggestions); // [suggestion1, suggestion2, suggestion3]
* ```
*/
generateSuggestions: () => Promise<void>;
/**
* Clear all current suggestions
* Also resets suggestion generation state
*/
resetSuggestions: () => void;
/** Whether suggestions are currently being generated */
isLoadingSuggestions: boolean;
/** Interrupt content for human-in-the-loop workflows */
interrupt: string | React.ReactElement | null;
agent?: ReturnType<typeof useAgent>["agent"];
threadId?: string;
}
declare function useCopilotChatInternal({ suggestions, onInProgress, onSubmitMessage, onStopGeneration, onReloadMessages, }?: UseCopilotChatOptions): UseCopilotChatReturn;
declare function defaultSystemMessage(contextString: string, additionalInstructions?: string): string;
export { AppendMessageOptions, ChatSuggestions, MCPServerConfig, OnReloadMessages, OnReloadMessagesArguments, OnStopGeneration, OnStopGenerationArguments, UseCopilotChatOptions, UseCopilotChatReturn, defaultSystemMessage, useCopilotChatInternal };