How to Integrate Agent-Native into a React Native Project: Complete Implementation Guide

You can integrate Agent-Native into a React Native application by either calling server actions directly via the @agent-native/client package or embedding the full web interface inside a React Native WebView.

Agent-Native is a full-stack framework developed by BuilderIO that couples a React frontend with an AI-driven Nitro backend. Since the framework's UI is web-based, React Native integration relies on consuming the backend's typed action API or hosting the existing interface within a native container.

Architecture Overview

Agent-Native separates concerns between a Nitro server (backend) and a React UI (frontend). The backend exposes actions—typed, secure endpoints defined in the actions/ folder—that both the web UI and external clients can invoke via HTTP/JSON RPC.

+-------------------+          +------------------------+          +-------------------+
| React Native App |  <--→   | Agent-Native Backend   |  <--→   | Data stores (SQL) |
| (JS/TS)           |  HTTP    | (Nitro server)         |  SQL    | (Drizzle)         |
+-------------------+          +------------------------+          +-------------------+

• Server side: Business logic lives in actions/ and runs on Node.js ≥ 22.
• Client side: The @agent-native/client npm package provides type-safe calls, automatic header injection, and conversation context handling.
• Authentication: Credentials store in the SQL layer (application_state), accessed via the /api/auth action defined in docs/auth.md.

Integration Methods

Direct Action Calls

Use the @agent-native/client library (or plain fetch) to invoke actions at /api/<action-name> from React Native code. This pattern suits native screens that need data, CRUD operations, or AI-driven workflows without rendering the web UI.

WebView Embedding

