Human-in-the-Loop
Create frontend tools and use them within your Pydantic AI agent for human-in-the-loop interactions.
What is this?
Frontend tools enable you to define client-side functions that your Pydantic AI 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 Human-in-the-loop.
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 human-in-the-loop tool
Frontend tools can be leveraged in a variety of ways. One of those ways is to have a human-in-the-loop flow where the response of the tool is gated by a user's decision.
In this example we will simulate an "approval" flow for executing a command. First, use the useHumanInTheLoop hook to create a tool that
prompts the user for approval.
import { useHumanInTheLoop } from "@copilotkit/react-core"
export function Page() {
// ...
useHumanInTheLoop({
name: "offerOptions",
description: "Give the user a choice between two options and have them select one.",
parameters: [
{
name: "option_1",
type: "string",
description: "The first option",
required: true,
},
{
name: "option_2",
type: "string",
description: "The second option",
required: true,
},
],
render: ({ args, respond }) => {
if (!respond) return <></>;
return (
<div>
<button onClick={() => respond(`${args.option_1} was selected`)}>{args.option_1}</button>
<button onClick={() => respond(`${args.option_2} was selected`)}>{args.option_2}</button>
</div>
);
},
});
// ...
}Set up your agent
Pydantic AI automatically picks up human-in-the-loop tools when you create your agent. No special configuration is needed:
from pydantic_ai import Agent
agent = Agent('openai:gpt-4o-mini')
app = agent.to_ag_ui()The frontend tools are automatically populated by CopilotKit through the AG-UI protocol and are available to your agent.
Try it out!
You've now given your agent the ability to show the user two options and have them select one. The agent will then be aware of the user's choice and can use it in subsequent steps.
Can you show me two good options for a restaurant name?
