Agent Integration

Embed, call, or drive your agent from your own applications.

Once an agent is built, you can wire it into your own product in three ways — embed a prebuilt chat widget, call the REST API, or drive it with the JavaScript SDK. This page walks through all three, along with the credentials and domain rules they share. Find them under Manage Agent → Agent Integration.

The three Integrate Agent options — Embed, API, and Headless — sit in the lower row of the screen.

This agent uses SDK Version 1.181.0 and Executor Version 1.3. Use these versions in your app and API calls for compatibility.

Choosing an integration

Start by matching the integration to where your agent runs and how much of the interface you want to own. The table below maps each option to its runtime; the sections that follow document each one in full.

If you want to…	Use	Runtime
Drop a chat onto a web page with no UI to build	Embed widget	Browser (prebuilt UI)
Call the agent from a backend, service, or scheduled job	REST API	Server-to-server (no browser)
Build your own custom chat UI in the browser	JS SDK	Browser (your UI)

Shared prerequisites. All three connect using credentials and domain rules configured on the agent:

Requirement	Where	Applies to
Widget Key	Agent Config Panel → Authentication	Embed, JS SDK (and optionally the API)
API Key + Secret	Agent Config Panel → Authentication	REST API (server-to-server)
Whitelisted domain	Agent Config Panel → Whitelisted Domains	Embed, JS SDK — add the full URL or hostname, no trailing spaces

To obtain a Widget Key: open your agent's Agent Config Panel → Authentication tab, then create and copy the key. To whitelist a domain: open Agent Config Panel → Whitelisted Domains, then add and save your domain.

Set up Authentication first. Then add your allowed hosts in Whitelisted Domains.

Wherever you supply a user object, it must represent a trusted, authenticated identity from your own auth system — the user currently logged into your application and verified by your auth system. Never populate it from query parameters or untrusted input, which can be manipulated.

Embedding

Embedding is the quickest path — a prebuilt chat UI you drop onto a page, with no interface to build yourself.

The Embed Agent widget is a drop-in chat interface backed by @uptiqai/widgets-sdk. It comes as React components or a framework-agnostic HTML web component, and each offers a compact Chat Widget (floating popover) or an immersive Full Screen layout with sidebar navigation. The widget handles conversation state, history, and messaging for you.

Install

npm install @uptiqai/[email protected]
# or
pnpm add @uptiqai/[email protected]

Import the stylesheet once in your application entry point:

import '@uptiqai/widgets-sdk/dist/style.css';

Chat Widget vs. Full Screen — both share the same config, user, theme, instanceId, and ref API. Full Screen adds a hideTrigger / hide-trigger option to hide the default launcher and open via your own button. Expand the variant you need:

React — Chat Widget (popover)

import { ChatWidget } from '@uptiqai/widgets-sdk';
import type { ChatWidgetRef } from '@uptiqai/widgets-sdk';
import '@uptiqai/widgets-sdk/dist/style.css';
import { useRef } from 'react';

function App() {
  const currentUser = useAuth(); // your auth hook
  return (
    <ChatWidget
      config={{
        serverUrl: 'https://api-builder-dev.uptiq.dev',
        agentId: '<agent-id>',
        widgetKey: '<your-widget-key>',
        agentExecutorVersion: '1.3',
      }}
      user={{
        uid: currentUser.id,
        firstName: currentUser.firstName,
        lastName: currentUser.lastName,
        email: currentUser.email,
      }}
    />
  );
}

React — Full Screen

Use FullScreenChatWidget / FullScreenChatWidgetRef. Add hideTrigger when driving visibility from your own button:

import { FullScreenChatWidget } from '@uptiqai/widgets-sdk';
import type { FullScreenChatWidgetRef } from '@uptiqai/widgets-sdk';
import '@uptiqai/widgets-sdk/dist/style.css';
import { useRef } from 'react';

function App() {
  const widgetRef = useRef<FullScreenChatWidgetRef>(null);
  const currentUser = useAuth();
  return (
    <FullScreenChatWidget
      config={{
        serverUrl: 'https://api-builder-dev.uptiq.dev',
        agentId: '<agent-id>',
        widgetKey: '<your-widget-key>',
        agentExecutorVersion: '1.3',
      }}
      user={{
        uid: currentUser.id,
        firstName: currentUser.firstName,
        lastName: currentUser.lastName,
        email: currentUser.email,
      }}
      hideTrigger={true}
      widgetRef={widgetRef}
    />
  );
}

