CopilotKit

useAgent

React hook for accessing AG-UI agent instances

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