Agent builder
ProA card for setting up an AI agent: name and avatar, a model picker, instructions, tool toggles with real app marks, and knowledge files with upload progress. A Configure / Test switch opens a compact chat that answers with the tools you turned on, and Publish ships the setup with a saved or unsaved state.
- Letting customers configure their own AI agent inside your product, like Intercom Fin, Zapier agents or an OpenAI GPT builder.
- Internal admin screens where ops teams tune instructions, tools and knowledge for a support or billing agent.
- A product tour or landing section that shows how an agent is set up and tested in one place.
- Running or monitoring an agent in production: use agent-status or agent-routines.
- Approving actions an agent wants to take: use agent-approvals.
- A full chat product: use ai-chat. The Test view here is a compact preview, not a conversation app.
- Only choosing a model: use model-picker.
Installation
Pro source and install commands unlock with a Pro plan.
Usage
Drop it into the settings screen of a support, sales or ops agent. Pass defaultConfig (or a controlled config with onConfigChange) and publishedConfig from your server, so unsaved changes are measured against what is live. Wire onPublish(config, signal) to save the setup, onUpload(file, report, signal) to upload knowledge files with progress, and onSend(message, config, signal) to answer test messages with the unsaved setup. onSend returns { text, calls }, and each call's tool id must match an AgentTool id (or "knowledge") so its chip gets the right mark. models and tools take your own lists with 16px SVG marks. Leave any callback out and that part is simulated.
import { AgentBuilder, sampleAgentConfig } from "@/components/arc/blocks/agent-builder/agent-builder"; export function SupportAgentSettings() { return ( <AgentBuilder defaultConfig={sampleAgentConfig} onPublish={async (config, signal) => { const response = await fetch("/api/agents/billing", { method: "PUT", body: JSON.stringify(config), signal }); if (!response.ok) throw new Error("Server rejected the config"); }} onSend={async (message, config, signal) => { const response = await fetch("/api/agents/billing/test", { method: "POST", body: JSON.stringify({ message, config }), signal }); return response.json(); // { text, calls: [{ tool: "stripe", label: "Searched customers", result: "2 charges" }] } }} /> );}API reference
2 parts. The first is the root.
AgentBuilder
Configure an AI agent in one card: name and avatar, a model picker, instructions with a character count, tools as toggle rows, and knowledge files with upload progress. A Configure / Test switch swaps the body for a compact chat that answers with the configured model and tools, and Publish ships the config with an unsaved, publishing, failed and published state. With no props it plays the Lumen billing assistant sample with simulated uploads, replies and publishing.
configAgentConfig–Controlled config: { name, tint, modelId, instructions, tools, files }. Pair with onConfigChange.defaultConfigAgentConfigsampleAgentConfigStarting config when uncontrolled. Passing it turns off the sample's auto upload.onConfigChange(config: AgentConfig) => void–Called with the next config on every edit, toggle, model change and file update.publishedConfigAgentConfig–The config that is live now. Unsaved changes are measured against it, so reverting an edit clears the unsaved state. Defaults to the starting config.modelsAgentModel[]defaultModelsModels in the picker: { id, name, note?, mark? }. Defaults to Claude Sonnet 5.5, Claude Opus 5.5, Claude Haiku 5.5, GPT-6.1 Sol and Gemini 4 Argon with their marks.toolsAgentTool[]defaultToolsTools the agent can be given: { id, name, description, mark? }. Defaults to Gmail, Slack, Linear, Notion, Google Calendar and Stripe.onPublish(config: AgentConfig, signal: AbortSignal) => Promise<void>–Saves and ships the config. Resolve to bump the version and show the published state; reject to show "Couldn't publish". Simulated when left out.onUpload(file: File, report: (progress: number) => void, signal: AbortSignal) => Promise<void>–Uploads one knowledge file. Call report with 0 to 1 as bytes go out; reject with an Error to mark the row failed with its message and a retry button. The signal aborts when the row is removed. Simulated when left out (files over 20 MB fail).onSend(message: string, config: AgentConfig, signal: AbortSignal) => Promise<TestReply>–Answers a Test message. Return { text, calls?: { tool, label, result? }[] }; calls render as tool chips with the tool's mark before the reply streams. Defaults to simulateReply, which follows the enabled tools.versionnumber12Published version shown under the name. Counts up after each successful publish.workspacestring"Lumen support"Short line under the name, such as the workspace or team.maxInstructionsnumber2000Instruction length limit. The count turns to the warning color past 90%.acceptstring".pdf,.md,.txt,.csv,.docx,.html"Accepted file types for the knowledge file picker.mode"configure" | "test"–Controlled view. Pair with onModeChange.defaultMode"configure" | "test""configure"Starting view when uncontrolled.onModeChange(mode: AgentBuilderMode) => void–Called when the Configure / Test switch changes.classNamestring–Extra class on the card.simulateReply
The built in reply function used when onSend is left out. Matches billing, bug and booking requests and changes its answer and tool calls to the tools that are on, so it is useful for demos and tests.
messageRequiredstring–The test message.configRequiredAgentConfig–The current config. Disabled tools are never called.- Tab
- Moves through the avatar, name, view switch, model picker, instructions, each tool switch, file actions and Publish. The hidden view is inert and skipped.
- Arrow keys
- Move between Configure and Test on the view switch, and between models in the open picker.
- EnterorSpace
- Opens the model picker, chooses a model, toggles a tool, and presses buttons.
- Escape
- Closes the model picker and returns focus to it.
- Enter (in Test)
- Sends the message. While a reply runs, the send button becomes Stop.
- The card is a labelled section; the name field, instructions and every tool switch have labels, and the tool row text is part of the switch label so the whole row is clickable.
- The model picker is a Radix menu with radio items, so the selected model is announced as checked.
- Upload progress uses role="progressbar" with a value; failed uploads show an icon and the error message, never color alone.
- Status changes (published, upload done or failed, reply ready) go to a polite live region, and simulated actions say so: "Simulated, nothing was deployed".
- The inactive view is inert and aria-hidden, so screen readers and the Tab key only reach what is visible.
- Configure and Test crossfade in the same box (100ms out, 160ms in); Test overlays Configure, so the card never changes size.
- Text swaps (model name, version, footer status, reply meta) are a single crossfade with a 2px rise. No blur or scramble.
- Test replies: a short Thinking shimmer, tool chips that shimmer while running and reveal their result in place, then fast chunked streaming of three to six words every 34ms, each chunk only fading in.
- Added and removed files animate their measured height with a bounce free spring; switches and the segmented control use the shared bounce free presets.
- Reduced motion drops the rises, height animation and streaming (replies appear whole) but keeps every state and status change.
- Fills its container up to 600px. Below 480px the padding drops to 16px and the model picker narrows; tool descriptions and file names truncate with an ellipsis.
- Holds up at 360px without horizontal scroll; the Test view scrolls its own thread and keeps the composer pinned.
- Tool rows and buttons are at least 28px tall targets inside 52px rows for touch.
- Plain DOM and CSS; motion only animates opacity, small transforms and the height of added or removed file rows.
- The sample upload starts only once the card is on screen. Text shimmers pause off screen.
- Streaming appends one chunk every 34ms; each chunk is its own span so earlier text never re-renders its animation.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Use it for the settings screen of a support, sales or ops agent: one card that holds the whole config with a built in test loop.
- Wire onPublish to persist the config and onSend to call your agent runtime with the unsaved config, so people can test before they publish.
- Pass publishedConfig from the server so the unsaved state compares against what is live; files still uploading or failed do not count as changes.
- Tool ids in TestReply.calls must match AgentTool ids (or "knowledge" for a file lookup) so the chips get the right mark.
- Keep marks 16px square SVGs; mono marks should use currentColor so they follow the theme.
The full library index for assistants is at /llms.txt.