Installation

Agents Kit follows the shadcn copy-source model. The CLI adds component files, local dependencies, styles, and license notices to your application. There is no bundled Agents Kit runtime to install from npm.

Prepare your application

Use React 19 and Tailwind CSS 4. Set up shadcn/ui for your framework first so your project has a components.json file and working import aliases. Running this repository locally uses Node.js 20 or later.

Next.js is used by this documentation site. It is not required by every component. Inspect an entry's dependencies before installing it; some retained v0.1 components use Next.js.

Add a component

npx shadcn@latest add https://agents-ui.github.io/agents-kit/c/agent-generative-surface.json

The registry index lists every available entry. The same URL format works for current and compatibility components:

npx shadcn@latest add https://agents-ui.github.io/agents-kit/c/beautiful-original-thinking-state.json
npx shadcn@latest add https://agents-ui.github.io/agents-kit/c/beui-prompt-input.json
npx shadcn@latest add https://agents-ui.github.io/agents-kit/c/agent-card.json

Load the styles

Every registry entry includes the shared Agents Kit typography and semantic theme. Import its copied styles once from your application's global stylesheet. The paths below assume that stylesheet is at the project root and the components alias resolves to a root-level directory. Adjust relative paths to the files the CLI installed. For example, a stylesheet in app/ with root-level components uses ../components/ and ../styles/.

@import "./components/boardui/styles/globals.css";
@import "./styles/agents.css";

BoardUI's shared stylesheet includes Tailwind CSS, the base theme, and typography tokens. Import it when the registry entry includes BoardUI controls; otherwise retain your existing Tailwind and shadcn setup. Import styles/agents.css after the base styles. Avoid importing Tailwind twice. The registry installs CSS files; it does not automatically add these imports to your stylesheet.

If you keep copied components outside Tailwind's scanned source directories, add an appropriate @source directive to your stylesheet.

Original Beautiful UI entries use the beautiful-original- prefix. Import their copied components/beautiful-ui/original/beautiful-ui.css through the same global CSS file that imports Tailwind, then wrap them in an ancestor with className="beautiful-ui-scope". Load this stylesheet before styles/agents.css. Do not load it from a JavaScript component: its @theme definitions must participate in Tailwind compilation. The host's .dark class selects the dark palette. The earlier beautiful- adapters remain available at their existing paths.

Load Inter and JetBrains Mono with your framework or font provider, and expose them as --font-inter and --font-jetbrains-mono on the application root. The shared UI baseline is 14px with a 1.5 line height, tight tracking, and Inter's cv11 / ss01 features. Mobile form controls use 16px. Card corners, borders, and muted text follow the same semantic tokens across collections. The design contract records the complete typography, spacing, shape, and accessibility rules.

Collections that ship styles/animations.css need that import for their entrance, exit, and disclosure animations. Prompt Kit also ships its loader keyframes; import the copied stylesheet once:

@import "./components/prompt-kit/styles.css";

AI Elements message and reasoning entries include Streamdown's code, math, diagram, and CJK plugins. Import their copied Markdown stylesheet and the shared animations:

@import "./styles/animations.css";
@import "./components/ai-elements/markdown.css";

markdown.css includes KaTeX fonts through its package stylesheet. Its @source paths assume components/ai-elements and node_modules are at the project root; adjust those paths if you install elsewhere. Workflow canvas entries import their XYFlow stylesheet directly.

The source coverage report lists the imported catalogs, preserved variants, and remote demo-media exceptions.

Use a component

import { AgentGenerativeSurface } from "@/components/agents-ui/agent-generative-surface"

export function WeatherAnswer() {
  return (
    <AgentGenerativeSurface
      content={{
        type: "weather",
        location: "Madrid",
        temperature: 24,
        unit: "C",
        condition: "Light rain",
        forecast: [
          { day: "Today", temperature: 24 },
          { day: "Tomorrow", temperature: 25 },
        ],
      }}
    />
  )
}

The @/components prefix above follows this repository's alias. Use the aliases configured in your own components.json. Components with interactive callbacks belong in a client component when using React Server Components.

AgentGenerativeSurface supports status="ready", status="loading", and status="error". Pass onAction, onSeek, and onRetry to handle user input. Your application supplies the data and performs the work; the component does not fetch weather or call a model.

Optional registry namespace

Merge this entry into the registries object in your existing components.json. Keep your existing style, aliases, Tailwind settings, and other registries.

{
  "registries": {
    "@agents-kit": "https://agents-ui.github.io/agents-kit/c/{name}.json"
  }
}

You can then use shorter install commands:

npx shadcn@latest add @agents-kit/agent-generative-surface

This namespace also lets the shadcn MCP server discover the collection.

v0.1 compatibility

Existing public import paths and registry names remain available. Use the archive for the original gallery and the migration guide for gradual adoption.

IntroductionModel Context Protocol