Frontend Tools

"""LangGraph agent backing the Chat Customization (CSS) demo.The demo is about CSS — the agent has no custom tools or behavior.CopilotKitMiddleware is attached so CopilotKit-specific context ispicked up if the frontend ever registers suggestions/components."""from langchain.agents import create_agentfrom langchain_openai import ChatOpenAIfrom copilotkit import CopilotKitMiddlewaregraph = create_agent(    model=ChatOpenAI(model="gpt-4o-mini"),    tools=[],    middleware=[CopilotKitMiddleware()],    system_prompt="You are a helpful, concise assistant.",)

What is this?#

Frontend tools let your agent define and invoke client-side functions that run entirely in the user's browser. Because the handler executes on the frontend, it has direct access to component state, browser APIs, and any third-party UI library the page already uses. That's how an agent can "reach into" the app: update React state, trigger animations, read localStorage, pop a toast, or steer the user's view.

This page covers the "agent drives the UI" shape of frontend tools. The same primitive also powers Generative UI and Human-in-the-loop; see those pages for interaction patterns.

When should I use this?#

Use frontend tools when your agent needs to:

Read or modify React component state
Access browser APIs like localStorage, sessionStorage, or cookies
Trigger UI updates, animations, or transitions
Show alerts, toasts, or notifications
Interact with third-party frontend libraries
Perform anything that requires the user's immediate browser context

How it works in code#

Install the LangGraph Python 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

Wire CopilotKit middleware into your graph

Frontend tools registered with useFrontendTool are forwarded to your agent at runtime. CopilotKitMiddleware is the bridge — drop it into create_agent's middleware list and the LLM sees the forwarded tool definitions on every turn.

frontend_tools.py

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from copilotkit import CopilotKitMiddleware

graph = create_agent(
    model=ChatOpenAI(model="gpt-5.4"),
    tools=[],
    middleware=[CopilotKitMiddleware()],
    system_prompt="You are a helpful, concise assistant.",
)

Register a frontend tool with useFrontendTool. Give it a name, a Zod schema for parameters, and a handler. The agent can then call it like any other tool and your frontend runs it in the browser.

page.tsx

import React, { useState } from "react";import {  CopilotKit,  CopilotSidebar,  useFrontendTool,} from "@copilotkit/react-core/v2";import { z } from "zod";import { Background, DEFAULT_BACKGROUND } from "./background";import { useFrontendToolsSuggestions } from "./suggestions";function Chat() {  const [background, setBackground] = useState<string>(DEFAULT_BACKGROUND);  useFrontendTool({    name: "change_background",    description:      "Change the page background. Accepts any valid CSS background value — colors, linear or radial gradients, etc.",    parameters: z.object({      background: z        .string()        .describe("The CSS background value. Prefer gradients."),    }),    handler: async ({ background }) => {      setBackground(background);      return { status: "success" };    },  });

The handler receives the parsed, type-safe parameters and can do anything the browser can: update state, call an API, touch the DOM. Its return value is sent back to the agent as the tool result so the model can reason about what happened.