Frontend Tools - Copilotkit

What is this?

Frontend tools enable you to define client-side functions that your Strands 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, 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

Implementation

<Callout> Check out the [Frontend Tools overview](/aws-strands/frontend-tools) to understand what they are and when to use them. </Callout> <Steps> <Step> ### Run and connect your agent <RunAndConnect /> </Step>

<Step>
    ### Register the frontend tool in your agent

    In your Strands agent, define a tool that returns `None`. This registers the tool with the LLM so it knows about it,
    but the actual execution will happen on the frontend.

    ```python title="main.py"
    from strands import Agent, tool
    from strands.models.openai import OpenAIModel
    from ag_ui_strands import StrandsAgent, create_strands_app

    @tool
    def change_background(background: str):
        """
        Change the background color of the chat. Can be anything that CSS accepts.

        Args:
            background: The background color or gradient. Prefer gradients.

        Returns:
            None - execution happens on the frontend
        """
        # Return None - frontend will handle execution
        return None  # [!code highlight]

    api_key = os.getenv("OPENAI_API_KEY", "")
    model = OpenAIModel(
        client_args={"api_key": api_key},
        model_id="gpt-5.4",
    )

    agent = Agent(
        model=model,
        tools=[change_background],  # [!code highlight]
        system_prompt="You are a helpful assistant.",
    )

    agui_agent = StrandsAgent(
        agent=agent,
        name="my_agent",
        description="A helpful assistant",
    )

    app = create_strands_app(agui_agent, "/")
    ```
</Step>

<Step>
    ### Create the frontend tool handler

    Create a frontend tool using the [useFrontendTool](/reference/v1/hooks/useFrontendTool) hook. The name must match
    the tool name defined in your agent.

    ```tsx title="app/page.tsx"
    "use client";


    export default function Page() {
      const [background, setBackground] = useState("#6366f1");

      // [!code highlight:12]
      useFrontendTool({
        name: "change_background",
        description: "Change the background color of the chat.",
        parameters: z.object({
          background: z.string().describe("The background color or gradient. Prefer gradients."),
        }),
        handler: async ({ background }) => {
          setBackground(background);
          return `Background changed to ${background}`;
        },
      });

      return (
        <main
          style={{
            background,
            transition: "background 0.3s ease",
          }}
          className="h-screen"
        >
          <CopilotSidebar />
        </main>
      );
    }
    ```
</Step>
<Step>
    ### Give it a try!

    Try asking the agent to change the background:

    ```
    Change the background to a sunset gradient
    ```

    ```
    Make the background dark purple
    ```

    You should see the background change in real-time as the agent calls your frontend tool!

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

</Steps>

Accessing React state

Frontend tools have full access to the DOM - including your React component state. For example, you can have your agent trigger re-renders via the useFrontendTool hook.

tsx

"use client";

export default function Page() {
  const [tasks, setTasks] = useState<string[]>([]);

  useFrontendTool({
    name: "add_task",
    description: "Add a task to the todo list",
    parameters: z.object({
      task: z.string().describe("The task to add"),
    }),
    handler: async ({ task }) => {
      setTasks((prev) => [...prev, task]);
      return `Added task: ${task}`;
    },
  });

  return (
    <div>
      <h1>Todo List</h1>
      <ul>
        {tasks.map((task, i) => (
          <li key={i}>{task}</li>
        ))}
      </ul>
    </div>
  );
}

Remember to define the corresponding tool in your Strands agent that returns None!