Start here
Install only what you need.
agent-ui is delivered as source. Start with a stylesheet, add the optional runtime when you need enhancement, or copy a component and make it yours.
0. Start with the complete flow
Skip the catalog when you need a credible screen now. The starter composes five states, uses native controls, and includes the narrow-screen rules that keep long tool output readable.
Copy the starter first. Replace the local stylesheet paths when you move it into your app, then let the host own execution and persistence.
1. Give an agent a reliable starting point
AI agents can read the generated component catalog before choosing a primitive. The AI setup guide includes a copyable prompt, selection rules, and the trust boundary.
Use the starter for a complete flow; use the catalog when you need one component and its exact dependencies.
2. Link the source
Copy the token file and the stylesheets for the components you use. The page renders without JavaScript.
<link rel="stylesheet" href="tokens.css">
<link rel="stylesheet" href="components/button/button.css">3. Enhance when you need behavior
The optional runtime currently enhances dialog with modal behavior, Escape handling, focus restoration, and shared events. It does not parse, fetch, or execute content.
<script src="agent-ui.js"
defer></script>4. Copy the source
Every component page exposes raw files. The first component is a native button with no JavaScript dependency; the dialog page shows the optional runtime path.
Open the component page, copy the canonical HTML, and paste it into a blank body with tokens.css and button.css.
5. Choose a distribution path
Copy source for ownership, open the hosted static docs for discovery, or use a pinned CDN tag for a quick prototype. The CDN is optional and never required by the components.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/itsbrennanm/agent-ui@v0.5.0/tokens.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/itsbrennanm/agent-ui@v0.5.0/components/tool-call/tool-call.css">Read the distribution guide. Keep CDN URLs pinned to a release tag, never main or latest.
Patterns
Recipes compose the primitives into full agentic moments without hiding their HTML. The starter is the shortest path; the full flow adds the surrounding docs shell and state inspector.
Theming
Use the semantic tokens in tokens.css. The MVP ships the default shape with light and dark modes. For responsive composition, start with the mobile checklist before adding density or decoration. The v0.5 release plan records the remaining proof gates.