Skip to main content

Getting Started

Get from zero to a working AI agent in your React app in minutes. This guide covers account setup, authentication, and embedding your first agent.

Prerequisites​

  • A React project (Vite, Next.js, or Create React App)
  • Node.js 18+
  • npm, yarn, or pnpm

Install the Distri packages:

npm install @distri/core @distri/react

Step 1: Create Your Account​

Sign up at app.distri.dev with your email. After verifying, you'll land on your dashboard.

Step 2: Create a Workspace​

Workspaces organize your agents, API keys, and usage. A personal workspace is created automatically when you sign up.

To create a team workspace:

  1. Go to Settings → Workspaces in your dashboard
  2. Click Create Workspace
  3. Note the Workspace ID — you'll need it for configuration

Step 3: Generate an API Key​

  1. Navigate to Settings → API Keys in your dashboard
  2. Click Create API Key
  3. Copy and securely store the key (it starts with dak_)
  4. This key is shown only once — save it to your backend environment variables
warning

Never expose your API key in frontend code. Always keep it on the server side.

Step 4: Create a Backend Token Endpoint​

Your frontend should never hold the API key directly. Instead, create a backend endpoint that exchanges your API key for short-lived tokens.

Node.js / Express Example​

import express from 'express';

const app = express();

app.post('/distri/token', async (req, res) => {
  const response = await fetch('https://api.distri.dev/v1/token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.DISTRI_API_KEY}`,
      'X-Workspace-Id': process.env.DISTRI_WORKSPACE_ID,
      'Content-Type': 'application/json',
    },
  });

  const { access_token, refresh_token, expires_at } = await response.json();
  res.json({ access_token, refresh_token, expires_at });
});

Generic Fetch Pattern​

async function getDistriTokens() {
  const response = await fetch('https://api.distri.dev/v1/token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.DISTRI_API_KEY}`,
      'X-Workspace-Id': process.env.DISTRI_WORKSPACE_ID,
      'Content-Type': 'application/json',
    },
  });
  return response.json();
  // Returns: { access_token, refresh_token, expires_at }
}
tip

The access_token is short-lived (30 minutes). The refresh_token lasts 90 days and can be used to get new access tokens.

Step 5: Configure React with DistriProvider​

Wrap your app with DistriProvider and pass the tokens from your backend:

import { useEffect, useState } from 'react';
import { DistriProvider } from '@distri/react';

function App() {
  const [tokens, setTokens] = useState<{
    access_token: string;
    refresh_token: string;
  } | null>(null);

  useEffect(() => {
    fetch('/distri/token', { method: 'POST' })
      .then((res) => res.json())
      .then(setTokens);
  }, []);

  if (!tokens) return <div>Loading...</div>;

  return (
    <DistriProvider
      config={{
        baseUrl: 'https://api.distri.dev',
        accessToken: tokens.access_token,
        refreshToken: tokens.refresh_token,
        workspaceId: 'your-workspace-id',
      }}
    >
      <ChatPage />
    </DistriProvider>
  );
}

DistriProvider Config Options​

PropTypeRequiredDescription
baseUrlstringYesDistri API URL (https://api.distri.dev for cloud)
accessTokenstringNoShort-lived access token from your backend
refreshTokenstringNoLong-lived refresh token for automatic renewal
workspaceIdstringNoYour workspace UUID from the dashboard
clientIdstringNoPublic client ID (alternative to accessToken)
authReadybooleanNoGate rendering until tokens are available
onTokenRefresh() => Promise<string>NoCallback to fetch a new token when the current one expires

Step 6: Load an Agent and Render Chat​

Use the useAgent hook to load your agent, then render the Chat component:

import { Chat, useAgent } from '@distri/react';

function ChatPage() {
  const { agent, loading, error } = useAgent({
    agentIdOrDef: 'your-agent-id',
  });

  if (loading) return <div>Loading agent...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!agent) return null;

  return (
    <Chat
      threadId="my-conversation"
      agent={agent}
      enableHistory
    />
  );
}

That's it! You now have a working AI agent embedded in your React app.

Alternative: Public Embed (No Backend)​

If you want a quick prototype without setting up a backend token endpoint, use the public embed approach with a clientId:

import { DistriProvider, Chat, useAgent } from '@distri/react';

function App() {
  return (
    <DistriProvider
      config={{
        baseUrl: 'https://api.distri.dev',
        clientId: 'your-public-client-id',
      }}
    >
      <PublicChat />
    </DistriProvider>
  );
}

function PublicChat() {
  const { agent } = useAgent({ agentIdOrDef: 'your-agent-id' });
  if (!agent) return <div>Loading...</div>;

  return <Chat threadId="public-thread" agent={agent} />;
}
note

Public embeds are rate-limited and require Cloudflare Turnstile validation. They're great for demos and prototypes but not recommended for production. Create a public client from Settings → Public Clients in your dashboard.

Handling Token Expiry​

Access tokens expire after 30 minutes. Use the onTokenRefresh callback to automatically fetch new tokens:

<DistriProvider
  config={{
    baseUrl: 'https://api.distri.dev',
    accessToken: tokens.access_token,
    refreshToken: tokens.refresh_token,
    workspaceId: 'your-workspace-id',
    onTokenRefresh: async () => {
      const res = await fetch('/distri/token', { method: 'POST' });
      const { access_token } = await res.json();
      return access_token;
    },
  }}
>
  <App />
</DistriProvider>

Next Steps​

Agent DefinitionLearn to write agent markdown filesIn-Product ToolsConnect your app's functions as agent toolsSessionsStore state across agent interactionsUsage TrackingMonitor token consumption and manage limits