Embed Spotter Agent

Embed Spotter Agent

Spotter Agent is an embeddable AI analyst component from ThoughtSpot that enables you to integrate natural language data search and analysis into your own applications. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, Spotter Agent is designed for deeper integration and customization. It allows you to build your own UI or agent experience, broker user questions to ThoughtSpot, and receive structured answers and visualizations, giving you full control over the look, feel, and workflow of the embedded analytics experience.

How is Spotter Agent Embedding Different from Spotter Embed?🔗

  • Spotter embed provides a pre-built search bar and interface for quick embedding.

  • Spotter Agent embedding is intended for custom agent or chatbot experiences, letting you control the UI and workflow while leveraging ThoughtSpot’s AI-powered analytics engine.

Prerequisites🔗

  • Access to a ThoughtSpot instance.

  • Your application domain must be allowlisted in ThoughtSpot CSP and CORS settings.

  • Admin or developer privileges in ThoughtSpot.

  • A worksheet or table to use as the data source.

Install the Visual Embed SDK🔗

npm install @thoughtspot/visual-embed-sdk

Import the SDK and Components🔗

import { AuthType, init } from '@thoughtspot/visual-embed-sdk';
import { SpotterAgentEmbed, SpotterAgentViewConfig } from '@thoughtspot/visual-embed-sdk/react';

Initialize the SDK🔗

init({
  thoughtSpotHost: 'https://<your-thoughtspot-cluster>',
  authType: AuthType.None // Or AuthType.TrustedAuthToken, etc.
});

Configure SpotterAgentViewConfig🔗

const viewConfig = {
  worksheetId: '<your-worksheet-or-table-id>', // Required: Data source object ID
  searchQuery: 'sales by region',              // Optional: Initial query
  runtimeFilters: [
    {
      columnName: 'region',
      operator: 'EQ',
      values: ['West']
    }
  ],                                           // Optional: Pre-filtered context
  visibleActions: [
    'Action.Save',
    'Action.Download',
    'Action.DownloadAsPDF'
  ],                                           // Optional: Show only these actions
  disabledActions: [
    'Action.Download'
  ],                                           // Optional: Disable specific actions
  disabledActionReason: {
    'Action.Download': 'Download is not allowed for this user'
  },                                           // Optional: Tooltip for disabled actions
  hideSourceSelection: true,                   // Optional: Hide data source selector
  disableSourceSelection: false,               // Optional: Disable data source selection
  locale: 'en-US',                             // Optional: Set locale
  showSpotterLimitations: false,               // Optional: Show Spotter limitations
  hideSampleQuestions: true                    // Optional: Hide sample questions
};

Embed the Spotter Agent🔗

<SpotterAgentEmbed
  viewConfig={viewConfig}
  frameParams={{ height: '600px' }}
  onLoad={() => console.log('Spotter Agent loaded')}
  onInit={() => console.log('Spotter Agent initialized')}
/>

Register and Handle Events🔗

You can handle Spotter Agent events for analytics and integration.

<SpotterAgentEmbed
  viewConfig={viewConfig}
  onLoad={handleLoad}
  onInit={handleInit}
  onData={handleData}
  onError={handleError}
/>

Common events include: - onLoad: Fires when Spotter Agent is loaded. - onInit: Fires when Spotter Agent is initialized. - onData: Fires when data is returned from a query. - onError: Fires on error.

Customizing the UI🔗

  • Use visibleActions, hiddenActions, and disabledActions in the config to control menu actions. Do not use both visibleActions and hiddenActions at the same time [1], [2], [3].

  • To apply custom styles, use CSS variables such as:

    :root {
  --ts-var-spotter-input-background: #f5f5f5;
  --ts-var-spotter-prompt-background: #e0e0e0;
}

Test the Embedded Spotter Agent🔗

  • Start your app.

  • Verify Spotter Agent loads and is interactive.

  • Confirm initial query and runtime filters are applied.

  • Test event handlers and UI customizations.

Additional Notes🔗

  • Use only answerId for event tracking in SpotterAgentEmbed.

  • SpotterAgentEmbed supports both host and embed events for two-way communication.

  • For advanced use, refer to the official SDK and API documentation.

Note

If you are embedding full ThoughtSpot experience in your app via AppEmbed, you must enable new home page experience and set the home page search bar mode to aiAnswer to view Spotter components. For more information, see Customize full application embedding.