React UI Managed Agent

Overview

This recipe shows how to embed a TruGen managed agent inside a React UI using an iframe. The managed agent itself is created and configured in TruGen; your React app is responsible for:

• Rendering the agent in your layout.
• Passing user and session context.
• Handling navigation and surrounding UI.

The complete example code lives at managed-agents/agent-with-reactui in the trugen-examples repository.

What you’ll build

A React + TypeScript app where:

• The main page renders a TruGen managed agent inside a panel.
• You can pass basic user/session info to the agent.
• The layout is styled with standard React/HTML (and optionally Tailwind or CSS modules).

This pattern is ideal when you already have a React frontend and want to drop in a TruGen agent without rewriting your app structure.

Prerequisites

• Node.js 18+ and npm.
• A TruGen account with at least one managed agent configured.
• Basic familiarity with React and JSX.

Project setup

1. Clone and install

Clone the examples repo and open the React UI managed agent folder:

git clone https://github.com/trugenai/trugen-examples.git
cd trugen-examples/managed-agents/agent-with-reactui

Install dependencies and start the dev server:

npm install
npm run dev

By default this runs the app on http://localhost:3000 (or similar, depending on the example).

2. Configure environment variables

In the root of the example, create a .env.local (or .env) file and add the TruGen‑specific values you need, for example:

TRUGEN_AGENT_ID=your_managed_agent_id
TRUGEN_API_KEY=your_api_key_if_required
TRUGEN_BASE_URL=https://your-trugen-endpoint

Check the example README in managed-agents/agent-with-reactui for the exact variable names expected by that project.

Understanding the React structure

The React example is typically split into:

• A page or root component that sets up layout.
• A dedicated AgentPanel (or similar) component that wraps the iframe.

A minimal pattern looks like:

// AgentPanel.tsx
import React from "react";

type AgentPanelProps = {
  userId?: string;
};

export function AgentPanel({ userId }: AgentPanelProps) {
  const url = new URL(process.env.NEXT_PUBLIC_TRUGEN_AGENT_URL as string);
  if (userId) {
    url.searchParams.set("userId", userId);
  }

  return (
    <div className="h-full w-full rounded-xl border bg-black/5">
      <iframe
        src={url.toString()}
        title="TruGen Managed Agent"
        className="h-full w-full rounded-xl border-0"
        allow="microphone; camera"
      />
    </div>
  );
}

Your actual example may use different prop names, but the structure is similar:

1. Build the agent URL from configuration and environment variables.
2. Render it in an <iframe> that fills its container.

Then, in your page:

// App.tsx or page.tsx
import { AgentPanel } from "./AgentPanel";

export default function App() {
  const userId = "demo-user-123"; // Replace with your auth / user data

  return (
    <main className="min-h-screen bg-slate-950 text-slate-50">
      <div className="mx-auto flex max-w-5xl flex-col gap-6 px-4 py-10">
        <header className="space-y-2">
          <h1 className="text-3xl font-semibold tracking-tight">
            React UI Managed Agent
          </h1>
          <p className="text-sm text-slate-400">
            Embed a TruGen managed agent inside your existing React app using an iframe.
          </p>
        </header>

        <section className="h-[480px]">
          <AgentPanel userId={userId} />
        </section>
      </div>
    </main>
  );
}

Passing user and session context

You can pass context to the agent via:

• Query parameters on the URL.
• PostMessage or similar channel if the agent supports it.

The simplest approach is to add query parameters:

url.searchParams.set("userId", userId);
url.searchParams.set("plan", "pro");
url.searchParams.set("source", "dashboard");

The managed agent can then read these values and adjust its behaviour (for example, different greeting or feature set based on plan).

If the TruGen embed supports a richer postMessage protocol, you can also wire a message event listener in the React app to exchange events between the parent window and the iframe.

Styling and layout

Because the agent is inside an iframe, you control only:

• The size and placement of the iframe.
• The surrounding UI (headings, buttons, sidebars).

Common patterns:

• A full‑height panel in a dashboard layout.
• A split view with the agent on the right and your app on the left.
• A modal or drawer containing the agent.

Use your usual React styling approach (Tailwind, CSS modules, styled‑components, etc.) to integrate the agent cleanly into your UI.

Where to go from here

• Swap environment variables to point to different managed agents for different parts of your app.
• Add authentication and build the userId from your auth system.
• Track analytics when the iframe loads or when users interact with UI around the agent.
• Explore other examples in the trugen-examples repo for more advanced integrations.