Frontend Tools

<Step>
    ### Create a frontend tool

    First, you'll need to create a frontend tool using the [useFrontendTool](/reference/v2/hooks/useFrontendTool) hook. Here's a simple one to get you started
    that says hello to the user.

    ```tsx title="page.tsx"
    import { z } from "zod";
    import { useFrontendTool } from "@copilotkit/react-core/v2" // [!code highlight]

    export function Page() {
      // ...

      // [!code highlight:12]
      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}!`;
        },
      });

      // ...
    }
    ```
</Step>
<Step>
    ### Install the CopilotKit SDK

    Now, we'll need to modify the agent to access these frontend tools. In your terminal, navigate to your agent's folder and continue from there!

    <InstallSDKSnippet/>
</Step>
<Step>
    ### Inheriting from CopilotKitState

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

    <Tabs groupId="language_langgraph_agent" items={['Python', 'TypeScript']} default="Python" persist>
        <Tab value="Python">
            ```python title="agent.py"
            from copilotkit import CopilotKitState # [!code highlight]

            class YourAgentState(CopilotKitState): # [!code highlight]
                your_additional_properties: str
            ```
        </Tab>
        <Tab value="TypeScript">
            ```typescript title="agent-js/src/agent.ts"
            import { StateSchema } from "@langchain/langgraph";
            import { CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph"; // [!code highlight]
            import { z } from "zod";

            export const YourAgentStateSchema = new StateSchema({
                yourAdditionalProperty: z.string(),
                ...CopilotKitStateSchema.fields, // [!code highlight]
            });
            export type YourAgentState = typeof YourAgentStateSchema.State;
            ```
        </Tab>
    </Tabs>

    By doing this, your agent's state will include the `copilotkit` property, which contains the frontend tools that can be accessed and invoked.
</Step>
<Step>
    ### Accessing Frontend Tools

    Once your agent's state includes the `copilotkit` property, you can access the frontend tools and utilize them within your agent's logic.

    Here's how you can call a frontend tool from your agent:

    <FrontEndToolsImpl />

    These tools are automatically populated by CopilotKit and are compatible with LangChain's tool call definitions, making it straightforward to integrate them into your agent's workflow.
</Step>
<Step>
    ### Give it a try!
    You've now given your agent the ability to directly call any frontend tools you've defined. These tools will be available to the agent where they can be used as needed.

    <video src="https://cdn.copilotkit.ai/docs/copilotkit/images/frontend-actions-demo.mp4" className="rounded-lg shadow-xl" loop playsInline controls autoPlay muted />
</Step>

    graph = create_agent( # Works the same for "create_react_agent" or similar options
        model="openai:gpt-4o",
        tools=[],  # backend tools go here
        middleware=[CopilotKitMiddleware()],
        state_schema=CopilotKitState,
        # [!code highlight:7]
        # Tell the agent WHEN it must call the frontend tool.
        # A short description alone may not be enough — make the rule explicit.
        system_prompt=(
            "You are a helpful sales assistant.\n\n"
            "IMPORTANT: When the user asks about sales data for a specific month or date range, "
            "you MUST call the `fetch_sales_by_month_range` frontend tool first to retrieve "
            "up-to-date figures. Never answer from memory or previously seen context values."
        ),
    )
    ```
</Tab>
<Tab value="TypeScript">
    ```typescript title="agent-js/src/agent.ts"
    import { createAgent } from "langchain";
    import { copilotkitMiddleware, CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph";

    export const graph = createAgent({ // Works the same for "create_react_agent" or similar options
      model: "openai:gpt-4o",
      tools: [],  // backend tools go here
      stateSchema: CopilotKitStateSchema,
      middleware: [copilotkitMiddleware],
      // [!code highlight:6]
      // Tell the agent WHEN it must call the frontend tool.
      // A short description alone may not be enough — make the rule explicit.
      systemPrompt:
        "You are a helpful sales assistant.\n\n" +
        "IMPORTANT: When the user asks about sales data for a specific month or date range, " +
        "you MUST call the `fetch_sales_by_month_range` frontend tool first to retrieve " +
        "up-to-date figures. Never answer from memory or previously seen context values.",
    });
    ```
</Tab>

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

useFrontendTool({
  name: "fetch_sales_by_month_range",
  // [!code highlight:3]
  // Keep the description accurate so the model understands the tool's contract,
  // but rely on system_prompt to enforce WHEN it is called.
  description:
    "Fetches sales overview data for the given month range from the live API and updates the dashboard. " +
    "Returns a summary of revenue and order counts for the requested period.",
  parameters: z.object({
    start_month: z.string().describe("Start month in YYYY-MM format"),
    end_month: z.string().describe("End month in YYYY-MM format"),
  }),
  handler: async ({ start_month, end_month }) => {
    const data = await fetchSalesOverview({ start_month, end_month });
    updateDashboard(data);
    return `Fetched sales data from ${start_month} to ${end_month}: revenue=${data.revenue}, orders=${data.orders}`;
  },
});