---
title: Human-in-the-Loop
icon: "lucide/User"
description: Create frontend tools and use them within your LlamaIndex agent for human-in-the-loop interactions.
---

<IframeSwitcher
  id="frontend-tools-based-hitl-example"
  exampleUrl="https://feature-viewer.copilotkit.ai/llama-index/feature/human_in_the_loop?sidebar=false&chatDefaultOpen=false"
  codeUrl="https://feature-viewer.copilotkit.ai/llama-index/feature/human_in_the_loop?view=code&sidebar=false&codeLayout=tabs"
  exampleLabel="Demo"
  codeLabel="Code"
  height="700px"
/>

## What is this?

Frontend tools enable you to define client-side functions that your LlamaIndex 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](/llamaindex/frontend-tools), [generative UI](/llamaindex/frontend-tools), 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

<Steps>
    <Step>
      ### Run and connect your agent
      <RunAndConnect />
    </Step>

    <Step>
        ### Add a tool to your agent
        Add a tool to your agent that will be used to write an essay. Since the tool will be used in the frontend,
        we'll add it to the `frontend_tools` list.

        ```python title="agent.py"
        from fastapi import FastAPI
        from llama_index.llms.openai import OpenAI
        from llama_index.protocols.ag_ui.router import get_ag_ui_workflow_router

        def offerOptions(option_1: str, option_2: str) -> str:
            """Give the user a choice between two options and have them select one."""
            return f"Presenting options: {option_1} or {option_2}"

        # Initialize the LLM
        llm = OpenAI(model="gpt-5.4")

        # Create the AG-UI workflow router
        agentic_chat_router = get_ag_ui_workflow_router(
            llm=llm,
            frontend_tools=[offerOptions],
            system_prompt="You are a helpful AI assistant that can write essays. When the user asks you to choose between two options or when you need to present them with a choice, you MUST use the offerOptions tool to let them select between the options.",
        )

        # Create FastAPI app
        app = FastAPI(
            title="LlamaIndex Agent",
            description="A LlamaIndex agent integrated with CopilotKit",
            version="1.0.0"
        )

        # Include the router
        app.include_router(agentic_chat_router)

        # Health check endpoint
        @app.get("/health")
        async def health_check():
            return {"status": "healthy", "agent": "llamaindex"}

        if __name__ == "__main__":
            uvicorn.run(app, host="localhost", port=8000)
        ```
    </Step>

    <Step>
        ### 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.

        ```tsx title="page.tsx"

        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>
                  {/* [!code highlight:2] */}
                  <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>
              );
            },
          });

          // ...
        }
        ```

        That's it! Your agent will automatically have access to all human-in-the-loop tools you've defined using `useHumanInTheLoop` in your React components.

        <Callout type="info">
          Human-in-the-loop tools registered with `useHumanInTheLoop` are automatically forwarded to your agent through the AG-UI protocol.
        </Callout>
    </Step>
    <Step>
        ### 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?
        ```
    </Step>

</Steps>
