HeroUI Agents SDK

Embed a hosted generative-UI agent in your React app with @heroui/agent. Declare typed client tools that read your data — the hosted runtime plans the answer, runs calculations in a sandbox, and streams back charts, tables, and metrics.

Installation

npm install @heroui/agent@beta

Import the stylesheet once:

@import "@heroui/agent/css";

Usage

import {HeroUIAgent} from "@heroui/agent/next";

export function AppAgent() {
  return (
    <HeroUIAgent
      agentId={process.env.NEXT_PUBLIC_HEROUI_AGENT_ID!}
      getAuthToken={async (context) => {
        const response = await fetch("/api/heroui-agent/auth-token", {
          method: "POST",
          headers: {"Content-Type": "application/json"},
          body: JSON.stringify(context),
        });

        if (!response.ok) throw new Error("Agent authentication failed");

        return response.json();
      }}
    />
  );
}

Mint the short-lived browser credential on your server — never expose the project API key to the client:

import {createAuthToken} from "@heroui/agent/server";

export async function POST(request: Request) {
  const {anonymousId, agentId} = await request.json();

  return Response.json(
    await createAuthToken({
      apiKey: process.env.HEROUI_AGENT_API_KEY!,
      identity: {id: anonymousId, type: "anonymous"},
      agentId,
    }),
  );
}

Overview

@heroui/agent provides a unified SDK for embedding HeroUI Agents into web applications.

Entrypoints

| Entrypoint | Description | Links | | -------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | @heroui/agent | React embed, hooks, and client tools | npm • Docs | | @heroui/agent/next | Next.js App Router entry | Docs | | @heroui/agent/server | Server helpers for minting auth tokens | Docs | | @heroui/agent/css | Agent stylesheet | — | | @heroui/agent/contracts | Shared protocol types and schemas | — |

Package Details

@heroui/agent

The core React SDK for embedding a hosted agent.

Features

• Generative UI — Charts, tables, metrics, and forms streamed from a validated component union
• Client tools — Typed browser functions that run with the signed-in user's session
• Dashboard-driven appearance — Theme, launcher, greeting, subtitle, and composer without a redeploy
• Anonymous → identified — Merge guest history when the user signs in
• Edge-safe contracts — Protocol types with no Node built-ins

Installation

npm install @heroui/agent@beta

@heroui/agent/next

Next.js App Router entry that mirrors the root export.

import {HeroUIAgent} from "@heroui/agent/next";

@heroui/agent/server

Server-only helpers for exchanging a project API key for a short-lived browser credential.

import {createAuthToken} from "@heroui/agent/server";

Styles

@import "@heroui/agent/css";

Optional Pro theme variants (brutalism, glass, mouve) ship from @heroui-pro/react:

import "@heroui/agent/css";
import "@heroui-pro/react/agent-themes/glass";

Contracts

Shared protocol version, message types, and schemas used by the SDK and hosted API.

import {HEROUI_AGENT_PROTOCOL_VERSION} from "@heroui/agent/contracts";

Client Tools

Client tools let the agent call into your application — fetch data, change filters, create records:

import {HeroUIAgent, createToolHelper} from "@heroui/agent";
import {z} from "zod";

const tool = createToolHelper<{apiClient: ApiClient}>();

const tools = [
  tool({
    name: "search_users",
    description: "Search for users by name or email",
    parameters: z.object({query: z.string()}),
    execute: ({query}, context) => context.apiClient.searchUsers(query),
  }),
];

<HeroUIAgent
  agentId={process.env.NEXT_PUBLIC_HEROUI_AGENT_ID!}
  getAuthToken={getAuthToken}
  context={{apiClient}}
  tools={tools}
/>;

Only tool names, descriptions, and JSON schemas reach the hosted agent. Implementations and context never leave the browser.

Learn more

Documentation

• Installation
• Identifying users
• Configuration
• Client tools
• Appearance
• Configure

Projects and API keys are managed in the Agents dashboard.

What runs where

The HeroUI API authenticates the visitor once, verifies conversation ownership, and returns a one-use connection ticket. The browser then keeps a resumable WebSocket directly to the conversation's Cloudflare Durable Object. That object owns the transcript, streams from the model provider, and starts MCP or an offline, per-call-scoped sandbox only when a tool actually needs one. Before the composer clears, the SDK durably stores the submitted turn and attachment blobs in an identity-and-conversation-scoped IndexedDB outbox. It removes that entry only after the Durable Object acknowledges committed admission, and reconciles the same turnId after a reload. InstantDB is updated asynchronously for dashboard monitoring and never sits in front of a response stream.

| In the browser | At the HeroUI edge runtime | | ------------------------------------------- | -------------------------------------------- | | Panel, theme, composer, generated UI | Conversation Durable Object and model stream | | Client tools, running as the signed-in user | Server tools, lazy MCP and offline Python | | Pre-admission IndexedDB turn outbox | SDK transcript and resumable stream storage | | A short-lived HeroUI browser credential | Hashed tickets, credit lease, Queue outbox |

Compatibility

• React 19+
• Next.js 15+ for @heroui/agent/next
• Chrome/Edge 120+, Firefox 121+, Safari 17.2+
• ESM only

This SDK speaks protocol version 6. The hosted API returns 426 Upgrade Required when a beta SDK is no longer compatible.

Support

• Documentation
• Agents product
• Issues
• Discord

License

MIT — see LICENSE.

Built by HeroUI