CopilotKit

useAgent

React hook for accessing AG-UI agent instances

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.

useAgent is a v2 API, exported from @copilotkit/react-core/v2. See the v2 useAgent reference for the full, up-to-date documentation.

Overview

useAgent is a React hook that returns an AG-UI AbstractAgent instance. The hook subscribes to agent state changes and triggers re-renders when the agent's state, messages, or execution status changes.

Throws error if no agent is configured with the specified agentId.

Signature

function useAgent(options?: UseAgentProps): { agent: AbstractAgent }

Parameters

Prop

Type

Return Value

Prop

Type

Usage

Basic Usage

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

function AgentStatus() {
  const { agent } = useAgent();

  return (
    <div>
      <div>Agent: {agent.agentId}</div>
      <div>Messages: {agent.messages.length}</div>
      <div>Running: {agent.isRunning ? "Yes" : "No"}</div>
    </div>
  );
}

Accessing State

function StateDisplay() {
  const { agent } = useAgent();

  return <pre>{JSON.stringify(agent.state, null, 2)}</pre>;
}

Updating State

function StateController() {
  const { agent } = useAgent();

  return (
    <button onClick={() => agent.setState({ ...agent.state, count: 1 })}>
      Increment
    </button>
  );
}

Event Subscription

import { useEffect } from "react";
import { useAgent } from "@copilotkit/react-core/v2";
import type { AgentSubscriber } from "@ag-ui/client";

function EventListener() {
  const { agent } = useAgent();

  useEffect(() => {
    const { unsubscribe } = agent.subscribe({
      onRunStartedEvent: () => console.log("Started"),
      onRunFinalized: () => console.log("Finished"),
    });

    return unsubscribe;
  }, []);

  return null;
}

Multiple Agents

function MultiAgentView() {
  const { agent: primary } = useAgent({ agentId: "primary" });
  const { agent: support } = useAgent({ agentId: "support" });

  return (
    <div>
      <div>Primary: {primary.messages.length}</div>
      <div>Support: {support.messages.length}</div>
    </div>
  );
}

Optimizing Re-renders

Control when your component re-renders using the updates parameter:

import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2";

// Only re-render when messages change
function MessageCount() {
  const { agent } = useAgent({
    updates: [UseAgentUpdate.OnMessagesChanged]
  });

  return <div>Messages: {agent.messages.length}</div>;
}

// Manually manage subscriptions (no automatic re-renders)
function ManualSubscription() {
  const { agent } = useAgent({ updates: [] });

  useEffect(() => {
    const { unsubscribe } = agent.subscribe({
      onMessagesChanged: () => {
        // Handle changes manually
      }
    });
    return unsubscribe;
  }, [agent]);

  return <div>Manual mode</div>;
}

Behavior

  • Automatic Re-renders: Component re-renders when agent state, messages, or execution status changes (configurable via updates parameter)
  • Error Handling: Throws error if no agent exists with specified agentId
  • State Synchronization: State updates via setState() are immediately available to both app and agent
  • Event Subscriptions: Subscribe/unsubscribe pattern for lifecycle and custom events

Related