HTML — Chat Widget (popover)

Add the widget script to your page <head>, then use the custom element:

<uptiq-chat-widget
  id="chat-widget"
  config='{
    "serverUrl": "https://api-builder-dev.uptiq.dev",
    "agentId": "<agent-id>",
    "widgetKey": "<your-widget-key>",
    "agentExecutorVersion": "1.3"
  }'
  user='{
    "uid": "auth0|<user-id>",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]"
  }'
></uptiq-chat-widget>

HTML — Full Screen

Use <uptiq-full-screen-chat-widget> and add hide-trigger="true" to hide the default launcher:

<uptiq-full-screen-chat-widget
  id="chat-widget"
  hide-trigger="true"
  config='{
    "serverUrl": "https://api-builder-dev.uptiq.dev",
    "agentId": "<agent-id>",
    "widgetKey": "<your-widget-key>",
    "agentExecutorVersion": "1.3"
  }'
  user='{
    "uid": "auth0|<user-id>",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]"
  }'
></uptiq-full-screen-chat-widget>

Props / attributes reference

React uses props (objects); the HTML web component uses attributes (JSON-stringified objects, kebab-case names). Otherwise they map 1:1.

React prop	HTML attribute	Required	Type	Description
config	config	Yes	WidgetConfig	Backend/agent config — see below.
user	user	Yes	WidgetUser	Authenticated user — see below.
instanceId	instance-id	No	string	Unique ID when rendering multiple widgets on one page. Default: auto-generated.
theme	theme	No	WidgetTheme	Palette overrides — see Theme customization.
defaultExecutionId	default-execution-id	No	string	Start with a specific conversation/execution loaded (continue a previous chat).
onExecutionChange	—	No	(executionId?) => void	Fires when the current conversation changes.
defaultOpen	default-open	No	boolean	Open on mount. Default false.
hideTrigger	hide-trigger	No	boolean	(Full Screen) Hide the default launcher; open via your own button + ref. Default false.
onClose	—	No	() => void	Fires when the user closes the widget.
widgetRef	—	No	React.Ref<…Ref>	Programmatic open() / close() control.

config (required) — WidgetConfig:

{
  serverUrl: 'https://api-builder-dev.uptiq.dev', // don't change this
  agentId: '<agent-id>',                          // don't change this
  widgetKey: string,          // from Agent Config -> Authentication
  agentExecutorVersion?: string, // Executor version from agent config (optional)
}

user (required) — WidgetUser:

{
  uid: string;        // Unique identifier for the user in your system
  firstName: string;  // User's first name
  lastName?: string;  // User's last name (optional)
  email: string;      // User's email address
}

Security: populate user from your authenticated session — e.g. const currentUser = useAuth(); — never from query params, form input, or other untrusted sources.

widgetRef — programmatic open/close control

// React.Ref<ChatWidgetRef> | React.Ref<FullScreenChatWidgetRef>
{
  open: () => void;   // Opens the widget
  close: () => void;  // Closes the widget
}

const widgetRef = useRef<FullScreenChatWidgetRef>(null);

const handleOpenChat = () => widgetRef.current?.open();
const handleCloseChat = () => widgetRef.current?.close();

Theme customization

Pass a theme (React object / HTML JSON string) to match your design system:

theme={{
  palette: {
    primary: '#3b82f6',
    primaryForeground: '#ffffff',
    background: '#ffffff',
    foreground: '#0f172a',
    border: '#e2e8f0',
    success: '#10b981',
    destructive: '#ef4444',
  },
}}

Full palette reference (WidgetTheme)

{
  palette?: {
    // Primary shades
    primary00?; primary100?; primary200?; primary300?; primary400?; primary500?;
    // Secondary shades
    secondary300?; secondary500?; secondary700?;
    // Background shades (00 lightest → 900 darkest)
    background00?; background100?; background200?; background300?; background800?; background900?;
    // Foreground / text
    foreground00?; foreground200?; foreground600?; foreground800?; foreground900?;
    // Borders
    border100?; border200?; border300?; border400?;
    // Semantic
    primary?; primaryForeground?;
    secondary?; secondaryForeground?;
    background?; foreground?;
    border?; input?;
    success?; successForeground?;
    warning?; warningForeground?;
    destructive?; destructiveForeground?;
    sidebar?; sidebarForeground?;
    ring?;
    // all values are string (optional)
  }
}

