Widget SDK Reference - TruGen AI Documentation

The @aiteammate/agent-widget package exposes a single React component, TrugenAgentWidget. Its full appearance and behavior are configured server-side via the agent’s widget config: the props below are what you pass at render time from your app.

Install

npm install @aiteammate/agent-widget

Import the stylesheet once (typically in your app’s root layout):

import "@aiteammate/agent-widget/styles.css";

Then render the component with your agent ID:

import { TrugenAgentWidget } from "@aiteammate/agent-widget";

export default function AgentPage() {
  return (
    <TrugenAgentWidget
      agentId="agt_12345"
      userName="Jane"
      userId="user_123"
      context="Jane opened the pricing page"
    />
  );
}

Props

Prop	Type	Required	Description
`agentId`	`string`	Yes	ID of the agent to load. Copy from the Developer Portal or from `POST /v1/ext/agent`.
`context`	`string`	No	Free-form context string appended to the agent’s system prompt for this session.
`userName`	`string`	No	Display name for the participant. Also passed to the agent so it can address the user by name.
`userId`	`string`	No	Your internal user identifier. Attaches to the resulting `conversation` record for analytics and lookup.

Requirements

React 19+: the widget declares React 19 as a peer dependency
Modern browser: Chrome 90+, Edge 90+, Firefox 88+, Safari 14+
HTTPS: camera and microphone access is only granted on HTTPS origins (or localhost in development)

What’s configured server-side

Everything about how the widget looks (colors, position, buttons, branding, allowed domains) lives on the agent’s widget config. Change it in the Studio or via the API and every embed of the widget picks up the change on the next session. Server-side settings covered on separate pages:

Widget Customization: colors, position, buttons, branding
Allowed origins: only listed domains can embed the widget and hold a conversation
System messages: welcome, idle, exit messages

Next steps

Widget Customization

Configure colors, position, buttons, and branding for the widget.

Install the widget

Full setup guide for the React widget.