Display-only

Run and connect your agent#

You'll need to run your agent and connect it to CopilotKit before proceeding. If you haven't done so already, you can follow the instructions in the Getting Started guide.

If you don't already have an agent, you can use the coagent starter as a starting point as this guide uses it as a starting point.

Register a component#

Use the useComponent hook to register a React component. The agent will be able to call it by name, and CopilotKit will render it with the tool arguments as props.

import { useComponent } from "@copilotkit/react-core/v2"; 
import { z } from "zod";

const weatherSchema = z.object({
  city: z.string().describe("City name"),
  temperature: z.number().describe("Temperature in Fahrenheit"),
  condition: z.string().describe("Weather condition"),
});

function WeatherCard({ city, temperature, condition }: z.infer<typeof weatherSchema>) {
  return (
    <div className="rounded-lg border p-4">
      <h3 className="font-semibold">{city}</h3>
      <p className="text-2xl">{temperature}°F</p>
      <p className="text-sm text-gray-500">{condition}</p>
    </div>
  );
}

function YourMainContent() {
  useComponent({
    name: "showWeather",
    description: "Display a weather card for a city.",
    parameters: weatherSchema,
    render: WeatherCard,
  });

  return <div>{/* ... */}</div>;
}

Install the CopilotKit SDK#

Now, we'll need to make sure your agent can access frontend tools. In your terminal, navigate to your agent's folder and continue from there.

Any LangGraph agent can be used with CopilotKit. However, creating deep agentic experiences with CopilotKit requires our LangGraph SDK.

uv add copilotkit

poetry add copilotkit

pip install copilotkit --extra-index-url https://copilotkit.gateway.scarf.sh/simple/

conda install copilotkit -c copilotkit-channel

Inherit from CopilotKitState#

To access the frontend tools provided by CopilotKit, inherit from CopilotKitState in your agent's state definition:

from copilotkit import CopilotKitState 

class AgentState(CopilotKitState): 
    pass

import { StateSchema } from "@langchain/langgraph";
import { CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph"; 

export const AgentStateSchema = new StateSchema({
  ...CopilotKitStateSchema.fields, 
});
export type AgentState = typeof AgentStateSchema.State;

Agent calls the component#

When your agent's LLM decides to use the tool, CopilotKit automatically renders your component in the chat. The tool is registered as a frontend tool that the agent can discover and call.

What is this?#

Frontend tools enable you to define client-side functions that your agent can invoke, with execution happening entirely in the user's browser. When your agent calls a frontend tool, the logic runs on the client side, giving you direct access to the frontend environment.

This can be utilized to let your agent control the UI, for generative UI, or for Human-in-the-loop interactions. In this guide, we cover the use of frontend tools driving and interacting with the UI.

When should I use this?#

Use frontend tools when you need your agent to interact with client-side primitives such as:

• Reading or modifying React component state
• Accessing browser APIs like localStorage, sessionStorage, or cookies
• Triggering UI updates or animations
• Interacting with third-party frontend libraries
• Performing actions that require the user's immediate browser context

Create a frontend tool#

Use the useFrontendTool hook to create a tool that your agent can call from the client side:

import { z } from "zod";
import { useFrontendTool } from "@copilotkit/react-core/v2"; 

export function Page() {
  // ...

  useFrontendTool({
    name: "sayHello",
    description: "Say hello to the user",
    parameters: z.object({
      name: z.string().describe("The name of the user to say hello to"),
    }),
    handler: async ({ name }) => {
      alert(`Hello, ${name}!`);
      return `Said hello to ${name}!`;
    },
  });

  // ...
}

Give it a try!#

Ask your agent something that would trigger the component (e.g. "What's the weather in San Francisco?"). You should see your WeatherCard rendered directly in the chat.