Widget

Overview

Widgets in UPTIQ AI Workbench are modular UI components that enhance the functionality of AI agents by embedding custom interactive elements. They allow developers to create custom interfaces that integrate seamlessly within agent workflows, enabling enhanced interactivity, data visualization, and workflow automation.

What is a Widget?

A widget in UPTIQ AI Workbench is a reusable web component that extends the capabilities of AI agents. It can be a simple UI element like a button or a complex component that interacts with backend workflows, listens to events, and processes user input.

How Widgets Work in UPTIQ AI Workbench

1. Creation: Developers create widgets using React, Tailwind CSS, and Shadcn UI.

2. Exporting: Widgets are converted into web components using @r2wc/react-to-web-component.

3. Hosting: Built widget bundles are hosted and linked in the agent configuration.

4. Integration: The widget is embedded within the agent’s UI and interacts with workflows.

5. Event Listening & Execution: Widgets can listen to custom events and trigger workflows accordingly.

How to add a custom widget?

Important Note

It is mandatory to use only the following libraries/packages to develop a component:

• React - https://react.dev

• Shadcn UI - https://ui.shadcn.com/docs

• Tailwind CSS - https://tailwindcss.com/

• @r2wc/react-to-web-component - for converting React components to web components - https://www.npmjs.com/package/@r2wc/react-to-web-component

Prerequisites

• Node.js and Yarn installed

• Basic knowledge of React and web components

• Access to the UPTIQ AI Workbench

Step 1: Set Up the Custom Widget Project

1. Download the starter project from custom-widget-starter https://drive.google.com/drive/folders/14JVnBlhEijOan1AxGA6IhjicsBMjSi8d
2. Install dependencies

yarn

1. The entry point for widgets is src/index.ts. This file exports all widgets as web components.

Step 2: Create a New Widget

1. Create a new file: src/widgets/secondWidget/SecondWidget.tsx.

2. Add a React component:

export const SecondWidget = () => {
  return (
    <div>
      // Your component code goes here.
    </div>
  );
};

1. Create an index.ts inside src/widgets/secondWidget/ for better organization:

export { SecondWidget } from "./SecondWidget";

1. Update src/index.ts to register the new widget:

import { SecondWidget } from "./widgets/secondWidget";

const widgets = [
  { tag: "first-widget", component: FirstWidget },
  { tag: "second-widget", component: SecondWidget },
];

widgets.forEach(registerWidgetAsWebComponent);

Step 3: Build and Deploy the Widget

1. Build the project:

   yarn build

2. Host the dist/ folder bundle in the cloud.

3. Use dist/index.js in the AI Workbench as a script:

<script src="<hosted-base-url>/index.js" type="module"></script>
<second-widget></second-widget>

Step 4: Configure Custom Widget in UPTIQ AI Workbench

1. Navigate to the Widgets tab in the AI Agent config page.

2. Click on Add Custom Widget.

3. Fill in the required details:

   • Name: Widget name

   • Description: Short description

   • Events: Custom events for workflow interactions

   • HTML Content: Include the script to load the widget

4. Click Save.

5. Approve the widget and toggle it on for use.

Step 5: Handling Events in Custom Widgets

• Use useSamuelEventListener to listen for custom events:

const handleEvent = useCallback((eventData: any) => {
  console.log(eventData);
});

useSamuelEventListenr("test-event", handleEvent);

Step 6: Running Workflows from a Widget

Call the workflow execution API:

const handleRunWorkflow = async (taskInputs: any) => {
  const executionId = uuid();
  const { uid } = getSamuelUser();
  const { appId, serverUrl, widgetKey } = getSamuelConfig();
  
  const workflowId = taskInputs?.workflowId;
  if (!workflowId) throw new Error("workflowId is required");
  
  const response = await axios.post(
    `${serverUrl}/workflow-defs/run-sync`,
    { executionId, uid, integrationId: workflowId, appId, taskInputs },
    { headers: { widgetKey, appid: appId } }
  );
  console.log(response.data);
};

Step 7: Testing Widgets Locally

1. Update src/development/constants.ts with test values.

2. Modify index.html to include the widget:

<script type="module" src="/src/index.ts"></script>
<div style="width: 400px">
  <second-widget></second-widget>
</div>

1. Start the local development server:

yarn dev

Conclusion

Following these steps, developers can create, configure, and integrate custom widgets into the UPTIQ AI Workbench to enhance AI agent capabilities.

Widgets in UPTIQ Workbench dynamically update based on events triggered within workflows. The Emit Event Node plays a crucial role in this interaction by allowing workflows to send real-time updates to UI components.

✅ Why It Matters?

• The Emit Event Node ensures that widgets always display the latest data without manual refresh.

• Events like Refresh Documents, Refresh Client Summary, and Open Document Uploader allow seamless updates to respective widgets.

• Developers can integrate workflows with widgets by triggering the appropriate Emit Event, ensuring a responsive and interactive user experience.

Want to learn more? Check the Emit Event Node documentation for a full list of supported events and how to configure them in your workflow. 🚀