How to Manage Components with Agent-Native: Import, Create, and Register UI Building Blocks

Agent-Native treats UI building blocks as first-class components that you can import from @agent-native/core/client, generate via server-side actions, and register in a workspace-based registry without additional build steps.

Managing components in the BuilderIO/agent-native framework revolves around a three-layer architecture that bridges React UI primitives with server-side asset management. The system enables you to consume pre-built panels, generate animated assets from natural language prompts, and maintain custom definitions in a SQL-backed workspace registry. This guide walks through the complete workflow for managing components with Agent-Native using the Component API, registry operations, and server actions.

Understanding the Component Architecture

Agent-Native organizes UI management into three distinct layers that work together to provide seamless component lifecycle management.

Component API Layer

The Component API consists of public React components exported directly from @agent-native/core/client. These include ready-to-use interfaces like AgentPanel, chat widgets, and presence indicators. You import and render these components like standard React elements, as implemented in packages/core/src/client/chat/AgentPanel.tsx.

Component Registry

The Component Registry is a central map that tracks local component definitions, including custom panels and animated assets. This registry lives in templates/content/shared/local-component-workspaces.ts and maintains the relationship between component IDs and their file system locations. Because the registry is SQL-backed in the workspace, any updates are immediately visible to the agent and UI without requiring rebuilds.

Component Actions

Component Actions are server-side operations that create, list, or update component assets. Key actions include:

• generate-animated-component – Builds animated components from text prompts, located in templates/videos/actions/generate-animated-component.ts
• list-plan-components – Returns components defined in a Plan, found in templates/plan/actions/list-plan-components.ts
• write-local-component-file, register-local-component-workspace, list-local-component-files – CRUD helpers for workspace component files in templates/content/actions/

Importing and Using Core UI Components

Start by importing pre-built components from the core client package. These components handle complex UI patterns like chat interfaces and resource panels.

import { AgentPanel } from "@agent-native/core/client";

export default function MyPage() {
  return (
    <section className="h-screen">
      {/* Full-width panel with built-in chat and sidebar */}
      <AgentPanel />
    </section>
  );
}

The AgentPanel component referenced above is defined in packages/core/src/client/chat/AgentPanel.tsx and provides a complete agent interface with minimal configuration.

Generating Custom Components via Server Actions

Create new animated components dynamically using the generate-animated-component action. This server action accepts a text prompt and generates the corresponding component assets.

import { useAction } from "@agent-native/core/client";
import { generateAnimatedComponent } from "@/actions/generate-animated-component";

export default function CreateAnim() {
  const generate = useAction(generateAnimatedComponent);

  const onClick = async () => {
    const result = await generate.mutate({
      prompt: "A rotating blue cube",
    });
    console.log("Component created:", result.id);
  };

  return <button onClick={onClick}>Create Animated Component</button>;
}

The action implementation in templates/videos/actions/generate-animated-component.ts handles the asset generation and returns the component metadata needed for registration.

Registering Components in the Local Workspace

After creating or writing component files, register them in the workspace registry using the register-local-component-workspace action. This updates the central registry in templates/content/shared/local-component-workspaces.ts and makes the component available to the runtime.

import { useAction } from "@agent-native/core/client";
import { registerLocalComponentWorkspace } from "@/actions/register-local-component-workspace";

export default function RegisterMyComp() {
  const register = useAction(registerLocalComponentWorkspace);

  const onRegister = async () => {
    await register.mutate({
      id: "my-widget",
      entry: "src/components/MyWidget.tsx",
      config: { title: "My Widget" },
    });
  };

  return <button onClick={onRegister}>Register Component</button>;
}

This action writes a JSON definition into the local component workspace and updates the registry, allowing the runtime to resolve imports dynamically.

Listing and Managing Existing Components

Query existing components using the plan and content actions to build management interfaces or perform updates.

import { useAction } from "@agent-native/core/client";
import { listPlanComponents } from "@/actions/list-plan-components";

export default function ComponentList() {
  const list = useAction(listPlanComponents);
  const { data, isLoading } = list.useQuery();

  if (isLoading) return <p>Loading…</p>;

  return (
    <ul>
      {data?.components.map((c) => (
        <li key={c.id}>{c.name}</li>
      ))}
    </ul>
  );
}

To modify component files, use the write-local-component-file action in templates/content/actions/write-local-component-file.ts. This maintains synchronization between the file system and the SQL-backed registry.

Summary

• Import core components from @agent-native/core/client for immediate rendering of chat panels and agent interfaces
• Generate animated assets using the generate-animated-component action from templates/videos/actions/generate-animated-component.ts
• Register custom components via registerLocalComponentWorkspace to update the SQL-backed registry at templates/content/shared/local-component-workspaces.ts
• Manage component lifecycle with CRUD actions including listPlanComponents, writeLocalComponentFile, and listLocalComponentFiles
• Consume registered components by importing them from the core client package, where the runtime automatically resolves them from the workspace registry

Frequently Asked Questions

What is the difference between core components and custom components in Agent-Native?

Core components are pre-built React components exported from @agent-native/core/client and documented in packages/core/docs/content/components.md. Custom components are generated via actions like generate-animated-component or written manually and registered in the local workspace registry via templates/content/actions/register-local-component-workspace.ts.

Where does Agent-Native store custom component definitions?

Custom component definitions are stored in a SQL-backed workspace registry defined in templates/content/shared/local-component-workspaces.ts. The registry is populated and maintained through server actions that write JSON metadata and update the central map, making components instantly available without rebuilds.

Do I need to rebuild my application after adding a new component?

No. Because the component registry is SQL-backed and managed through server-side actions, new components become immediately visible to the agent, the UI, and other actions. The runtime resolves components dynamically from the workspace registry, eliminating the need for additional build steps.

How do I generate an animated component from a text prompt?

Use the generateAnimatedComponent action implemented in templates/videos/actions/generate-animated-component.ts. Import the action into your React component, invoke it via the useAction hook from @agent-native/core/client, and pass a prompt string describing the desired animation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}