Connect ThoughtSpot to AI Agents: Query Data and Export Reports

You want to connect ThoughtSpot to an AI agent so your system can autonomously run analytical queries, generate PDF reports, audit object permissions, and orchestrate ThoughtSpot Spotter sessions. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom Business Intelligence (BI) integration from scratch.

Giving a Large Language Model (LLM) read and write access to your BI instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting ThoughtSpot to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting ThoughtSpot to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for ThoughtSpot, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex reporting workflows. For a broader look at this design pattern, read our guide on Architecting AI Agents: LangGraph, LangChain, and the SaaS Integration Bottleneck.

The Engineering Reality of the ThoughtSpot API

Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production against complex enterprise BI systems, this approach collapses.

ThoughtSpot's API introduces several specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

TML (ThoughtSpot Modeling Language) Complexity

Unlike traditional REST APIs that traffic entirely in simple JSON objects, ThoughtSpot manages its core metadata via TML (ThoughtSpot Modeling Language). When an agent wants to modify a Liveboard, Answer, or Logical Table, it cannot simply PATCH a flat JSON record. It must export the TML representation (in JSON or YAML), understand the nested hierarchical structure of the data model, modify the relevant visualization or column mappings, and push the TML back via an import endpoint. An LLM exposed directly to raw TML without a strict schema wrapper will frequently hallucinate invalid syntax, breaking your data models.

Asynchronous Polling for Heavy Imports

Enterprise BI operations are heavy. When an agent attempts to import large groups of TML files or trigger an index rebuild, ThoughtSpot does not block and return a synchronous success message. It returns an asynchronous task ID. The caller must then repeatedly poll an async status endpoint (create_a_thought_spot_async_status) until the task resolves. Standard LLMs struggle with asynchronous state management; if you expose the raw API, the model will often assume the operation is complete the millisecond it receives the task ID, leading to premature execution of dependent steps.

Row-Level Security (RLS) and Custom Token Scoping

ThoughtSpot relies heavily on complex Row-Level Security (RLS) and Trusted Authentication. To query data on behalf of a specific user, the system must generate a custom authentication token scoped specifically to that user and pass formula variables to enforce RLS. If your agent framework is responsible for raw API requests, it must securely orchestrate this multi-step token generation process before it can execute a single search query. One hallucinated parameter in the token request will result in unauthorized access errors or, worse, data exposure.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, decide what layer your agent talks to. This choice determines how safe your production system will be.

Direct API tools (one tool per raw ThoughtSpot endpoint) push provider quirks into the LLM's context. The model has to remember exactly how to poll the async endpoints, format the TML payload, and manage the custom authentication tokens. Every one of those quirks is a hallucination waiting to happen.

Truto operates by mapping any API into a REST-based CRUD API using the concept of Resources and Methods. Every integration on Truto is essentially a comprehensive JSON object that represents how the underlying product's API behaves.

When your agent accesses ThoughtSpot through Truto's proxy APIs, it collapses the BI platform behind one standardized schema. That gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from stable function names with explicit parameter definitions.
2. Deterministic input validation. Every tool has a strict JSON schema derived from the underlying method. Invalid arguments are rejected by Truto's proxy layer before they hit ThoughtSpot, so a broken tool call fails fast instead of corrupting a BI dashboard.
3. Abstracted authentication. The agent does not need to understand Trusted Auth or token scoping; Truto handles the base authentication layer for the integrated account.

Fetching and Binding ThoughtSpot Tools

Truto provides a set of tools for your LLM frameworks by offering a description and schema for all the Methods defined on the Resources for an integration.

To expose ThoughtSpot to your agent, you make a request to the /tools endpoint on the Truto API. This returns all the Proxy APIs with their descriptions and schemas, creating native tools that LLM frameworks can consume.

Here is how to fetch and bind these tools dynamically using the TrutoToolManager from the truto-langchainjs-toolset. This approach works identically whether you are using LangChain, LangGraph, or passing the tools to Vercel AI SDK.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "@trutohq/langchainjs-toolset";
 
// 1. Initialize the Truto Tool Manager with your API key
const toolManager = new TrutoToolManager({
  apiKey: process.env.TRUTO_API_KEY,
});
 
// 2. Fetch the tools for your specific ThoughtSpot integrated account
// You can filter by methods (e.g., 'read', 'custom') to limit scope
const thoughtSpotTools = await toolManager.getTools(
  process.env.THOUGHTSPOT_INTEGRATED_ACCOUNT_ID,
  { methods: ["read", "write", "custom"] }
);
 
// 3. Initialize your LLM
const llm = new ChatOpenAI({
  model: "gpt-4o",
  temperature: 0,
});
 
// 4. Bind the ThoughtSpot tools to the model
const agentWithTools = llm.bindTools(thoughtSpotTools);
 
// 5. Execute a query
const response = await agentWithTools.invoke([
  { role: "user", content: "Query the Q3 Sales data source and give me the revenue by region." }
]);
 
console.log(response.tool_calls);

Because the tools are generated dynamically from the integration definition, any customizations you make to the tool descriptions in the Truto UI immediately propagate to your agent the next time you call /tools.

Building Multi-Step Workflows and Handling Rate Limits

Agents rarely execute just one tool. A standard reporting workflow requires the agent to query data, generate a report, and adjust permissions. To orchestrate this, you need a resilient agent loop.

The most critical component of a production agent loop is rate limit handling.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream ThoughtSpot API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller.

However, Truto normalizes the upstream rate limit info into standardized headers per the IETF spec:

• ratelimit-limit: The maximum number of requests permitted.
• ratelimit-remaining: The number of requests remaining in the current window.
• ratelimit-reset: The time (in seconds) until the limit resets.

