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

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, 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:

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

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 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 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 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:

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:

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 and routes the request to the Builder.io implementation.

Handling Connection Errors

When Builder.io is not configured, the 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:

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 accepts custom providers that implement the file-upload interface:

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:

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, 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 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 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 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. Once registered, the upload action in 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 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. 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.

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