Frontend Tools
Create frontend tools and use them within your AWS Strands agent.
What is this?
Frontend tools enable you to define client-side functions that your AWS 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 for generative 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
Run and connect your agent
You'll need to run your agent and connect it to CopilotKit before proceeding.
If you don't already have CopilotKit and your agent connected, choose one of the following options:
Create a frontend tool
Create a frontend tool using the useFrontendTool hook. Here's a simple example that says hello to the user.
import { useFrontendTool } from "@copilotkit/react-core"
export function Page() {
// ...
useFrontendTool({
name: "sayHello",
description: "Say hello to the user",
parameters: [
{
name: "name",
type: "string",
description: "The name of the user to say hello to",
required: true,
},
],
handler({ name }) {
// Handler returns the result of the tool call
return { currentURLPath: window.location.href, userName: name };
},
render: ({ args }) => {
// Renders UI based on the data of the tool call
return (
<div>
<h1>Hello, {args.name}!</h1>
<h1>You're currently on {window.location.href}</h1>
</div>
);
},
});
// ...
}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.
import os
from strands import Agent, tool
from strands.models.openai import OpenAIModel
from ag_ui_strands import StrandsAgent, create_strands_app
@tool
def sayHello(name: str):
"""
Say hello to the user.
Args:
name: The name of the user to say hello to
Returns:
None - execution happens on the frontend
"""
# Return None - frontend will handle execution
return None
api_key = os.getenv("OPENAI_API_KEY", "")
model = OpenAIModel(
client_args={"api_key": api_key},
model_id="gpt-4o",
)
agent = Agent(
model=model,
tools=[sayHello],
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, "/")Frontend tools in Strands require explicit tool registration on both agent and frontend sides. This gives you full control over what the agent can do.
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.
