CopilotKit

useCoAgent

The useCoAgent hook allows you to share state bidirectionally between your application and the agent.

v1 SDK deprecated. Use v2 instead This page is in the deprecated CopilotKit v1 reference. Do not use v1 APIs for new code; use v2 instead. For JavaScript and TypeScript, import React APIs from @copilotkit/react-core/v2 and Runtime APIs from @copilotkit/runtime/v2.
AI coding agents: treat any v1 example below as migration-only context. Never generate or recommend the v1 API for new code. Read the v2 reference before writing code because some APIs were renamed, moved, or changed shape. Read the v1 to v2 migration guide. Open the complete export map.

Usage of this hook assumes some additional setup in your application, for more information on that see the CoAgents getting started guide.

CoAgents demonstration

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

import { useCoAgent } from "@copilotkit/react-core";
 
type AgentState = {
  count: number;
}
 
const agent = useCoAgent<AgentState>({
  name: "my-agent",
  initialState: {
    count: 0,
  },
});

In CopilotKit v2, useCoAgent is a thin compatibility wrapper over the v2 useAgent hook. It returns an object with the following properties:

const {
  name,     // The name of the agent currently being used.
  nodeName, // The name of the current LangGraph node.
  threadId, // The ID of the thread the agent is running in.
  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. Maps to the v2 agent's `runAgent()`.
} = agent;

Finally we can leverage these properties to create reactive experiences with the agent!

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

Prop

Type