TruGen PlayBook

Overview

This guide walks through the trugen-examples/sdk/react-agent-ui example and shows exactly how it embeds TruGen Agent UI in a React app.

The example uses @trugen/agent-ui with a connect screen for apiKey and agentId, then renders the agent interface after the user clicks Connect.

What you'll build

A setup where:

A React app connects to a TruGen agent using API Key and Agent ID
The app renders the hosted TruGen Agent UI for live conversation

Prerequisites

Node.js 18 or later
TruGen API Key
TruGen Agent ID
React 19 or later in your project

Project setup

1. Clone and open the example

git clone https://github.com/trugenai/trugen-examples.git
cd trugen-examples/sdk/react-agent-ui

2. Install node package

npm install
npm run dev

3. Install dependencies

npm install @trugen/agent-ui
# or
yarn add @trugen/agent-ui
# or
pnpm add @trugen/agent-ui

This example declares:

@trugen/agent-ui
react

4. Run the app

Open: http://localhost:3001

On the connect screen:

Enter API Key
Enter Agent ID
Click Connect

Import component and its styles

import { TrugenAgentProvider, TrugenAgent } from "@trugen/agent-ui";
import "@trugen/agent-ui/dist/index.css";

The CSS import is required — it includes the component's layout and theme styles.

API Reference

TrugenAgentProvider: wraps child agent components.
- children (React.ReactNode, required)
TrugenAgent: main agent UI component.
- agentId (string, required)
- apiKey (string, required)
- context (string, optional)

Let you provide credentials

If you want to enter own API Key and Agent ID (as this example does), manage them as state and pass them to TrugenAgent once both are provided:

import { useState } from "react";
import { TrugenAgentProvider, TrugenAgent } from "@trugen/agent-ui";
import "@trugen/agent-ui/dist/index.css";

export default function App() {
  const [apiKey, setApiKey] = useState("");
  const [agentId, setAgentId] = useState("");
  const [connected, setConnected] = useState(false);

  if (!connected) {
    return (
      <div>
        <input
          type="password"
          placeholder="API Key"
          value={apiKey}
          onChange={(e) => setApiKey(e.target.value)}
        />
        <input
          type="text"
          placeholder="Agent ID"
          value={agentId}
          onChange={(e) => setAgentId(e.target.value)}
        />
        <button
          disabled={!apiKey || !agentId}
          onClick={() => setConnected(true)}
        >
          Connect
        </button>
      </div>
    );
  }

  return (
    <TrugenAgentProvider>
      <div style={{ height: "100vh", width: "100vw" }}>
        <TrugenAgent apiKey={apiKey} agentId={agentId} />
      </div>
    </TrugenAgentProvider>
  );
}

Notes

@trugen/agent-ui requires React 19 or later.
Client-side rendering only (not SSR / not React Server Components).
npm v7+ installs peer deps automatically; npm v6 requires manual react and react-dom install.

Result

A React app displays a credentials gate first
After connect, TruGen Agent UI loads with the provided credentials