# How to Use Builder.io with Agent-Native: Complete Integration Guide

> Integrate Builder.io with Agent-Native effortlessly. Learn how to enable file uploads and leverage storage capabilities with our complete guide. Get started now.

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

---

**Agent-Native automatically enables Builder.io file uploads when you set the `BUILDER_API_KEY` and `BUILDER_PRIVATE_KEY` environment variables, exposing storage capabilities through the `@agent-native/core/file-upload` module.**

Integrating Builder.io with Agent-Native provides a managed CDN for images and assets without manual configuration. The BuilderIO/agent-native repository ships with a built-in provider that handles authentication, signed URLs, and upload retries automatically. This guide covers the architecture, setup steps, and code implementations needed to leverage Builder.io storage in your Agent-Native applications.

## Architecture Overview

Agent-Native treats Builder.io as the default file-upload provider when credentials are present. The system uses a registry pattern to manage providers, with Builder.io serving as the automatic fallback.

### Automatic Provider Registration

When the environment variables `BUILDER_API_KEY` and `BUILDER_PRIVATE_KEY` are detected, the core module automatically registers the Builder.io provider. According to the source code in [`packages/core/src/file-upload/registry.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/registry.ts), the registry maintains a priority list where the first registered provider handles all upload operations.

If you need to override this with custom storage (S3, R2, GCS), call `registerFileUploadProvider()` before the app initializes:

```typescript
import { registerFileUploadProvider } from "@agent-native/core/file-upload";
import { s3FileUploadProvider } from "./my-s3-provider";

registerFileUploadProvider(s3FileUploadProvider);

```

Place this registration in a server-side plugin such as [`templates/content/server/plugins/onboarding.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/content/server/plugins/onboarding.ts) to ensure it loads before any upload actions execute.

### Connection Flow and OAuth

The connection UI lives in Settings → File uploads and renders a "Connect Builder.io" card. This card is generated by the `connect-builder` tool defined in [`packages/core/src/server/agent-chat-plugin.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/agent-chat-plugin.ts).

When a user clicks the card, Builder.io's OAuth flow initiates and stores credentials in the app's secret store. The `useBuilderStatus` hook in [`packages/core/src/client/settings/useBuilderStatus.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/client/settings/useBuilderStatus.ts) exposes the connection state (`connected`, `not-connected`, or `error`) and provides a `connect()` method to trigger this flow programmatically.

### Upload Actions and the Registry

The `upload-image` action in [`packages/core/src/file-upload/actions/upload-image.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/actions/upload-image.ts) serves as the public API for file storage. This action posts files to the currently configured provider and returns a CDN URL. If no provider is available, the action throws an error at line 136 with the message: *"Connect or reconnect Builder.io in Settings → File uploads…"*.

The concrete implementation in [`packages/core/src/file-upload/builder.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/builder.ts) handles the signed-URL flow and retry logic specific to Builder.io's infrastructure.

## Setting Up Builder.io Authentication

Before uploading files, configure your environment variables:

```bash
BUILDER_API_KEY=your_public_api_key
BUILDER_PRIVATE_KEY=your_private_key

```

With these variables set, Agent-Native automatically instantiates the Builder.io provider at runtime. No additional configuration is required to start uploading files through the default registry.

## Uploading Files with the Builder.io Provider

### Basic Image Upload Example

Import the `uploadImage` action from the core package to handle file uploads:

```tsx
import { uploadImage } from "@agent-native/core/file-upload/actions";
import { useState } from "react";

export default function ImageUploader() {
  const [url, setUrl] = useState("");
  
  const handleFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    try {
      const result = await uploadImage({ file });
      setUrl(result.url); // Returns Builder.io CDN URL
    } catch (err) {
      console.error("Upload failed:", err);
    }
  };

  return (
    <>
      <input type="file" accept="image/*" onChange={handleFile} />
      {url && <img src={url} alt="Uploaded" />}
    </>
  );
}

```

