ContextQMD
Back to Copilotkit

Programmatic Control

showcase/shell-docs/src/content/snippets/shared/basics/programmatic-control.mdx

1.57.02.9 KB
Original Source

import { MessageCircle, Database, Zap, BookOpen, Play, Settings, } from "lucide-react";

Overview

The useAgent hook provides direct access to your agent from any React component. It gives you real-time access to the agent's state, messages, execution status, and allows you to subscribe to custom events.

This enables you to build custom agent dashboards, monitoring tools, and interactive features that respond to your agent's behavior.

<Cards className="gap-6 mt-6 mb-8"> <Card icon={<Play className="text-primary" />} className="p-6 rounded-xl text-base" title="Running the Agent" description="Trigger your agent programmatically with copilotkit.runAgent()." href="#running-the-agent-programmatically" /> <Card icon={<Settings className="text-primary" />} className="p-6 rounded-xl text-base" title="Fully Headless UI" description="Build a completely custom chat interface from the ground up using CopilotKit's headless hooks." href="custom-look-and-feel/headless-ui" /> </Cards>

import UseAgentSnippet from "@/snippets/use-agent.mdx";

<UseAgentSnippet components={props.components} />

Running the Agent Programmatically

Use copilotkit.runAgent() to trigger your agent from any component — no chat UI required. This is the same method CopilotKit's built-in <CopilotChat /> uses internally.

tsx
import { useAgent } from "@copilotkit/react-core/v2";
import { useCopilotKit } from "@copilotkit/react-core/v2";
import { randomUUID } from "@copilotkit/shared/v2";

export function AgentTrigger() {
  const { agent } = useAgent();
  // [!code highlight:1]
  const { copilotkit } = useCopilotKit();

  const handleRun = async () => {
    // Add a user message to the agent's conversation
    agent.addMessage({
      id: randomUUID(),
      role: "user",
      content: "Summarize the latest sales data",
    });

    // [!code highlight:2]
    // Run the agent — handles tool execution, follow-ups, and streaming
    await copilotkit.runAgent({ agent });
  };

  return <button onClick={handleRun}>Run Agent</button>;
}

copilotkit.runAgent() vs agent.runAgent()

Both methods trigger the agent, but they operate at different levels:

  • copilotkit.runAgent({ agent }) — The recommended approach. Orchestrates the full agent lifecycle: executes frontend tools, handles follow-up runs when tools request them, and manages errors through the subscriber system.
  • agent.runAgent() — Low-level method on the agent instance. Sends the request to the runtime but does not execute frontend tools or handle follow-ups. Use this only when you need direct control over the agent execution (e.g., resuming from an interrupt with forwardedProps).

Stopping a Run

You can stop a running agent using copilotkit.stopAgent():

tsx
const handleStop = () => {
  copilotkit.stopAgent({ agent });
};