Provider Setup — Agentuity Documentation

Provider Setup

Legacy AgentuityProvider setup for @agentuity/react apps

This page covers the AgentuityProvider compatibility layer from @agentuity/react. For new apps, use hc() directly and keep auth state in @agentuity/auth/react or your framework's auth provider.

Basic Setup

import { AgentuityProvider } from '@agentuity/react';
 
export default function App() {
  return (
    <AgentuityProvider>
      <YourApp />
    </AgentuityProvider>
  );
}

By default, the provider resolves its base URL in this order:

  1. NEXT_PUBLIC_AGENTUITY_URL, VITE_AGENTUITY_URL, or AGENTUITY_URL
  2. window.location.origin
  3. http://localhost:3500

Production Configuration

For deployed applications, set the baseUrl to your Agentuity deployment:

import { AgentuityProvider } from '@agentuity/react';
 
export default function App() {
  return (
    <AgentuityProvider baseUrl="https://your-project.agentuity.cloud">
      <YourApp />
    </AgentuityProvider>
  );
}

Environment-Based Configuration

Use your framework's public env var pattern to switch between development and deployment:

import { AgentuityProvider } from '@agentuity/react';
 
const baseUrl = import.meta.env.VITE_AGENTUITY_URL;
 
export default function App() {
  return (
    <AgentuityProvider baseUrl={baseUrl}>
      <YourApp />
    </AgentuityProvider>
  );
}

In Next.js, use process.env.NEXT_PUBLIC_AGENTUITY_URL instead.

Provider Props

PropTypeDefaultDescription
baseUrlstringEnv var → window.location.origin → http://localhost:3500Base URL for API requests
authHeaderstring | nullnullOptional Authorization header shared with Agentuity transport helpers
childrenReactNode—Your app components

Using hc() with the Provider

AgentuityProvider does not automatically configure hc(). Use a relative /api client for same-origin frontends, or read baseUrl from the provider when your frontend is deployed separately:

import { useAgentuity } from '@agentuity/react';
import { hc } from 'hono/client';
import type { ApiRouter } from '../api/index';
 
function ChatButton() {
  const { baseUrl } = useAgentuity();
  const client = hc<ApiRouter>(`${baseUrl}/api`);
 
  return (
    <button onClick={() => client.chat.$post({ json: { message: 'Hello' } })}>
      Send
    </button>
  );
}

Authentication Integration

For apps with user authentication, keep AgentuityProvider and AuthProvider separate. AgentuityProvider does not automatically consume tokens from AuthProvider.

Use AuthProvider callbacks to mirror the current bearer token into AgentuityProvider:

import { useState } from 'react';
import { AgentuityProvider } from '@agentuity/react';
import { AuthProvider, createAuthClient } from '@agentuity/auth/react';
 
const authClient = createAuthClient();
 
export default function App() {
  const [authHeader, setAuthHeader] = useState<string | null>(null);
 
  return (
    <AgentuityProvider authHeader={authHeader}>
      <AuthProvider
        authClient={authClient}
        onAuthHeaderChange={setAuthHeader}
      >
        <YourApp />
      </AuthProvider>
    </AgentuityProvider>
  );
}

If you prefer, you can also attach auth headers in a custom fetch passed to hc(). See Adding Authentication for the full auth flow.

Type Safety

For route calls, export your router type from src/api/index.ts and import it directly into your frontend. No separate .agentuity/types.d.ts registry is required.

import { hc } from 'hono/client';
import type { ApiRouter } from '../api/index';
 
const client = hc<ApiRouter>('/api');
const res = await client.chat.$post({ json: { message: 'Hello' } }); // Type-safe

Next Steps