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

> Learn how to integrate Agent-Native into your React Native app. Explore direct server actions or WebView embedding for a seamless implementation.

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

---

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

```bash

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

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

```typescript
// 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:

```typescript
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`](https://github.com/BuilderIO/agent-native/blob/main/actions/createTask.ts), call it from your component:

```tsx
// 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:

```tsx
// 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:

```typescript
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`](https://github.com/BuilderIO/agent-native/blob/main/docs/auth.md) for JWT handling and session management.

## Complete Code Examples

### Initializing with Async Authentication

```typescript
// 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

```tsx
// 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`](https://github.com/BuilderIO/agent-native/blob/main/docs/auth.md)**: Documents the standard auth flow (`/api/login`) and JWT requirements.
- **[`docs/neon-netlify-integration.md`](https://github.com/BuilderIO/agent-native/blob/main/docs/neon-netlify-integration.md)**: Production deployment guide for the Nitro backend.
- **[`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md)**: Local development workflow using `pnpm dev`.
- **[`packages/core/docs/content/using-your-agent.md`](https://github.com/BuilderIO/agent-native/blob/main/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.