Toolkit

Toolkit is the reusable, battle-tested building-block shelf for high-quality agentic applications. It turns the hard product work that repeats across apps into standard surfaces without making one app pattern the center of the catalog.

This section is the single discovery shelf for reusable app-building UI. A surface belongs in these docs because it is reusable, even when its current implementation owner is Core or a template. Ownership labels and import paths make that boundary explicit without scattering related UI guidance across the site.

Each kit packages the UI patterns, action contracts, app-state expectations, access boundaries, and agent-visible behavior that users expect to work consistently. Apps still own their domain model and visual identity; Toolkit makes the common product systems feel complete from the first version instead of being rebuilt in slightly different ways every time.

The mock shows one possible app composition. The app owns its dashboard data and routes; Toolkit provides reusable surfaces that can be adopted independently.

Core is the framework. Toolkit is an optional shelf of reusable pieces for the framework. Templates are optional apps built on Core; they can use Toolkit and can be forked and used as complete starting points. An app can also use Core directly without adopting Toolkit or a template.

Catalog

Area Start here What it covers
Foundations UI Primitives Shared controls, hooks, app adapters, and shell seams.
Editors & canvases Editors & Canvases Rich editing, structured blocks, reusable canvas controls, and Design patterns.
Agent experience & context Context & Knowledge Context X-Ray, resources, knowledge, composer context, and agent-visible state.
Collaboration & governance Collaboration Sharing, presence, review, history, audit, and organization boundaries.
Workspace chrome App Chrome Settings, teams, setup, navigation, resources, and agent UX.
Operations Observability Usage, feedback, replay, diagnostics, and operational visibility.
Capability modules Toolkit Capability Modules Scheduling, Creative Context, and Pinpoint as install-on-demand packages.

Product kits

Kit Use it for
Agent Page Full-page agent configuration surface; apps choose whether to mount it.
Canvas interactions Headless gestures and shortcuts plus optional drawing and comment-pin UI.
Chat History Reusable chat list and rail; the app supplies thread data and callbacks.
Data Grid Spreadsheet-like grid mechanics; apps own rows, editors, actions, and persistence.
Dashboard Presentational dashboard panels and layout; the app supplies data and state.
Sharing Ownable resources, share dialogs, visibility badges, share actions, public/private/org access.
Collaboration Realtime editing, presence, live cursors, recent-edit highlights, collaborative undo.
Settings Standard settings pages and tabs so app settings and agent/provider settings live in one predictable place.
Org & Team Team pages, org switching, invites, org domains, roles, and app switching.
Setup & Connections Onboarding, secrets, workspace connections, OAuth/provider readiness, and Builder connect (free tier available).
Command & Navigation Command menu, deep links, standard app routes, sidebar and shell patterns.
Resources Resource trees, editors, file picker/search, attachments, and local file mode.
Agent UX Composer, model picker, context chips, approvals, run recovery, and the runs tray.
History Version and audit APIs, undo/redo foundations, and guidance for app-owned history and diff views.
Comments & Review Registered reviewable resources, comment actions, feedback queues, thread panels, mentions, resolved threads, and review status.
Notifications Notification inbox and bell surfaces with app-owned event and routing policy.
Observability Usage, spend, feedback, replay, errors, and run diagnostics.

Package maturity and ownership

  • The rich editor is Toolkit-owned. The old @agent-native/core/client and @agent-native/core/client/editor import paths are deprecated tombstones, not compatibility re-exports — see Editors & Canvases for the migration path.
  • Design is a template pattern with reusable design-tweaks; it is not a full drop-in editor or canvas package.
  • Core owns the Blocks schema and runtime contract; Toolkit provides reusable client UI under @agent-native/toolkit/app/blocks.
  • The Context X-Ray engine remains Core-owned; its reusable presentation is Toolkit-owned.
  • Scheduling, Creative Context, and Pinpoint are Toolkit capability modules installed on demand; Dispatch is a separate product, not one of them — see Toolkit Capability Modules for package maturity and ownership.

Dashboard kit

@agent-native/toolkit/dashboard is an ejectable, presentation-only unit for metric and stats cards, data tables, date-range controls, panel ordering and layout, and generic chart rendering. It receives rows and callbacks from an app-owned adapter: it never fetches data, resolves credentials, or owns a dashboard's state.

Use agent-native eject inspect toolkit/dashboard before applying toolkit/dashboard to an app. Keep durable dashboards in that app with @agent-native/core/dashboard-storage: instantiate its access-scoped schema and store per app, not in a cross-app dashboard table. Panel data flows through a PanelSourceResolver; the built-in program source runs an app-owned data program and is the canonical no-provider default. Provider resolvers belong in the app that owns their connection and query policy.

Implementation Boundary

Toolkit docs are organized by reusable product capability, not npm package. Kits are product surfaces first. Some pieces are runtime-backed (@agent-native/core), some are presentation primitives (@agent-native/toolkit), and apps usually wrap both through local adapters. Use the package path that owns the needed behavior, but design the user-facing settings, collaboration, sharing, team, review, and setup experiences as one coherent kit instead of exposing package boundaries in the app.

Customize or eject a kit

Adopt shared behavior in this order: configure the public component or adapter, compose public primitives behind an app-owned wrapper, eject the smallest supported unit, then propose a new shared seam when the same override appears in multiple apps.

Toolkit publishes readable, version-matched source and an ejection manifest that covers every public entry point. Inspect a unit before taking ownership:

agent-native eject --list
agent-native eject inspect <unit>
agent-native eject <unit> --app <app>
agent-native eject <unit> --app <app> --apply

The dry run reports all files and consumer imports that will change. Applying the plan copies the complete source closure into the app, rewrites only the declared imports, and records package version, manifest digest, file hashes, and rewrites in the committed agent-native.ejections.json. Chat history is one such unit: an app can own its presentation while Core continues to own thread state, access, persistence, and chat transport.

Use agent-native eject diff <unit> --app <app> to inspect drift. Use agent-native eject restore <unit> --app <app> to preview a return to the package implementation, then add --apply. Restore refuses when any ejected file or rewritten import has local edits, so app-owned changes are never silently discarded.

The same unit contract covers first-party integration surfaces: remote MCP presets, workspace-connection providers, provider API definitions, messaging/channel adapters, setup and readiness UI, and domain packages. The catalog is complete by construction; a missing first-party unit fails the release guard. Unknown third-party packages receive an add-style blueprint. Protected runtime contracts are not ejectable and instead route to their public configuration, adapter, or extension seam.

Foundation Pieces

  • UI Primitives covers the shared shadcn-style primitives under @agent-native/toolkit/ui/*, the local app-adapter pattern every template wraps them in, and the shared shell hooks (header actions, mobile detection, toasts).
  • Component API remains the lower-level reference for the public React exports.

Design Rule

Use a toolkit when the behavior repeats across apps and users expect it to feel standard: sharing, settings, teams, comments, history, and agent progress should not be slightly different in every template. Keep domain-specific data, workflows, labels, and visual styling in the app.

What's next

  • Toolkit UI Primitives — the shared primitives, app adapters, and shell hooks every kit builds on.
  • Sharing Kit — a good first kit to adopt: ownable resources, share dialogs, and visibility.
  • Creating Templates — build a template end to end and see where kits fit alongside your own domain model.
  • Component API — the generated reference for every public React export, including kit components.
  • Package Lifecycle — inspect, add, and eject manifest-driven capability packages safely.
Edit this page on GitHub