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

> [!WARNING]
> **Compatibility Layer**
> `@agentuity/react` is deprecated. Use this provider only when you already depend on its transport auth, analytics, or WebRTC hooks.

## Basic Setup

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

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

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

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `baseUrl` | `string` | Env var → `window.location.origin` → `http://localhost:3500` | Base URL for API requests |
| `authHeader` | `string \| null` | `null` | Optional `Authorization` header shared with Agentuity transport helpers |
| `children` | `ReactNode` | — | 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:

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

```tsx
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](/frontend/authentication) for the full auth flow.

> [!NOTE]
> **Two Different Auth Contexts**
> `@agentuity/react` manages transport state like `authHeader` and `baseUrl`. `@agentuity/auth/react` manages signed-in user and session state. They complement each other, but one does not replace the other.

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

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

> [!NOTE]
> **Type Generation**
> The typed client comes from your exported router type. If route inference looks wrong, check that your root router is exported as a single chained expression, like the current testing apps.

## Next Steps

- [React Hooks](/frontend/react-hooks): Auth, analytics, and WebRTC hooks from `@agentuity/react`
- [Deployment Scenarios](/frontend/deployment-scenarios): Choose where your frontend lives
- [Adding Authentication](/frontend/authentication): Configure sign-in, sessions, and API protection