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

> Learn to manage components with Agent-Native. Import, create, and register UI building blocks easily without extra build steps. Streamline your development workflow today.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-21

---

**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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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.

```tsx
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`](https://github.com/BuilderIO/agent-native/blob/main/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.

```tsx
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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/templates/content/shared/local-component-workspaces.ts) and makes the component available to the runtime.

```tsx
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.

```tsx
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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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.