Install HeroUI Agent and its required styles in a React or Next.js application.
Next.js is not required. If your application uses Next.js, the Agent's Next.js entry point requires Next.js 15 or newer.
Next.js 16 + Sentry
Hosts on Next.js 16 with Sentry (especially tunnelRoute) may see
MaxListenersExceededWarning on ServerResponse. Next itself attaches 6+ close listeners per
response; the Agent only adds more requests (auth token, root-layout CSS, widget), so the warning
shows up more often. The Agent does not attach those EventEmitter listeners. Workaround: raise
ServerResponse max listeners on the Node process, or wait for a Next.js fix.
HeroUI Agent is currently an invite-only beta. You need a provisioned agent ID and a project API key before the embed can connect to the hosted runtime. Request beta access if you do not have them yet.
Open Agents in the Pro dashboard, select your Agent, and copy
its Agent ID. Then open API keys for that Agent and create a key with
auth_tokens:create permission.
Install @heroui/agent. React and React DOM are the only peer dependencies you provide yourself;
everything else the Agent needs ships with it.
npm install @heroui/agent@betapnpm add @heroui/agent@betayarn add @heroui/agent@betabun add @heroui/agent@betaWriting client tools with Zod?
Add zod to your own dependencies as well. It ships inside @heroui/agent, but strict package
managers such as pnpm do not let application code import a package it did not declare. Tools that
use raw JSON Schema for parameters need nothing extra.
Import the Agent stylesheet from your global CSS entry:
@import "@heroui/agent/css";Keep the API key and a server-side copy of the Agent ID in your server environment. The embed also needs the Agent ID in the browser:
HEROUI_AGENT_API_KEY=he_...
HEROUI_AGENT_ID=your_agent_id
NEXT_PUBLIC_HEROUI_AGENT_ID=your_agent_idHEROUI_AGENT_API_KEY=he_...
HEROUI_AGENT_ID=your_agent_id
VITE_HEROUI_AGENT_ID=your_agent_idHEROUI_AGENT_API_KEY must stay server-only. The Agent ID is safe to expose; it identifies the
Agent but does not authorize requests.
| Use | Import |
|---|---|
| Next.js App Router embed | @heroui/agent/next |
| Vite embed | @heroui/agent |
| TanStack Start embed | @heroui/agent |
| React Router Framework Mode | @heroui/agent |
| Server-side token exchange | @heroui/agent/server |
| Shared protocol contracts | @heroui/agent/contracts |
The React and Next.js entry points expose the same public SDK. The Next.js entry point is packaged
for App Router applications and is the recommended import in Next.js projects. Every framework
uses @heroui/agent/server on the server to exchange the API key for short-lived browser tokens.
Both entry points and the server helper use https://api.heroui.pro by default.
Continue to the Quickstart to create a token endpoint, mount the embed, and send your first message.
Pin an exact prerelease version in production and review the changelog before upgrading. The hosted beta can reject SDK versions that are no longer protocol-compatible.