Agentuity Documentation

Choose the deployment shape that matches your app. The SDK supports both same-origin frontends bundled with your Agentuity app and separate frontends hosted elsewhere.

All-in-One Deployment

Put your frontend code in src/web/ and deploy everything together:

my-project/
├── src/
│   ├── agent/
│   │   └── chat/
│   │       └── agent.ts
│   ├── api/
│   │   └── index.ts
│   └── web/
│       ├── App.tsx
│       ├── frontend.tsx
│       └── index.html
└── agentuity.json

When you run agentuity deploy, both your agents and frontend are bundled and deployed together.

// src/web/App.tsx
import { hc } from 'hono/client';
import type { ApiRouter } from '../api/index';
 
const client = hc<ApiRouter>('/api');
 
function Chat() {
  // Use hc() for type-safe API calls
  const handleSend = async (message: string) => {
    const res = await client.chat.$post({ json: { message } });
    return res.json();
  };
  // ... your chat UI
}
 
export default function App() {
  return <Chat />;
}

No baseUrl Needed

When frontend and agents are deployed together, hc<ApiRouter>('/api') automatically targets the same origin. Add AgentuityProvider only if you use @agentuity/react hooks (see Provider Setup).

Best for:

New projects starting from scratch
Simple deployments with one codebase
Projects that don't need separate frontend scaling

Separate Frontend

Deploy your frontend on Vercel, Netlify, or any hosting platform while agents run on Agentuity:

Frontend (e.g., Vercel)                Agents (Agentuity)
┌───────────────────────┐           ┌───────────────────────┐
│     your-app.com      │ ────────► │    project.cloud      │
│     React/Next.js     │           │     Agent routes      │
└───────────────────────┘           └───────────────────────┘

import { hc } from 'hono/client';
import type { ApiRouter } from '@acme/agentuity-contract';
 
const agentuityBaseUrl = 'https://your-project.agentuity.cloud';
const client = hc<ApiRouter>(`${agentuityBaseUrl}/api`);
 
function Chat() {
  const send = async (message: string) => {
    const res = await client.chat.$post({ json: { message } });
    return res.json();
  };
 
  return <button onClick={() => send('Hello from Vercel')}>Send</button>;
}
 
export default function App() {
  return <Chat />;
}

Share the Router Type or Use fetch

If your frontend lives in a separate repo, put ApiRouter in a shared package or call the backend with plain fetch. hc() only needs the exported router type, not a generated registry.

Best for:

Existing projects adding AI agents
Teams with separate frontend and backend deployments

CORS Configuration

When your frontend and agents are on different domains, configure CORS in app.ts:

// app.ts
import { createApp } from '@agentuity/runtime';
 
export default await createApp({
  cors: {
    sameOrigin: true,
    allowedOrigins: ['https://your-frontend.com'],
  },
});

Required for Cross-Origin

Without CORS configuration, browsers will block requests from your frontend to your agents when they're on different domains.

Comparison

Aspect	All-in-One	Separate Frontend
Deployment	Single `agentuity deploy`	Deploy frontend and agents separately
Configuration	Minimal	Requires `baseUrl`, absolute API URLs, and CORS
Scaling	Tied together	Independent scaling
Type-safe client imports	Local relative import	Shared package or monorepo import
Best for	New projects	Existing frontends

Next Steps

React Hooks: Auth, analytics, and WebRTC hooks from @agentuity/react
Provider Setup: AgentuityProvider configuration for @agentuity/react apps
RPC Client: Build typed clients for same-origin or remote frontends
App Configuration: CORS and other app-level settings