The `uploadImage` function internally queries the registry established in [`packages/core/src/file-upload/registry.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/registry.ts) and routes the request to the Builder.io implementation.

### Handling Connection Errors

When Builder.io is not configured, the [`pre-upload-attachments.ts`](https://github.com/BuilderIO/agent-native/blob/main/pre-upload-attachments.ts) helper displays a "Connect Builder.io" suggestion at line 292. Your UI should catch upload errors and guide users to the Settings page:

```tsx
try {
  const result = await uploadImage({ file });
} catch (err) {
  if (err.message.includes("Connect or reconnect Builder.io")) {
    // Redirect to Settings → File uploads
    openSettingsPage();
  }
}

```

## Implementing Custom File Upload Providers

While Builder.io works automatically, you can register alternative storage solutions. The registry in [`packages/core/src/file-upload/registry.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/registry.ts) accepts custom providers that implement the file-upload interface:

```typescript
import { registerFileUploadProvider } from "@agent-native/core/file-upload";

const customProvider = {
  upload: async (file: File) => {
    // Your custom upload logic
    return { url: "https://your-cdn.com/file.jpg" };
  }
};

registerFileUploadProvider(customProvider);

```

Once registered, all calls to `uploadImage` automatically use your custom provider instead of Builder.io.

## Monitoring Connection Status in the UI

Surface the Builder.io connection state to users with the `useBuilderStatus` hook:

```tsx
import { useBuilderStatus } from "@agent-native/core/client/settings/useBuilderStatus";

export function BuilderStatusPanel() {
  const { status, connect } = useBuilderStatus();

  return (
    <div>
      {status === "connected" ? (
        <p>Builder.io is connected.</p>
      ) : (
        <button onClick={connect}>Connect Builder.io</button>
      )}
    </div>
  );
}

```

The `connect` function triggers the `connect-builder` tool from [`packages/core/src/server/agent-chat-plugin.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/agent-chat-plugin.ts), opening the OAuth card without manual navigation.

## Summary

- **Agent-Native** automatically configures Builder.io as the file-upload provider when `BUILDER_API_KEY` and `BUILDER_PRIVATE_KEY` environment variables are present.
- The **file-upload registry** in [`packages/core/src/file-upload/registry.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/registry.ts) manages provider selection and can be overridden with custom storage via `registerFileUploadProvider()`.
- Use the **`uploadImage`** action from [`packages/core/src/file-upload/actions/upload-image.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/actions/upload-image.ts) to upload files and receive CDN URLs.
- Implement the **`useBuilderStatus`** hook to display connection states and trigger the OAuth flow programmatically.
- The **Builder.io provider** implementation in [`packages/core/src/file-upload/builder.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/builder.ts) handles signed URLs, retries, and CDN distribution automatically.

## Frequently Asked Questions

### How do I switch from Builder.io to AWS S3 for file uploads?

Register your S3 provider using `registerFileUploadProvider()` before the app initializes. Place this call in a server-side plugin such as [`templates/content/server/plugins/onboarding.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/content/server/plugins/onboarding.ts). Once registered, the upload action in [`packages/core/src/file-upload/actions/upload-image.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/actions/upload-image.ts) automatically routes files to your S3 implementation instead of Builder.io.

### What happens if Builder.io credentials are missing or invalid?

If the `BUILDER_API_KEY` or `BUILDER_PRIVATE_KEY` variables are missing, the Builder.io provider remains unregistered. When attempting to upload, the `uploadImage` action throws an error at line 136 guiding users to "Connect or reconnect Builder.io in Settings → File uploads." The [`pre-upload-attachments.ts`](https://github.com/BuilderIO/agent-native/blob/main/pre-upload-attachments.ts) helper also surfaces a connection suggestion in the UI.

### Can I use Builder.io alongside other storage providers?

Agent-Native supports only one active provider at a time per the registry pattern in [`packages/core/src/file-upload/registry.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/registry.ts). While you cannot use Builder.io and S3 simultaneously for the same upload action, you can register different providers for different environments (Builder.io for production, custom S3 for staging) by conditionalizing the `registerFileUploadProvider()` call based on environment variables.

### How do I check if Builder.io is properly connected from my React component?

Import `useBuilderStatus` from `@agent-native/core/client/settings/useBuilderStatus`. This hook returns a `status` string (`connected`, `not-connected`, or `error`) and a `connect` function that launches the Builder.io OAuth card. The hook reads from the same secret store used by the `connect-builder` tool in [`packages/core/src/server/agent-chat-plugin.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/agent-chat-plugin.ts).