Load a hosted Agent-Native page (e.g., https://my-app.agentnative.builder.io) inside react-native-webview. The WebView runs the full Agent-Native interface—complete with shadcn/ui components and AI chat—while the native app exchanges messages via postMessage/onMessage.

Step-by-Step Integration Guide

1. Deploy the Agent-Native Backend

Start the Nitro server locally or deploy to production:

# From the repository root

pnpm dev

This starts a development server at http://localhost:3000. For production deployment, follow the Netlify guide in docs/neon-netlify-integration.md. Note your base URL (e.g., https://my-app.agentnative.builder.io).

2. Install the Client Package

Add the official client to your React Native project:

npm install @agent-native/client

The client is a thin wrapper around fetch that automatically adds the required x-agent-native-session header and marshals JSON payloads.

3. Configure the Agent Client

Create a configuration file to initialize the client:

// src/agentNative.ts
import { createAgentClient } from '@agent-native/client';

export const agent = createAgentClient({
  baseUrl: 'https://my-app.agentnative.builder.io', // Your deployed URL
});

Optionally, attach an authentication token getter:

export const agent = createAgentClient({
  baseUrl: 'https://my-app.agentnative.builder.io',
  getAuthToken: async () => await AsyncStorage.getItem('agentToken'),
});

4. Invoke Actions from React Native

Assuming the repository defines a createTask action in actions/createTask.ts, call it from your component:

// src/screens/TaskScreen.tsx
import React, { useState } from 'react';
import { View, TextInput, Button, Text } from 'react-native';
import { agent } from '../agentNative';

export default function TaskScreen() {
  const [title, setTitle] = useState('');
  const [result, setResult] = useState<string | null>(null);

  const createTask = async () => {
    const response = await agent.action('createTask', { title });
    setResult(response?.message ?? 'No response');
  };

  return (
    <View style={{ padding: 20 }}>
      <TextInput 
        placeholder="Task title" 
        value={title} 
        onChangeText={setTitle} 
      />
      <Button title="Create task" onPress={createTask} />
      {result && <Text>{result}</Text>}
    </View>
  );
}

The agent.action method makes a POST request to /api/createTask and returns the JSON payload defined by the server-side action.

5. Embed the Full UI (Optional)

To render the complete Agent-Native interface inside your app:

// src/screens/AgentScreen.tsx
import { WebView } from 'react-native-webview';
import React from 'react';

export default function AgentScreen() {
  return (
    <WebView
      source={{ uri: 'https://my-app.agentnative.builder.io' }}
      onMessage={event => {
        // Receive messages from the web UI
        console.log('From web:', event.nativeEvent.data);
      }}
      injectedJavaScript={`
        // Send native auth token to web app on load
        window.dispatchEvent(new CustomEvent('agent-native-auth', {
          detail: { token: '${/* retrieve token here */''}' }
        }));
        true;
      `}
    />
  );
}

This approach gives you the drag-and-drop AI assistant UI without reimplementing components in native code.

6. Handle Authentication

Authenticate users via the standard login action:

const auth = await agent.action('login', { email, password });
// Store securely using react-native-keychain
await AsyncStorage.setItem('agentToken', auth.token);

Reference the authentication flow in docs/auth.md for JWT handling and session management.

Complete Code Examples

Initializing with Async Authentication

// agentNative.ts
import { createAgentClient } from '@agent-native/client';
import AsyncStorage from '@react-native-async-storage/async-storage';

export const agent = createAgentClient({
  baseUrl: 'https://my-app.agentnative.builder.io',
  getAuthToken: async () => await AsyncStorage.getItem('agentToken'),
});

Fetching User Data

// UserProfile.tsx
import React, { useEffect, useState } from 'react';
import { Text, View } from 'react-native';
import { agent } from './agentNative';

export default function UserProfile() {
  const [profile, setProfile] = useState<any>(null);

  useEffect(() => {
    (async () => {
      const data = await agent.action('getUserProfile', { userId: '123' });
      setProfile(data);
    })();
  }, []);

  return (
    <View>
      {profile ? (
        <>
          <Text>Name: {profile.name}</Text>
          <Text>Email: {profile.email}</Text>
        </>
      ) : (
        <Text>Loading…</Text>
      )}
    </View>
  );
}

Key Files and References

• actions/: Directory containing server-side action definitions that form the API contract for your React Native client.
• docs/auth.md: Documents the standard auth flow (/api/login) and JWT requirements.
• docs/neon-netlify-integration.md: Production deployment guide for the Nitro backend.
• DEVELOPMENT.md: Local development workflow using pnpm dev.
• packages/core/docs/content/using-your-agent.md: Details on how the UI consumes actions and the agent-native client architecture.

Summary

• Two integration paths: Direct action calls via @agent-native/client for native-first experiences, or WebView embedding for the full Agent-Native UI.
• Backend requirement: Deploy the Nitro server (Node ≥ 22) from the BuilderIO/agent-native repository before connecting your React Native app.
• Type-safe API: Use createAgentClient to invoke actions defined in the actions/ folder with automatic header injection and JSON marshaling.
• Authentication: Implement JWT storage using react-native-keychain and pass tokens via the client's getAuthToken option or WebView postMessage.

Frequently Asked Questions

Can I run Agent-Native directly inside React Native without a WebView?

No. Agent-Native's UI layer depends on web-specific technologies like shadcn/ui and ReactDOM. To integrate agent-native into a React Native project, you must either call the backend actions via HTTP (using the @agent-native/client package) or embed the hosted web UI in a WebView.

How do I handle real-time updates between the Agent-Native backend and React Native?

The @agent-native/client package uses standard HTTP requests. For real-time features, poll the action endpoints or use WebSocket connections if your specific Agent-Native implementation exposes them. The WebView embedding method automatically handles real-time updates since the web UI manages its own state.

What Node.js version is required for the Agent-Native backend?

The server requires Node.js version 22 or higher. This is specified in the repository's environment requirements and is necessary for the Nitro server to function correctly.

Where do I define custom actions for my React Native app to call?

Define custom actions in TypeScript files under the actions/ directory at the repository root. These files export typed functions that automatically become available at /api/<action-name> endpoints, which your React Native client can invoke via agent.action() or standard fetch requests.

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