Examples

Example 1 — Basic implementation

import { FullScreenChatWidget } from '@uptiqai/widgets-sdk';
import '@uptiqai/widgets-sdk/dist/style.css';

function App() {
  const currentUser = useAuth();
  return (
    <div>
      <h1>My Application</h1>
      <FullScreenChatWidget
        config={{ serverUrl: 'https://api-builder-dev.uptiq.dev', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.3' }}
        user={{ uid: currentUser.id, firstName: currentUser.firstName, lastName: currentUser.lastName, email: currentUser.email }}
      />
    </div>
  );
}

Example 2 — Custom trigger with ref control

import { FullScreenChatWidget } from '@uptiqai/widgets-sdk';
import type { FullScreenChatWidgetRef } from '@uptiqai/widgets-sdk';
import '@uptiqai/widgets-sdk/dist/style.css';
import { useRef } from 'react';

function App() {
  const widgetRef = useRef<FullScreenChatWidgetRef>(null);
  const currentUser = useAuth();
  return (
    <div>
      <button onClick={() => widgetRef.current?.open()}>💬 Chat with AI Assistant</button>
      <FullScreenChatWidget
        config={{ serverUrl: 'https://api-builder-dev.uptiq.dev', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.3' }}
        user={{ uid: currentUser.id, firstName: currentUser.firstName, lastName: currentUser.lastName, email: currentUser.email }}
        hideTrigger={true}
        widgetRef={widgetRef}
      />
    </div>
  );
}

For the popover ChatWidget, the same pattern applies with both open and close buttons (widgetRef.current?.open() / .close()).

Example 3 — Theme customization

const customTheme = {
  palette: {
    primary: '#6366f1', primaryForeground: '#ffffff',
    background: '#f8fafc', foreground: '#1e293b', border: '#cbd5e1',
    sidebar: '#ffffff', sidebarForeground: '#475569',
    success: '#22c55e', warning: '#f59e0b', destructive: '#ef4444',
  },
};

<FullScreenChatWidget config={/* … */} user={/* … */} theme={customTheme} />

Example 4 — Tracking conversations

import { useState } from 'react';

function App() {
  const currentUser = useAuth();
  const [currentExecutionId, setCurrentExecutionId] = useState<string>();

  const handleExecutionChange = (executionId?: string) => {
    setCurrentExecutionId(executionId);
    if (executionId) localStorage.setItem('lastExecutionId', executionId);
    analytics.track('conversation_changed', { executionId });
  };

  const lastExecutionId = localStorage.getItem('lastExecutionId') || undefined;

  return (
    <FullScreenChatWidget
      config={{ serverUrl: 'https://api-builder-dev.uptiq.dev', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.3' }}
      user={{ uid: currentUser.id, firstName: currentUser.firstName, lastName: currentUser.lastName, email: currentUser.email }}
      defaultExecutionId={lastExecutionId}
      onExecutionChange={handleExecutionChange}
      onClose={() => console.log('Widget closed with execution:', currentExecutionId)}
    />
  );
}

Example 5 — Multiple widgets on the same page

Give each widget a distinct instanceId (React) / instance-id (HTML):

<FullScreenChatWidget instanceId="sales-agent" config={{ /* sales agentId + widgetKey */ }} user={/* … */} />
<FullScreenChatWidget instanceId="support-agent" config={{ /* support agentId + widgetKey */ }} user={/* … */} />

Features

• Chat interface (floating popover or full-screen) with responsive design

• Conversation sidebar for managing multiple chats

• New chat creation for starting fresh conversations

• Message history persistence across sessions

• Real-time messaging with the AI agent

• Agent avatar display in the trigger button

• Customizable theming to match your brand

• TypeScript support with full type definitions

Browser support

All modern browsers: Chrome/Edge (latest), Firefox (latest), Safari (latest), and mobile browsers (iOS Safari, Chrome Mobile).

Troubleshooting

• Widget not appearing — ensure you imported the CSS (import '@uptiqai/widgets-sdk/dist/style.css';), that both required props (config and user) are provided, and that your Widget Key is correct and active.

• "Unauthorized" errors — confirm your application's domain is whitelisted exactly (full URL with protocol or hostname only, no trailing spaces).

REST API & JS SDK

When you'd rather drive the agent from your own code than a prebuilt UI, reach for one of these two. The REST API runs server-to-server with no browser; the JS SDK runs in the browser so you can build a fully custom chat interface. Pick a tab:

REST API

REST API

The Headless Agent Trigger API invokes an agent over HTTP — no UI or browser. Use it for backend services, scheduled jobs, or any workflow that starts the agent from your own systems.

• Base URL: https://api-builder-dev.uptiq.dev · Format: JSON

Authentication

Every request must include exactly one of the following header sets.

Option 1 — API Key + Secret (server-to-server)

Best for backend and service-to-service integrations.

x-api-key: YOUR_AGENT_API_KEY
x-api-key-secret: YOUR_AGENT_API_KEY_SECRET
Content-Type: application/json

Create and copy both from Agent Config Panel → Authentication.

Option 2 — Widget Key

Best for first-party platform integrations.

x-widget-key: YOUR_AGENT_WIDGET_KEY
Content-Type: application/json

Create and copy it from Agent Config Panel → Authentication.

Trigger an agent

POST /agent-executor/1.3/agents/:agentId/trigger

Starts a new agent execution or resumes a paused one.

Path parameters

Name	Type	Required	Description
agentId	string	Yes	The unique identifier of the agent to run.

Request body — provide either message or resumeData; all other fields are optional.

Field	Type	Description
message	string	The instruction sent to the agent. Required for new executions.
payload	object	Structured data sent alongside message for programmatic inputs.
documents	array	File attachments. See Document handling.
executionId	string	Specific execution ID. Auto-generated if omitted.
executionMode	string	async (default) or sync. Use sync only when you need an immediate response.
responseFormat	string	Markdown (default) or Json.
webhooks	array	Webhook URLs to receive execution updates. See Webhooks.

curl -X POST "https://api-builder-dev.uptiq.dev/agent-executor/1.3/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the latest sales report"}'

Success response: { "executionId": "exec_123" }

Document handling

Attaching documents is a two-step process: upload the file, then reference it in the trigger request.

Step 1 — Get a signed upload URL

POST /agent-executor/1.3/agents/:agentId/uploads/signed-urls

curl -X POST "https://api-builder-dev.uptiq.dev/agent-executor/1.3/agents/:agentId/uploads/signed-urls" \
  -H "x-widget-key: YOUR_AGENT_WIDGET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 1 }'

Field	Type	Required	Description
count	number	No	Number of signed URLs to generate. Default 1.
executionId	string	No	Execution ID to associate the upload with.

Response:

{
  "message": "Signed URL generated successfully.",
  "data": [
    { "id": "document-id", "url": "https://storage.googleapis.com/.../uploads/...", "agentId": "agent-id" }
  ]
}

PUT your file to the returned url, then use the id when triggering the agent.

The previous endpoint POST /agent-executor/1.3/agents/:agentId/documents/presigned-url is deprecated and will be removed — migrate to uploads/signed-urls.

Step 2 — Attach the document to the trigger request

curl -X POST "https://api-builder-dev.uptiq.dev/agent-executor/1.3/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze financial risk",
    "documents": [
      { "id": "<document-id>", "fileName": "balance-sheet.pdf", "mimeType": "application/pdf" }
    ]
  }'

Field	Type	Description
id	string	Document ID returned from the upload endpoint.
signedUrl	string	Alternative to id — the signed URL of the uploaded file.
fileName	string	Original filename. Recommended for better agent context.
mimeType	string	MIME type of the file. Recommended for better agent context.

Webhooks

Webhooks are available on Agent Executor Version 1.2 and onwards.

Register webhooks in the trigger request to receive real-time updates when an execution completes or needs input:

{
  "webhooks": [
    { "url": "https://your-service.com/webhook", "metadata": "optional-context-id" }
  ]
}

Your endpoint receives:

{
  "executionId": "exec_123",
  "success": true,
  "result": { "message": "Agent response..." },
  "error": null,
  "metadata": "optional-context-id"
}

Verify the webhook signature

Each webhook includes an X-Webhook-Signature header — a hex-encoded RSA-SHA256 signature of the raw JSON body. Verify it against the platform's public key (available on the agent's API Integration screen):

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHex, publicKey) {
  const signature = Buffer.from(signatureHex, 'hex');
  return crypto.verify('RSA-SHA256', Buffer.from(rawBody), publicKey, signature);
}

Common examples

Send structured data with a message

curl -X POST "https://api-builder-dev.uptiq.dev/agent-executor/1.3/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Generate quarterly report", "payload": { "quarter": "Q4", "year": 2024 } }'

Resume a paused execution

curl -X POST "https://api-builder-dev.uptiq.dev/agent-executor/1.3/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "executionId": "exec_123", "resumeData": { "lastStep": "analysis" } }'

Pin a specific reasoning model (advanced)

By default the platform picks the reasoning model. To override:

{ "message": "Analyze this contract", "agentStrategy": { "reasoningModelId": "your-model-id" } }

Error responses

Status	Meaning	Example
400	Invalid request	{ "error": "Message or resume data is required" }
401	Bad credentials	{ "error": "Invalid or missing agent API key" }
403	Forbidden	{ "message": "You're not authorized to perform this action." }
500	Server error	{ "message": "Something went wrong. Please try again later." }

Executions default to async — use sync only when you must block on the result. The trigger endpoint is not idempotent: each call starts a new execution unless you pass an existing executionId.

JS SDK

JS SDK

The Headless Agent JS SDK lets you build a custom chat interface while it handles the socket connection, real-time agent events, and file uploads automatically. Runs in the browser (React, Vue, or vanilla JS). Entry point: createHeadlessAgentInstance(params), which returns an instance with emit(), on(), and cleanup() methods.

Install & import

npm install @uptiqai/[email protected]

import { createHeadlessAgentInstance } from '@uptiqai/widgets-sdk';
// TypeScript projects also import the types:
import type { HeadlessAgentInstance, AgentInterruptEvent } from '@uptiqai/widgets-sdk';

Authentication uses the Widget Key; your application's domain must be whitelisted (see Shared prerequisites above).

Create an instance

const instance = createHeadlessAgentInstance({
  config: { serverUrl: 'https://api-builder-dev.uptiq.dev', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.3' },
  user: { uid: 'user-123', firstName: 'Jane', lastName: 'User', email: '[email protected]' },
  instanceId: 'my-chat-instance',
});

Parameter	Type	Required	Description
config	WidgetConfig	Yes	serverUrl, agentId, widgetKey, optional agentExecutorVersion.
user	WidgetUser	Yes	uid, firstName, email (required); lastName (optional).
instanceId	string	Yes	Unique identifier used for socket scoping.

Instance API

Method	Signature	Description
emit	(event: 'query', payload: QueryPayload) => void	Send a query to the agent, optionally with file attachments.
on	(event: 'agent-interrupt', handler) => () => void	Subscribe to agent events. Returns an unsubscribe function.
cleanup	() => void	Remove listeners and disconnect the socket (call on unmount).

Sending messages — emit('query', payload)

Property	Type	Required	Description
content	string	Yes	The user's message text (use ' ' when sending only files).
executionId	string	No	Existing execution ID to continue a conversation.
files	File[]	No	Browser File objects to upload and attach.

The SDK obtains presigned upload URLs, uploads each file to cloud storage, and attaches the metadata to the message automatically — just pass the File objects.

// New conversation
instance.emit('query', { content: 'Hello, can you help me?' });

// With attachments
instance.emit('query', { content: 'Analyze these documents', files: [file1, file2] });

// Continue an existing conversation
instance.emit('query', { content: 'Tell me more', executionId: 'existing-execution-uuid' });

// Files only (no text)
instance.emit('query', { content: ' ', files: [selectedFile] });

Receiving events — on('agent-interrupt', handler)

The handler receives an AgentInterruptEvent; branch on its type:

Event type	Description	Key fields
agent_message	Agent text response	content, subtype
status_update	Progress indicator	status
done	Execution completed	content (optional)
error	Error occurred	error
tool_call	Agent is calling a tool	tool details
tool_result	Tool call completed	tool result
plan_update	Agent created/updated a plan	plan details

agent_message events carry a subtype: intermediate (streaming), final (complete), question (needs user response), final_stream, output_files, ask_permission.

Don't filter only by subtype === 'final' or you'll miss agent questions and streamed replies — handle final, question, and final_stream at minimum.

const unsubscribe = instance.on('agent-interrupt', event => {
  switch (event.type) {
    case 'agent_message':
      if (['final', 'question', 'final_stream'].includes(event.subtype) && event.content) {
        displayMessage({ role: 'agent', content: event.content });
      }
      break;
    case 'error':
      displayMessage({ role: 'system', content: event.error ?? 'An error occurred' });
      break;
    case 'status_update':
    case 'done':
    case 'tool_call':
    case 'tool_result':
    case 'plan_update':
      // optional UI handling
      break;
    default:
      console.log('Unknown event type:', event.type);
  }
});

Cleanup

Always call cleanup() (and the unsubscribe function) when you're done — e.g. on component unmount:

unsubscribe();
instance.cleanup();

React integration example

import { createHeadlessAgentInstance } from '@uptiqai/widgets-sdk';
import type { HeadlessAgentInstance, AgentInterruptEvent } from '@uptiqai/widgets-sdk';
import { useEffect, useRef, useState } from 'react';

const config = { serverUrl: 'https://api-builder-dev.uptiq.dev', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.3' };
const user = { uid: 'user-123', firstName: 'Jane', lastName: 'User', email: '[email protected]' };

export const ChatComponent = () => {
  const [messages, setMessages] = useState<Array<{ role: 'user' | 'agent'; content: string }>>([]);
  const instanceRef = useRef<HeadlessAgentInstance | null>(null);

  useEffect(() => {
    const instance = createHeadlessAgentInstance({ config, user, instanceId: 'my-chat-instance' });
    instanceRef.current = instance;

    const unsubscribe = instance.on('agent-interrupt', (event: AgentInterruptEvent) => {
      if (event.type === 'agent_message'
          && ['final', 'question', 'final_stream'].includes(event.subtype ?? '')
          && event.content) {
        setMessages(prev => [...prev, { role: 'agent', content: event.content! }]);
      }
    });

    return () => { unsubscribe(); instance.cleanup(); };
  }, []);

  const sendMessage = (text: string, files?: File[]) => {
    setMessages(prev => [...prev, { role: 'user', content: text }]);
    instanceRef.current?.emit('query', { content: text, files });
  };

  return <div>{messages.map((m, i) => <div key={i}>{m.role}: {m.content}</div>)}</div>;
};

TypeScript types

import type {
  HeadlessAgentInstance,
  QueryPayload,
  AgentInterruptEvent,
  CreateHeadlessAgentInstanceParams,
} from '@uptiqai/widgets-sdk';

type HeadlessAgentInstance = {
  emit: (event: 'query', payload: QueryPayload) => void;
  on: (event: 'agent-interrupt', handler: (event: AgentInterruptEvent) => void) => () => void;
  cleanup: () => void;
};

type QueryPayload = { content: string; executionId?: string; files?: File[] };

Best practices

• Single instance — create one instance per chat context and reuse it for the whole conversation.

• Subscribe before sending — attach your on('agent-interrupt', …) handler before the first emit so no responses are missed.

• Handle multiple subtypes — capture final, question, and final_stream, not just final.

• Always clean up — call cleanup() on unmount to prevent memory leaks.

• Persist executionId — store and pass it to continue a conversation across page reloads.

• Let the SDK handle uploads — pass File objects; presigned-URL upload is automatic.

The SDK manages socket connections and reconnection automatically, and shares the socket across instances that use the same user and config. For server-side or backend-only execution with no browser, use the REST API tab instead.

How this relates to the agent's other settings

Whichever integration you choose, a few other settings shape how it behaves:

• Authentication — the keys generated there are the credentials your embed widget, JS SDK, or API integration uses.

• Whitelisted Domains — for the embed widget and JS SDK, the agent only runs on domains in this list.

• Secrets & Variables — the credentials and values the agent uses at runtime; the widget, SDK, and API all invoke the agent against these same configured secrets.

Tighten these before you publish embeds or share API credentials — once a widget is live on a page, every visitor reaches the agent through whatever auth and domain rules you have set.

To export the agent's full configuration as a portable package instead of running it live, see Export Agent.