{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-8", "title": "Agent 8: knowledge manager", "author": "Ballmac ", "description": "A knowledge manager for an AI agent: a health bar across its sources, each source with sync progress or failure and a retry, a switch for whether the agent may use it, and a panel showing which passages come back for a question.", "dependencies": [ "lucide-react" ], "registryDependencies": [ "utils", "https://ui.ballmac.com/r/alert-dialog.json", "https://ui.ballmac.com/r/badge.json", "https://ui.ballmac.com/r/blur-fade.json", "https://ui.ballmac.com/r/button.json", "https://ui.ballmac.com/r/dropdown-menu.json", "https://ui.ballmac.com/r/match-highlight.json", "https://ui.ballmac.com/r/skeleton.json", "https://ui.ballmac.com/r/state-view.json", "https://ui.ballmac.com/r/switch.json", "https://ui.ballmac.com/r/return-focus.json" ], "files": [ { "path": "registry/ballmac/components/blocks/agent-8/agent-8.tsx", "content": "// Ballmac UI: Agent 8. https://ui.ballmac.com/blocks/agent-8\n\"use client\"\n\nimport * as React from \"react\"\nimport { BookOpen, ChevronDown, CircleAlert, FileText, Globe, Loader2, Plus, RefreshCw, Search, SearchX, Trash2, Type } from \"lucide-react\"\n\nimport { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle } from \"@/components/ballmac/alert-dialog\"\nimport { Badge } from \"@/components/ballmac/badge\"\nimport { BlurFadeGroup } from \"@/components/ballmac/blur-fade\"\nimport { Button } from \"@/components/ballmac/button\"\nimport { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from \"@/components/ballmac/dropdown-menu\"\nimport { countMatches, MatchHighlight, queryTokens } from \"@/components/ballmac/match-highlight\"\nimport { Skeleton } from \"@/components/ballmac/skeleton\"\nimport { useReturnFocus } from \"@/lib/ballmac/return-focus\"\nimport { frameProps, StateView, type StateProps } from \"@/components/ballmac/state-view\"\nimport { Switch } from \"@/components/ballmac/switch\"\nimport { cn } from \"@/lib/utils\"\n\ntype Agent8Kind = \"website\" | \"file\" | \"text\"\n\ntype Agent8Source = {\n id: string\n name: string\n kind: Agent8Kind\n /** A web address, a file name or a short note about where it came from. */\n location: string\n status: \"ready\" | \"syncing\" | \"failed\"\n /** From 0 to 1 while syncing. */\n progress?: number\n /** How many passages the agent can find in it. */\n passages?: number\n /** Already written for people (\"Synced 2 hours ago\"). */\n synced?: string\n /** Why it failed. */\n error?: string\n /** Whether the agent may use it. */\n enabled?: boolean\n /** A few representative passages. The built-in test searches these. */\n excerpts?: string[]\n}\n\ntype Agent8Passage = { sourceId: string; text: string; /** 0 to 1 */ score?: number }\n\ntype Agent8Props = Omit, \"title\"> &\n StateProps & {\n sources?: Agent8Source[]\n title?: string\n /** Questions offered as shortcuts in the test panel. */\n exampleQuestions?: string[]\n /** Called by Add source with the kind chosen. */\n onAdd?: (kind: Agent8Kind) => void\n /** Called by Sync now on a source, or Retry on a failed one. */\n onResync?: (id: string) => void\n /** Called after Remove is confirmed. */\n onRemove?: (id: string) => void\n /** Called when a source is turned on or off for the agent. */\n onToggle?: (id: string, enabled: boolean) => void\n /**\n * Finds what the agent would find for a question. Return the passages with their source, and optionally an answer. Without it the\n * block searches the sources' excerpts, so you can see the idea working.\n */\n onAsk?: (question: string, sources: Agent8Source[]) => Promise<{ passages: Agent8Passage[]; answer?: string }>\n /** The question shown in the test panel at first, and run straight away. */\n defaultQuestion?: string\n }\n\nconst sample: Agent8Source[] = [\n {\n id: \"help\",\n name: \"Help center\",\n kind: \"website\",\n location: \"help.acme.com\",\n status: \"ready\",\n passages: 612,\n synced: \"Synced 2 hours ago\",\n enabled: true,\n excerpts: [\n \"To download an invoice, open Billing, choose Invoices and select the PDF icon next to the month you need. Invoices include your company name and tax number.\",\n \"A refund for a duplicate charge usually reaches the customer's card within 5 to 10 business days, depending on their bank.\",\n \"To reset your password, choose Forgot password on the sign-in page. The link we email you works for one hour.\",\n ],\n },\n {\n id: \"policy\",\n name: \"Refund policy.pdf\",\n kind: \"file\",\n location: \"Uploaded last week · 14 pages\",\n status: \"ready\",\n passages: 48,\n synced: \"Added last week\",\n enabled: true,\n excerpts: [\n \"Refunds under $200 for duplicate charges may be issued by support without approval. Larger refunds need a manager's approval and a written reason.\",\n \"Annual plans can be refunded in full within 30 days of purchase. After that, unused months are credited to the account instead.\",\n ],\n },\n { id: \"macros\", name: \"Support macros\", kind: \"file\", location: \"macros.csv · 220 rows\", status: \"syncing\", progress: 0.58, synced: \"Reading rows…\", enabled: true },\n { id: \"wiki\", name: \"Internal wiki\", kind: \"website\", location: \"wiki.acme.com\", status: \"failed\", error: \"Could not sign in. The saved password has expired.\", enabled: false },\n { id: \"tone\", name: \"Tone of voice\", kind: \"text\", location: \"Pasted note\", status: \"ready\", passages: 6, synced: \"Added 3 weeks ago\", enabled: true, excerpts: [\"Write the way a thoughtful colleague would speak: warm, brief and specific. Never use exclamation marks in refunds or incident messages.\"] },\n]\n\nconst kindIcon = { website: Globe, file: FileText, text: Type } as const\nconst kindTone = { website: \"bg-chart-1/20\", file: \"bg-chart-4/20\", text: \"bg-chart-3/25\" } as const\nconst addOptions: { kind: Agent8Kind; label: string; hint: string }[] = [\n { kind: \"website\", label: \"A website\", hint: \"Read pages from an address\" },\n { kind: \"file\", label: \"Files\", hint: \"PDFs, documents and spreadsheets\" },\n { kind: \"text\", label: \"Pasted text\", hint: \"Notes, policies, a few paragraphs\" },\n]\n\nfunction KnowledgeSkeleton() {\n return (\n
\n
\n \n {[0, 1, 2].map((i) => (\n \n ))}\n
\n \n
\n )\n}\n\n/**\n * A knowledge manager for an AI agent: how healthy its sources are at a glance, each source with its sync state, progress or failure\n * (and a way to retry), a switch for whether the agent may use it, and a panel that shows which passages the sources return for a question.\n */\nfunction Agent8({\n sources: sourcesProp = sample,\n title = \"Knowledge\",\n exampleQuestions = [\"How long does a refund take?\", \"Can support refund $150 without approval?\", \"How do I download an invoice?\"],\n onAdd,\n onResync,\n onRemove,\n onToggle,\n onAsk,\n defaultQuestion,\n state = \"ready\",\n onRetry,\n emptyState,\n errorState,\n className,\n ...props\n}: Agent8Props) {\n const id = React.useId()\n const [sources, setSources] = React.useState(sourcesProp)\n React.useEffect(() => setSources(sourcesProp), [sourcesProp])\n const [confirm, setConfirm] = React.useState(null)\n const returnFocus = useReturnFocus(!!confirm)\n const [question, setQuestion] = React.useState(defaultQuestion ?? \"\")\n const [asking, setAsking] = React.useState(false)\n const [asked, setAsked] = React.useState(null)\n const [found, setFound] = React.useState<{ passages: Agent8Passage[]; answer?: string } | null>(null)\n const [askError, setAskError] = React.useState()\n const [announce, setAnnounce] = React.useState(\"\")\n const ready = state === \"ready\" || state === \"empty\"\n const list = state === \"empty\" ? [] : sources\n\n const counts = { ready: list.filter((s) => s.status === \"ready\").length, syncing: list.filter((s) => s.status === \"syncing\").length, failed: list.filter((s) => s.status === \"failed\").length }\n const passages = list.reduce((sum, s) => sum + (s.passages ?? 0), 0)\n const usable = list.filter((s) => s.enabled && s.status === \"ready\")\n\n async function ask(q: string) {\n const text = q.trim()\n if (!text) return\n setAsking(true)\n setAskError(undefined)\n setAsked(text)\n try {\n if (onAsk) setFound(await onAsk(text, usable))\n else {\n await new Promise((r) => setTimeout(r, 450))\n const tokens = queryTokens(text).filter((t) => t.length > 2)\n const hits = usable\n .flatMap((s) => (s.excerpts ?? []).map((p) => ({ sourceId: s.id, text: p, raw: countMatches(p, tokens) })))\n .filter((h) => h.raw > 0)\n .sort((a, b) => b.raw - a.raw)\n .slice(0, 4)\n const max = Math.max(1, ...hits.map((h) => h.raw))\n setFound({ passages: hits.map((h) => ({ sourceId: h.sourceId, text: h.text, score: h.raw / max })) })\n }\n } catch (err) {\n setFound(null)\n setAskError(err instanceof Error && err.message ? err.message : \"The test could not run. Try again.\")\n } finally {\n setAsking(false)\n }\n }\n\n // run the starting question once, so the panel opens showing what it does\n const started = React.useRef(false)\n React.useEffect(() => {\n if (defaultQuestion && !started.current && ready) {\n started.current = true\n ask(defaultQuestion)\n }\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, [])\n\n const sourceOf = (sid: string) => sources.find((s) => s.id === sid)\n\n const addMenu = (\n \n \n \n Add source\n \n \n \n {addOptions.map((o) => {\n const Icon = kindIcon[o.kind]\n return (\n onAdd?.(o.kind)} className=\"items-start gap-3 py-2\">\n \n \n {o.label}\n {o.hint}\n \n \n )\n })}\n \n \n )\n\n const content = !list.length ? (\n
\n \n \n \n

{emptyState?.title ?? \"Teach your agent what you know\"}

\n

{emptyState?.description ?? \"Add the pages, files and notes it should read before it answers. It will only use what you give it.\"}

\n
\n {addOptions.map((o) => {\n const Icon = kindIcon[o.kind]\n return (\n \n )\n })}\n
\n {emptyState?.action}\n
\n ) : (\n
\n
\n
\n
\n {counts.ready ? : null}\n {counts.syncing ? : null}\n {counts.failed ? : null}\n
\n
\n
\n
\n
Sources
\n
{list.length}
\n
\n
\n
Passages
\n
{new Intl.NumberFormat(\"en-US\").format(passages)}
\n
\n
\n
    \n
  • {counts.ready} ready
    • \n
  • {counts.syncing} syncing
    • \n
  • {counts.failed} failed
    • \n
\n
\n
\n\n \n {list.map((s) => {\n const Icon = kindIcon[s.kind]\n return (\n
\n
\n \n \n \n
\n
\n

\n {s.name}\n

\n {s.status === \"ready\" ? Ready : s.status === \"syncing\" ? Syncing : Failed}\n
\n

\n {s.location}\n

\n {s.status === \"syncing\" ? (\n
\n
\n
\n
\n

\n \n {Math.round((s.progress ?? 0) * 100)}% · {s.synced ?? \"Syncing\"}\n

\n
\n ) : s.status === \"failed\" ? (\n

\n \n {s.error ?? \"Could not read this source.\"}\n

\n ) : (\n

\n {s.passages !== undefined ? `${new Intl.NumberFormat(\"en-US\").format(s.passages)} passages` : \"Ready\"}\n {s.synced ? ` · ${s.synced}` : \"\"}\n

\n )}\n
\n
\n {s.status === \"failed\" ? (\n \n ) : s.status === \"ready\" && s.kind === \"website\" ? (\n \n ) : null}\n \n {\n setSources((l) => l.map((x) => (x.id === s.id ? { ...x, enabled: on } : x)))\n onToggle?.(s.id, on)\n setAnnounce(`${s.name} ${on ? \"turned on\" : \"turned off\"} for the agent`)\n }}\n aria-labelledby={`${id}-${s.id}`}\n aria-describedby={`${id}-use`}\n />\n
\n
\n
\n )\n })}\n \n

\n The switch decides whether the agent may use a source in its answers. Failed sources are off until they work again.\n

\n
\n\n \n
\n )\n\n return (\n
\n
\n
\n

\n {title}\n

\n

What your agent reads before it answers. It uses only what is turned on here, and it can tell you which source it used.

\n
\n {ready && list.length ? addMenu : null}\n
\n } error={{ title: errorState?.title ?? \"Your sources could not be loaded\", description: errorState?.description ?? \"Nothing was changed. Check your connection and try again.\", ...errorState }}>\n {content}\n \n\n !o && setConfirm(null)}>\n \n \n Remove {confirm?.name}?\n The agent stops using it straight away. You can add it again later, but it will be read from scratch.\n \n \n Cancel\n {\n if (!confirm) return\n setSources((l) => l.filter((x) => x.id !== confirm.id))\n onRemove?.(confirm.id)\n setAnnounce(`${confirm.name} removed`)\n }}\n >\n Remove\n \n \n \n \n

\n {announce}\n

\n
\n )\n}\n\nexport { Agent8, type Agent8Props, type Agent8Source, type Agent8Passage, type Agent8Kind }\n", "type": "registry:component", "target": "@components/ballmac/blocks/agent-8/agent-8.tsx" } ], "meta": { "schema": 1, "tier": "free", "tags": [ "ai", "agent", "knowledge", "rag", "sources", "retrieval", "documents", "sync", "training data", "knowledge base" ], "version": "1.0.0", "updated": "2026-10-17", "tests": true, "ai": { "summary": "An agent knowledge page. …} onResync onRemove onToggle onAsk={async (question, sources) => ({ passages: [{ sourceId, text, score }], answer })} defaultQuestion />. The test panel shows retrieval, not a generated answer; onAsk returns your vector search's top passages. Without onAsk it searches each source's excerpts.", "whenToUse": [ "Managing what a support, docs or internal agent may read (RAG sources)", "Checking that a question is covered before shipping an agent" ], "whenNotToUse": [ "Showing the sources an answer used (use sources-list and citation)", "Configuring tools and instructions (use agent-7)" ], "composesWith": [ "agent-7", "agent-6", "agent-3", "app-shell-1" ], "a11y": [ { "keys": "Tab", "action": "Each source has a switch named for it, a retry or sync button and a remove button; failures are announced as alerts" }, { "keys": "Remove", "action": "Asks for confirmation in an alert dialog first" }, { "keys": "Test", "action": "Results are a polite live region marked busy while searching; matches are real mark elements and scores are also written as text" } ], "customization": [ "title, exampleQuestions, defaultQuestion (runs once at the start)", "progress (0 to 1) drives the bar of a syncing source", "onAsk gets the enabled, ready sources; return passages with a score from 0 to 1 and, if you have one, an answer" ] }, "states": [ { "id": "loading", "title": "Loading", "example": "agent-8-loading", "trigger": "state=\"loading\"", "note": "A skeleton of the summary, the source cards and the test panel under the real heading." }, { "id": "empty", "title": "No sources yet", "example": "agent-8-empty", "trigger": "state=\"empty\" (or sources={[]})", "note": "Explains what knowledge is and offers the three ways to add it as large buttons (website, files, pasted text); emptyState sets the copy." }, { "id": "error", "title": "Could not load", "example": "agent-8-error", "trigger": "state=\"error\"", "note": "An alert saying nothing was changed, with Try again (onRetry). A single source that fails to sync shows its reason and Retry on its own card." } ], "examples": [ "agent-8-demo", "agent-8-no-match", "agent-8-empty", "agent-8-loading", "agent-8-error" ], "url": "https://ui.ballmac.com/components/agent-8" }, "categories": [ "blocks", "agents" ], "type": "registry:block" }