AI Assistant

A React component for embedding the WorkTango AI Assistant in your web application.

In scope:

• Voice to text, text to voice, and text-only chat interfaces
• Single-stream back-and-forth UI between an LLM and a user, similar to popular LLM AI assistant UIs
• Standardized API for consumers to hook into the chat and provide new guidance for the session, add instructions, contextual information, and other things to make the assistant more useful, or tailored to a specific feature or user
• Standardized API for tool calls, with multiple layers of fulfillment (e.g., client fulfilled; sourceServerFulfilled; proxyServerFulfilled)
• Consistent styling across WorkTango apps
• Embeddable in any React application
• Consistent with our other React components

Out of scope (for now):

• Chat session history management
• User authentication (we provide a server-to-server proxy middleware for that; this should only work for logged-in users)
• Unauthenticated users and LLM sessions (low chance we will ever even need this)
• Anything else not explicitly mentioned in the scope section, above

Installation

npm install @worktango/ai-assistant
# or
yarn add @worktango/ai-assistant

Usage

Code generation

Our normal code generation can be used in this API, but with one caveat: this package may not use the normal GraphQL hooks when fulfilling tool calls. (You may still use hooks to do other operations, like upload metadata, chat history, etc.) Instead, use the packages/ai-assistant/src/frontend/tools/generatedSdks.ts map to access our strongly-typed SDKs.

For more information on code generation, see the GraphQL README.

In short:

1. Add the package you want to query to dependencies in this package
2. Write the appropriate query in this package's queries directory
3. Run yarn generate:gql.

Your generated code will be in packages/ai-assistant/generated.

Also note that we commit generated files, since they are path agnostic and have saved hundreds of hours of build times over the years.

React Applications

import { AiAssistant } from "@worktango/ai-assistant/react";
import "@worktango/ai-assistant/dist/ai-assistant.css";

function App() {
  return (<AiAssistant />);
}

Note: You must import the CSS file to ensure components are styled correctly. This includes components like GenAIRatingComponentApolloWrapped.

Using GenAIRatingComponentApolloWrapped

The GenAIRatingComponentApolloWrapped component allows users to rate AI-generated content (e.g., survey summaries, comments summaries). It can be used outside the AI Assistant context.

Important: You must configure the bearer token strategy before using this component. This is typically done once at your app's initialization:

import { config } from "@worktango/ai-assistant/react";
import { getAccessToken } from './your-auth-module';

// In your root component or app initialization
React.useEffect(() => {
  config.setPulseBearerTokenStrategy(() => getAccessToken() ?? '');
}, []);

Once configured, you can use the component anywhere in your app:

import { GenAIRatingComponentApolloWrapped } from "@worktango/ai-assistant/react";
import "@worktango/ai-assistant/dist/ai-assistant.css";

function MyComponent() {
  return (
    <GenAIRatingComponentApolloWrapped
      responseType="SURVEY_SUMMARY"
      responseId="123"
      genAiMessage="This is the AI-generated summary..."
      genAiMessageTimestamp="2026-01-28T12:00:00Z"
      aiResponseRating={existingRating} // Optional: existing rating data
    />
  );
}

Testing

To test whether a change might break the build when this application is deployed on another server, you can test it in this repository in the following ways:

Testing just the UI

If you just made UI changes, you can rename packages/ai-assistant/react.ts to _react.ts; and react.public.js to react.js. Then, run yarn build:all in this package. Once you do that, when you restart the development server, webpack will use the react.js file to load the component over at /admin/ai-assistant, and use the fully bundled React component to do so.

Testing locally with pulse-web

From this package, with a pulse-web checkout beside your kazoo-web one:

yarn dev:pulse-web

That points pulse-web's @worktango/ai-assistant at this working copy and then rebuilds on every change to src/. Leave it running alongside pulse-web's own dev server. The pulse-web client reloads by itself; restart the pulse-web API after a change under src/backend, because it only watches its own src.

Set PULSE_WEB_DIR if your checkout is somewhere other than ../pulse-web.

yarn link:pulse-web does the linking on its own, for when you would rather run the builds yourself, and yarn unlink:pulse-web puts the published package back.

Two things to know while linked:

• The link mirrors what npm publishes, so a new export needs to reach react.d.ts or express.d.ts before pulse-web can see its types.
• The package resolves express out of kazoo-web rather than pulse-web, so the API runs against this repo's version of it.

Features

• Unified tool call API for all WorkTango apps