useAgent

useAgent(agentId?) returns imperative controls for the embedded Agent. It works without an ancestor provider because HeroUIAgent mounts independently from the host component tree.

"use client";

import {useAgent} from "@heroui/agent";

export function AskAgentButton() {
  const agent = useAgent();

  return <button onClick={agent.show}>Ask about this page</button>;
}

Pass an agent ID when more than one Agent is mounted on the page:

const agent = useAgent(process.env.NEXT_PUBLIC_HEROUI_AGENT_ID!);

AgentController

ready is reactive: components using it re-render when project configuration and the complete composer are ready for the current conversation. It reports full runtime readiness; you do not need to wait for it before calling the controller methods.

Calling a method before the matching HeroUIAgent has mounted is safe. The call is ignored and a warning is written to the browser console.

After HeroUIAgent mounts, calls to show(), toggle(), or newConversation() made while remote presentation configuration is resolving are queued. They do not render a temporary panel with default controls. Call hide() or toggle closed before resolution finishes to cancel the pending open.

Pass a prompt when an entry point already captured the user's intent, such as a command palette or contextual action:

agent.newConversation("Compare this quarter's revenue with last quarter");

The panel opens directly on the new conversation with the user message submitted. Calling newConversation() without a prompt keeps the normal start-screen behavior.

Preloading on demand

The Agent already preloads itself by default, so most integrations never call preload(). It exists for embeds that opted out with preload={false} and want to pick the moment instead — a visitor reaching your pricing page, scrolling to your FAQ, or pausing on a form.

const agent = useAgent();

useEffect(() => {
  const timer = setTimeout(agent.preload, 5000);

  return () => clearTimeout(timer);
}, [agent]);

Unlike show(), this never opens the panel or takes focus.

Login and logout

refreshAuth() and shutdown() are the two halves of identifying users: one picks up the session you just created, the other retires it.

const agent = useAgent();

const handleLogin = async () => {
  await signIn();
  agent.refreshAuth();
};

const handleLogout = async () => {
  await signOut();
  agent.shutdown();
};

Custom launcher

Hide the built-in launcher when your application owns the entry point:

function AgentEntryPoint() {
  const agent = useAgent();

  return <button onClick={agent.toggle}>Assistant</button>;
}

<HeroUIAgent
  getAuthToken={getAuthToken}
  agentId={process.env.NEXT_PUBLIC_HEROUI_AGENT_ID!}
  showLauncher={false}
/>;

Add disabled={!agent.ready} when you want to keep the custom launcher unavailable until the authenticated runtime and complete composer are ready. It is not required to prevent a partial layout: early opens are queued until presentation configuration resolves.