The caller (your agent framework) is completely responsible for reading these headers and executing a retry/backoff strategy.

Here is an architectural flow showing how the agent must handle a 429 error returned by Truto.

sequenceDiagram
    participant Agent as AI Agent Loop
    participant Truto as Truto Proxy API
    participant Upstream as Upstream API (ThoughtSpot)

    Agent->>Truto: Call thought_spot_2_0_searchdatas_search
    Truto->>Upstream: Forward API Request
    Upstream-->>Truto: HTTP 429 Too Many Requests
    Truto-->>Agent: HTTP 429 (Headers: ratelimit-reset: 10)
    Note over Agent: Agent parses headers<br>Pauses execution for 10s
    Agent->>Truto: Retry thought_spot_2_0_searchdatas_search
    Truto->>Upstream: Forward API Request
    Upstream-->>Truto: HTTP 200 OK
    Truto-->>Agent: HTTP 200 OK + Normalized Data
    Note over Agent: Agent passes data<br>back to LLM context

When writing your custom tool executor, ensure you catch the 429, extract the ratelimit-reset header, pause the thread, and retry. If you rely on the LLM to "decide" when to retry, it will immediately spam the API again and exhaust your context window with error loops.

Hero Tools for ThoughtSpot Agents

ThoughtSpot exposes a massive surface area. While your agent can access dozens of endpoints, you should restrict its toolset to the highest-leverage operations to maintain deterministic behavior.

Here are the critical tools to expose for autonomous BI agents.

thought_spot_2_0_searchdatas_search

This is the core analytical engine. It allows the agent to execute search-token queries against a ThoughtSpot data source (Worksheet, View, Table) and retrieve the generated answer data.

"Run a search against the 'Global Sales 2026' logical table. Filter by 'Region = EMEA' and group by 'Product Category'. Return the raw contents."

create_a_thought_spot_answer_create

For more complex natural language processing, this endpoint allows the agent to pass a natural language query directly against a data model, leveraging ThoughtSpot's internal AI to generate an answer session. It returns the generated tokens and visualization type.

"Generate an answer for the natural language query: 'What were the top 5 performing stores last month?' using the Retail Metadata model."

create_a_thought_spot_report_answer

This tool is critical for distribution. It commands ThoughtSpot to export a saved Answer as a downloadable file (CSV, PDF, PNG, or XLSX). The agent can use this to extract visual reports without rendering them locally.

"Export the saved Answer 'Monthly Churn Metrics' as a PDF report so I can distribute it to the executive team."

thought_spot_metadata_manage_object_privilege

This is an administrative tool that allows the agent to programmatically add or remove object-level privileges for users and groups on metadata objects (like Logical Tables).

"Remove the READ_ONLY object privilege for the 'External Consultants' group on the 'Q3 Financials' logical table."

create_a_thought_spot_tml_export

This tool allows the agent to export the ThoughtSpot Modeling Language (TML) representation of metadata objects in JSON or YAML format. This is required for agents performing version control, backup, or schema auditing tasks.

"Export the TML representation of the 'Core HR Dashboard' Liveboard so I can audit the underlying column dependencies."

For the complete tool inventory and detailed JSON schemas, view the ThoughtSpot integration page.

Workflows in Action

Here is how these tools compound to create autonomous, multi-step workflows for specific user personas.

Scenario 1: Automated Data Query & PDF Report Distribution

Persona: Data Analyst / Operations Manager

"Check the Q3 Pipeline worksheet. Find all deals closed in North America this month, generate a PDF report of that specific answer, and prep it for download."

Execution Steps:

1. The agent calls thought_spot_2_0_searchdatas_search passing the query string for North American closed deals and the logical table identifier for the Q3 Pipeline worksheet.
2. ThoughtSpot returns the raw data contents, which the agent analyzes to verify the results are correct.
3. The agent calls create_a_thought_spot_answer_create to ensure the specific view is locked as an answer session.
4. The agent calls create_a_thought_spot_report_answer, requesting a PDF file format for the generated answer.

Outcome: The agent autonomously navigates the BI data model, executes the query, and produces a binary PDF report ready for the user to distribute, entirely bypassing the ThoughtSpot UI.

Scenario 2: AI-Driven Object Permissions Auditing

Persona: IT Administrator / Security Operations

"Audit the 'Executive Compensation' Logical Table. Tell me who has access, and immediately remove access for anyone in the 'Contractors' user group."

Execution Steps:

1. The agent calls list_all_thought_spot_metadata_permissions (or list_all_thought_spot_metadata_object_privileges) passing the identifier for the 'Executive Compensation' table.
2. The agent parses the returned JSON, identifying the principal groups that currently hold object privileges.
3. The agent isolates the 'Contractors' group identifier from the results.
4. The agent calls thought_spot_metadata_manage_object_privilege, setting the operation to remove privileges for the identified principal on that specific metadata identifier.

Outcome: The system enforces strict Row-Level Security and object permissions autonomously, ensuring sensitive financial models are not exposed to unauthorized groups, without requiring manual admin intervention.

Moving Past Hardcoded Integrations

Giving AI agents access to enterprise BI platforms like ThoughtSpot forces a build-vs-buy decision. If you build it yourself, your engineers are responsible for managing complex TML parsing, polling async import jobs, and normalizing rate limit headers for every single API call.

By routing agent traffic through Truto's /tools endpoint, you offload the integration boilerplate. Your LLM interacts with a clean, strictly validated proxy API, drastically reducing the attack surface for hallucinations and letting your engineering team focus on the agent's core reasoning loops.