# Agentable UI

> React components that people and agents can use together, plus a parser and renderer for model-generated interfaces. Packages are independently versioned under @agentable-ui/*. MIT licensed.

The docs site renders in JavaScript. This guide and /llms-full.txt provide text access. The full reference combines this guide with all six package READMEs; it does not reproduce every rendered docs page.

## Start here

Install in an existing React 18.2+ app:

```bash
npm install @agentable-ui/ui @agentable-ui/react @agentable-ui/core
npm install -D @agentable-ui/devtools
```

```tsx
import { AgentableProvider } from "@agentable-ui/react";
import { DataTable } from "@agentable-ui/ui";
import { AgentableDevtools } from "@agentable-ui/devtools/react";
import "@agentable-ui/ui/styles.css";

const rows = [
  { id: "ORD-1001", customer: "Ada Lovelace", total: 129 },
  { id: "ORD-1002", customer: "Grace Hopper", total: 249 },
];
const columns = [
  { key: "id", header: "Order" },
  { key: "customer", header: "Customer" },
  { key: "total", header: "Total" },
];

export default function App() {
  return (
    <AgentableProvider budget={12}>
      <DataTable rows={rows} columns={columns}
        agent={{ name: "query_orders", cache: false }} />
      <AgentableDevtools />
    </AgentableProvider>
  );
}
```

Open Agent (Alt+A), choose Console, and call query_orders with {"query":"Ada"}. No model, API key, or browser flag is required for local devtools invocation. A browser agent needs compatible WebMCP support. In frameworks with server components, use a client component.

## Choose a package

- [@agentable-ui/ui](https://www.npmjs.com/package/@agentable-ui/ui): callable controls (Form/Field, DataTable, Combobox, ActionBar, Dialog, Tabs, Nav, Filters, Pagination, Toaster), optional CSS, and uiCatalog.
- [@agentable-ui/react](https://www.npmjs.com/package/@agentable-ui/react): AgentableProvider, useTool, useCapability, ToolScope, and snapshot hooks.
- [@agentable-ui/core](https://www.npmjs.com/package/@agentable-ui/core): framework-free registry, budgets, tiers, caching, validation, output shaping, confirmation, and adapters.
- [@agentable-ui/devtools](https://www.npmjs.com/package/@agentable-ui/devtools): in-page inspector and tool console. React entry: @agentable-ui/devtools/react.
- [@agentable-ui/lang](https://www.npmjs.com/package/@agentable-ui/lang): parser, streaming parser, serializer, and prompt generation for Agentable Lang. No model calls or network access.
- [@agentable-ui/genui](https://www.npmjs.com/package/@agentable-ui/genui): Renderer for streamed programs and AgentSurface for an agent-callable present tool.

## Availability

A supported control declares tools only when an agent prop is supplied and it is mounted. Presentational primitives such as Button and Card do not accept an agent prop; use ActionBar, useTool, or generated event actions.

The default budget is 12 resident tools, including discovery tools. Tier 0 is preferred for residency, subject to the budget. Tier 1 is listed by list_capabilities and loaded through open_capability. Tier 2 is dormant and requires application code to promote it. Groups load together; priority decides what stays when space is limited. ActionBar combines actions into one tool by default.

ToolScope can demote offscreen groups after five seconds. Offscreen components remain mounted; inactive tab panels and closed dialog contents unmount and release their tools.

## Confirmation and caching

Custom tools are consequential by default unless annotations or explicit confirmation options say otherwise. React supplies a built-in confirmation dialog. Core without a handler declines consequential calls. A decline returns structured error text with declined: true.

UI defaults are explicit: forms ask before agent submission; ActionBar asks for destructive actions; selection, navigation, tabs, filters, and pagination do not ask. Human callbacks follow ordinary application event handling.

Pure read-only tools cache by default for 30 seconds. A cache hit skips execute. Use cache: false for callbacks that must re-read changing state or reapply UI changes. Tagged entries can be cleared with invalidates after a successful agent mutation. Human interactions do not automatically invalidate registry caches.

## Authoring rules

- Put React tools and callable controls under AgentableProvider. Use stable names and ids.
- Keep tool names within the 30-character guidance and descriptions concise.
- Provide inputSchema and mark pure reads with annotations.readOnlyHint: true.
- Use project and agentHidden to limit output, while enforcing access control in your application.
- Use group and tier: 1 for less frequent capabilities.
- Treat confirm: false as an explicit opt-out from prompting.
- Prefer stable record ids or getRowId for selectable tables.
- Import styles.css once, then override --ag-* tokens or data-agentable-* hooks.
- The source checkout's Button API adds native props, children, sizes, ghost, and loading; confirm your installed version includes these unreleased additions.

## Generative UI

Agentable Lang uses one node per line: root = Card("Hello"). createLibrary(catalog).prompt() generates a model prompt. The application owns the model request and stream; Renderer receives the full accumulated response and isStreaming. It parses complete lines, prunes invalid nodes, and enables interactions after streaming ends.

AgentSurface registers present over an allowed catalog. present accepts either { program } or { root }. Its tool actions use the registry; Renderer can also receive a direct tools callback map. Direct callbacks follow application policies. Data is read-only; generated actions write only ui state.

## Verification and limits

WebMCP is experimental. The repository's conformance report records the tested browser version and findings, rather than claiming universal browser support. The current Chrome 155 run accepts object executeTool inputs and returns strings. The library validates inputs and shapes outputs instead of relying on browser enforcement.

The budget bounds advertised tool count. Token estimates vary by schema; no model-accuracy benchmark is claimed. Package versions differ; use each package's manifest and changelog. The original implementation plan is historical context.

## Documentation

- [Full package reference](/llms-full.txt)
- [Quick start](https://agentable.interfacesforhuman.com/#/docs/quickstart)
- [Styling](https://agentable.interfacesforhuman.com/#/docs/styling)
- [Demo](https://agentable.interfacesforhuman.com/#/demo)