diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 4f5ebcb00..d42224b5c 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -6,68 +6,82 @@ :page-pageid: mcp-integration :page-description: Learn how to use the ThoughtSpot Model Context Protocol (MCP) server to interact with ThoughtSpot data via MCP tools and AI APIs and get relevant questions and answers for a given query and create Liveboards at runtime. -ThoughtSpot’s Agentic Model Context Protocol (MCP) Server enables integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. +ThoughtSpot’s Agentic Model Context Protocol (MCP) Server allows you to integrate ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. + +The ThoughtSpot MCP Server is an add-on feature available with the link:https://www.thoughtspot.com/pricing[ThoughtSpot Analytics and ThoughtSpot Embedded offerings, window=_blank]. + +To purchase the MCP Server subscription and enable the MCP Server in your environment, you must have an active subscription to one of the following ThoughtSpot license plans: -The MCP tools of the Agentic MCP Server support the following functions: +* Enterprise Edition of ThoughtSpot Analytics +* ThoughtSpot Embedded subscription -* Ask natural language questions and get data in a structured format from ThoughtSpot -* Retrieve relevant analytical questions based on user queries -* Create a Liveboard with the answers generated from the queries -* Get data source recommendations based on a user's query and intent +To learn more about the MCP Server subscription options and to get started, please contact your ThoughtSpot Sales representative. == Integration overview The Agentic MCP Server integration requires the following core components and authentication framework: MCP Server:: -The MCP Server provides a tools wrapper with a discoverable interface for agentic analytics. It exposes a set of tools to external agents to interact with ThoughtSpot's resources, data, and analytical capabilities. The MCP Server includes an orchestration layer that determines which tools to invoke based on the incoming queries and user intent. The MCP Server can be hosted by ThoughtSpot or by customers in their own environment. +The MCP Server exposes a set of tools that can be invoked by an LLM or external AI. ThoughtSpot's MCP Server acts as a bridge between the LLM/agent and ThoughtSpot application backend. -MCP tools, resources, and AI APIs:: -MCP tools are the actions that the MCP Server exposes to the agent for interaction with ThoughtSpot. Currently, the MCP Server supports the following tools: +MCP tools and resources:: +MCP tools are the actions that the MCP Server exposes to the agent for interaction with ThoughtSpot. + +* Ask natural language questions and get data in a structured format from ThoughtSpot +* Retrieve relevant analytical questions based on user queries +* Create a Liveboard with the answers generated from the queries +//* Get data source recommendations based on a user's query and intent + ++ +Currently, the MCP Server supports the following tools: * `ping` to test connection to ThoughtSpot * `getRelevantQuestions` to get relevant analytical questions + -The `getRelevantQuestions` tool calls xref:spotter-apis.adoc#_get_relevant_questions[/api/rest/2.0/ai/relevant-questions/] API and gets relevant data questions for a given data context by breaking down a user's query. +The `getRelevantQuestions` tool to fetch relevant data questions for a given data context by breaking down a user's query. * `getAnswer` to execute the queries and fetch data + -The `getAnswer` tool calls xref:spotter-apis.adoc#_send_a_question_and_generate_streaming_responses[/api/rest/2.0/ai/agent/converse/sse] API and generates answers and insights for a given data context. +The `getAnswer` tool generates answers and insights for a given data context. * `createLiveboard` to create a Liveboard in ThoughtSpot + -The `createLiveboard` tool calls the Liveboard creation workflow and creates a Liveboard with the answers generated from user's query. +The `createLiveboard` tool calls the Liveboard creation workflow and creates a Liveboard with the answers generated from the user's query. + +//// * `getDataSourceSuggestions` to get data source suggestions + Based on the type of data that users want to fetch, `getDataSourceSuggestions` gets a list of data source recommendations. Currently, `getDataSourceSuggestions` is not exposed as an MCP tool and is available as an MCP `resource`. To get data source suggestions, the user or MCP client must have at least view access to ThoughtSpot data sources. +//// -MCP host/client:: -The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface, orchestrates interaction with ThoughtSpot MCP Server, and enables agentic workflows. +MCP client/ LLM agent:: +The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface and orchestrates interaction with the ThoughtSpot MCP Server. +This is the model or system that processes the user’s natural language input, determines which tool to call, and integrates the tool results into its final output. +//// Configuration settings to enable the integration:: Integration requires configuration, typically via a config file, to specify server addresses, credentials, and other connection details. +//// Authentication and security settings:: + * Access to ThoughtSpot instance: + -For MCP Server connection, users require access to a ThoughtSpot instance. ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in the users. + -To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create Liveboard, users +For MCP Server connection, users require access to a ThoughtSpot instance. For tool invocation, the MCP server must accept authenticated requests, and the LLM tool specification must carry those credentials or headers. + +ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in users. + +* SAML redirect settings: + +For SAML SSO users, the SAML redirect domain configuration is required to ensure that users are redirected to an allowed and trusted domain after they are authenticated. + +* To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create a Liveboard, users require the data download privilege. * CSP and CORS settings: + To secure communication between the MCP client and the ThoughtSpot instance, administrators must add the MCP Server URL to CSP (Content Security Policy) and CORS (Cross-Origin Resource Sharing) allowlists in ThoughtSpot. -* SAML redirect settings: + -For SAML SSO users, the SAML redirect domain configuration is required to ensure that users are redirected to an allowed and trusted domain after they are authenticated. * Client connection configuration: + MCP Server integration also requires configuration on the client side, typically via a config file, to include the MCP Server addresses, credentials, and other details. + === How it works -When the MCP Server integration is enabled, your host app connects to ThoughtSpot and enables the following workflow: - -. User initiates a request. + -The user sends a query to get data from a specific ThoughtSpot data model or context. -. AI agent receives the request and discovers the MCP tools + -The agent discovers MCP tools available in its environment and processes the request to the MCP Server, specifying the data model or context and the user's query. -. MCP Server receives the request and executes actions via tools + -The MCP Server executes tools and triggers API requests to ThoughtSpot to break down the user's query into relevant questions, get information for the specified data context, or create an artifact. -. The MCP Server sends the response to the MCP host. -. The agent receives the response and constructs the output + -The agent receives the response from the MCP host, constructs the output, and presents it to the user. -. User receives the response + -The user can refine the analysis or choose a direction for further exploration. + -For example, after receiving relevant questions and answer, the user can send follow-up questions or send a Liveboard creation request. +The MCP Server integration with an agentic framework or LLM clients enables the following workflow: + +. User sends a query to get data from a specific ThoughtSpot data model context. +. The LLM / AI agent receives the request and sends it to the MCP server endpoint with the user's query. +. The MCP server responds with the available tools. +. The LLM / AI Agent determines the appropriate MCP tool to call. Based on the user's query or prompt, the MCP tools are invoked. For example, to get information for a specific data context from ThoughtSpot, break down the user's query into relevant questions or programmatically create an artifact in ThoughtSpot. +. The MCP server processes the request and returns the result. +. The agent receives the response, constructs the output, and presents it to the user. +. User receives the response. The user can refine the analysis with follow-up queries for further exploration or ask a new question. + +For example, after receiving relevant questions and answers, the user can send follow-up questions or initiate a Liveboard creation request. The following figure illustrates the sequence of workflows in a typical MCP Server integration setup: @@ -86,19 +100,245 @@ Before you begin, verify if your application setup has the following: * Your application users have at least view access to the data source objects to query data and get answers. * Row-level and column-level security rules are configured for data security and access control. +To enable secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: + +. On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. +. Add the MCP Server domain to CSP and CORS allowlists. +. If your setup uses SAML SSO logins, add the MCP Server domain to the SAML redirect domain allowlist. + +//// === Configure security settings on ThoughtSpot -To allow the secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: +To allow secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: . On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. . Add the MCP Server domain to CSP and CORS allowlists. . If your setup uses SAML SSO logins, add the MCP Server domain to the SAML redirect domain allowlist. +//// -=== Add MCP Server to the MCP client's config +=== Connect your client to the MCP Server -If your MCP client supports remote MCP Servers, add the MCP Server URL to the client's config file. +If using a client that supports remote MCPs natively, such as Claude AI, use the following MCP server URL: +---- +https://agent.thoughtspot.app/mcp +---- -MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote MCP Servers. In such a case, add the URL with arguments shown in this example: +For OpenAI ChatGPT Deep Research, use the following URL: +---- +https://agent.thoughtspot.app/openai/mcp +---- + +For MCP clients such as Claude Desktop, Windsurf, and Cursor that do not support a remote MCP Server, you must xref:mcp-integration.adoc#_connecting_other_mcp_clients_claude_desktop[add the MCP server configuration to your MCP client settings]. + +=== Call MCP tools via LLM APIs + +ThoughtSpot remote MCP Server acts as a wrapper over the ThoughtSpot APIs, making them available as tools for agent frameworks or LLMs such as Claude or OpenAI. It exposes specific tools that can be invoked by the LLMs in response to a user's query or prompt. + +To enable tool calling: + +* Register the ThoughtSpot MCP Server endpoint as a tool provider in your LLM or agent framework. +* Provide an authentication (OAuth or token-based) token. + +You can generate an authentication token for a specific user from ThoughtSpot via a `POST` call to the `/api/rest/2.0/auth/token/full` REST API endpoint. + +Logged-in users can view the authentication token for their current session by using the `/api/rest/2.0/auth/session/token` REST API endpoint or by opening the following URL in a new tab on the web browser: ++ +`https://{your-ts-instance}/api/rest/2.0/auth/session/token` + +For information about calling MCP tools using LLM APIs and methods, see these sections: + +* xref:mcp-integration.adoc#_claude_mcp_connector[Claude MCP connector] +* xref:mcp-integration.adoc#_openai_api_for_mcp_tool_calling[OpenAI API] +* xref:mcp-integration.adoc#_gemini_api[Gemini API and function calling] + +==== Claude MCP connector +The Claude’s MCP connector allows you to connect to remote MCP Servers directly from the Messages API. + +To connect to the ThoughtSpot remote MCP Server, specify the following properties in the API request: + +* `mcp_servers` + +In the `mcp_servers` array, include these parameters: + +** `type` + +__String__. Type. Specify the type as `url`. +** `url` + +__String__. The URL of the remote MCP Server endpoint. Must start with `https://`. +** `name` + +__String__. A unique identifier/label for the MCP Server. It will be used in the MCP tool call blocks to identify the server and to disambiguate tools to the LLM. +** `authorization_token` + +__String__. OAuth authorization token (`TS_AUTH_TOKEN`) along with the ThoughtSpot application instance URL. In the following example, the authorization token is added as a prefix, and the ThoughtSpot host URL is added with the `@` symbol. + +* `messages` + +In the `messages` array, specify a natural language question in `content` and the user role in `role`. + +* `model` + +LLM model to use for processing queries and interacting with tools. For example, claude-sonnet-4-20250514. + +[source,cURL] +---- +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "X-API-Key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: mcp-client-2025-04-04" \ + -d '{ + "model": "claude-sonnet-4-20250514", + "max_tokens": 1000, + "messages": [{ + "role": "user", + "content": "How do I increase my sales ?" + }], + "mcp_servers": [ + { + "type": "url", + "url": "https://agent.thoughtspot.app/bearer/mcp", + "name": "thoughtspot", + "authorization_token": "$TS_AUTH_TOKEN@my-thoughtspot-instance.thoughtspot.cloud" + } + ] + }' +---- + +//// +[source,TypeScript] +---- +import { Anthropic } from '@anthropic-ai/sdk'; + +const anthropic = new Anthropic(); + +const response = await anthropic.beta.messages.create({ + model: "claude-sonnet-4-5", + max_tokens: 1000, + messages: [ + { + role: "user", + content: "How do I increase my sales ?", + }, + ], + mcp_servers: [ + { + type: "url", + url: "https://agent.thoughtspot.app/bearer/mcp", + name: "thoughtspot", + authorization_token: "$TS_AUTH_TOKEN@my-thoughtspot-instance.thoughtspot.cloud", + }, + ], + betas: ["mcp-client-2025-04-04"], +}); +---- +//// + +The request uses Claude’s internal tool-calling mechanism to call the MCP endpoint with the provided token, discover the available tools, and retrieve data for the user's query. + +For more information, see the link:https://docs.claude.com/en/docs/agents-and-tools/mcp-connector[Claude MCP connector documentation, window=_blank]. + +==== OpenAI API for MCP tool calling +To enable tool calling and retrieve data from ThoughtSpot via OpenAI, you can use the Responses API endpoint. + +To connect to the ThoughtSpot remote MCP server, call the `https://api.openai.com/v1/responses` API endpoint and specify the following properties in the API request: + +* `tools` + +In the `tools` array, include these parameters: + +** `server_url` + +The URL of the ThoughtSpot MCP Server. Use the full path of the MCP server URL. +** `server_label` + +Label of the ThoughtSpot MCP Server +** `type` + +Type of tool. For example, MCP. +** `headers` + +Additional headers needed for authentication, for example, the authentication token and URL of the ThoughtSpot host. + +* `input` + +Include the natural language query string as `input`. +* `model` + +LLM model to use for processing queries and interaction with tools. For example, GPT-5 or GPT 4.1. + +[source,cURL] +---- +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4.1", + "tools": [ + { + "type": "mcp", + "server_label": "thoughtspot", + "server_url": "https://agent.thoughtspot.app/bearer/mcp", + "headers": { + "Authorization": "Bearer $TS_AUTH_TOKEN", + "x-ts-host": "my-thoughtspot-instance.thoughtspot.cloud" + } + } + ], + "input": "How can I increase my sales ?" +}' +---- + +If the API request is successful, the LLM discovers the available MCP tools from the MCP Server endpoint. Once the model has access to these tools, it determines the tool to call depending on the user's query and what's in the model's context. + +For more information, see link:https://platform.openai.com/docs/guides/tools-connectors-mcp[Open AI Connectors and MCP Server Documentation]. + +==== Gemini API + +You can use the standard function calling mechanism provided in Gemini Python/Typescript SDK. The Gemini SDK supports MCP natively, and can pass tool definitions and call tools. + +In the following example, a session linked to the ThoughtSpot remote MCP Server is passed along with the authorization token and the ThoughtSpot host, so that the SDK can handle tool calling. + +[source,TypeScript] +---- +import { GoogleGenAI, FunctionCallingConfigMode , mcpToTool} from '@google/genai'; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; + +// Create server parameters for stdio connection +const serverParams = new StreamableHTTPClientTransport(new URL("https://agent.thoughtspot.app/bearer/mcp"), { + requestInit: { + headers: { + "Authorization": "Bearer $TS_AUTH_TOKEN", + "x-ts-host": "my-thoughtspot-instance.thoughtspot.cloud" + }, + } +}); + +const client = new Client( + { + name: "example-client", + version: "1.0.0" + } +); + +// Configure the client +const ai = new GoogleGenAI({}); + +// Initialize the connection between client and server +await client.connect(serverParams); + +// Send request to the model with MCP tools +const response = await ai.models.generateContent({ + model: "gemini-2.5-flash", + contents: `What is the weather in London in ${new Date().toLocaleDateString()}?`, + config: { + tools: [mcpToTool(client)], // uses the session, will automatically call the tool + // Uncomment if you **don't** want the sdk to automatically call the tool + // automaticFunctionCalling: { + // disable: true, + // }, + }, +}); +console.log(response.text) + +// Close the connection, +await client.close(); +---- + +For additional information, refer to the following resources: + +* For more information about Gemini API MCP tool calling, see link:https://ai.google.dev/gemini-api/docs/function-calling?example=meeting#mcp[Function calling with the Gemini API documentation, window=_blank]. +* A link:https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-google-adk-trusted-auth[developer example with Google ADK and Python implementation] is also available in the link:https://github.com/thoughtspot/developer-examples[ThoughtSpot Developer Examples GitHub repository, window=_blank]. +* The ThoughtSpot MCP server can also be installed as a Gemini CLI extension. For more information, see link:https://github.com/google-gemini/gemini-cli[Gemini CLI, window=_blank]. + +=== For clients that do not support the remote MCP server + +For clients such as Claude Desktop, Windsurf, and Cursor, which do not support remote MCP servers, add the following configuration to your MCP client settings: [source,JSON] ---- @@ -113,7 +353,6 @@ MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote M } } } - ---- After updating the config file: @@ -121,7 +360,8 @@ After updating the config file: . When prompted to connect your ThoughtSpot instance, add the URL of your application instance and complete authentication. . Restart your MCP client to load the new configuration. + -If the connection is successful, you'll see an option to connect to ThoughtSpot and choose the data context. + +If the connection is successful, you'll see an option to connect to ThoughtSpot and choose the data context. ++ For example, the Claude Desktop shows the *Add to ThoughtSpot* as shown in the following figure: + [.bordered] @@ -130,44 +370,23 @@ image::./images/claudeDesktop.png[Claude Desktop] . Verify if the MCP tools are available. + For example, on Claude Desktop, click the Search and tools icon to view the MCP tools. - + [.bordered] [.widthAuto] image::./images/mcp-tools-claude.png[Claude Desktop] -You can adjust tool access, resources, instructions to data models, object permissions, and user privileges as needed. To get insights, the user requires view access to the data source objects and data download privilege. - -=== Verify the query and response workflow - -* Select a data source to set the context of your query. + -For example, on Claude Desktop, click the `+` icon and select a data source. - -+ -[.bordered] -[.widthAuto] -image::./images/datasource-selection.png[Claude Desktop] - -* Ask an analytics question to trigger the query and response workflow. -* Verify if the AI agent on your MCP client gets relevant data questions from ThoughtSpot and generates an Answer. +. Select a data source to set the context of your query and verify the request and response flow. + [.bordered] [.widthAuto] image::./images/query-response-claude.png[Claude query response] -+ -[.bordered] -[.widthAuto] -image::./images/query-response-claude2.png[Claude query response 2] - -* Try sending a query to create a Liveboard and verify if a Liveboard is created on your ThoughtSpot instance. - +. Try sending a query to create a Liveboard and verify if a Liveboard is created on your ThoughtSpot instance. + [.bordered] [.widthAuto] image::./images/create-lb-claude.png[Liveboard creation] - == Configuration considerations and best practices * Users must have at least view access to the data source. Otherwise, it may lead to empty results. @@ -179,9 +398,9 @@ image::./images/create-lb-claude.png[Liveboard creation] * Check the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repo, window=_blank] for implementation instructions. * Check your MCP client's documentation for instructions on how to connect to MCP Servers. -* To understand ThoughtSpot agentic analytics capabilities and AI APIs, refer to the following documentation: +* In case of issues with connection or authentication, refer to the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^]. +* To understand ThoughtSpot's agentic analytics capabilities and AI APIs, refer to the following documentation: -** link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation] -** link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation] +** link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation, window=_blank] +** link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation, window=_blank] ** xref:spotter-apis.adoc[Spotter AI APIs] -* In case of issues with connection or authentication, refer to the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^]. \ No newline at end of file diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 6eb6daad5..7cab136a1 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -57,6 +57,14 @@ __Limited availability on ThoughtSpot Cloud instances from 10.13.0.cl onwards. P ==== //// +=== Locale settings for API requests + +When using the xref:spotter-apis.adoc#_generate_a_single_answer[Single Answer] and xref:spotter-apis.adoc#_send_a_question_to_generate_answer[Send message] APIs, the locale used for API requests depends on your application's locale settings: + +* If your application is set to "Use browser language," the API will not apply the default locale. In this case, you must explicitly include the desired locale code in the `Accept-Language` header of your API request. If you do not specify the locale, the API may not return responses in the expected language or format. +* If you have set a specific locale in your ThoughtSpot instance or user profile, the API will use this locale to generate responses, overriding the browser or OS locale + +To ensure consistent localization, set the `Accept-Language` header in your API requests when relying on browser language detection, or configure the locale explicitly in the user profile settings in ThoughtSpot. == Create a conversation session A conversation session acts as a container for maintaining continuity across user inputs, system responses, and agent-driven clarifications. Once created, users can send queries or ask follow-up questions to the conversation session to explore data and get further insights. @@ -82,26 +90,28 @@ To set the context for the conversation session, you must specify the metadata t [options='header'] |===== |Form parameter| Description -|`metadata_context` a| Defines the data context for the conversation. Specify the following values: +|`metadata_context` a| Defines the data context for the conversation. * `type` + -Metadata type. Valid values are: -** `answer` - To use an existing Spotter-generated Answer as the object -** `liveboard` - To use an existing Liveboard as data object -** `data_source` - To create a new conversation session using data objects such as Model. -+ +Metadata context type. The context type is mandatory. Select one of the following values: +** `data_source` - To set a data source context for the conversation session. + +If the context type is `data_source`, you must define the `data_source_context` in the request payload. +** `answer` - To use an existing Spotter-generated Answer as the object. + +If the context type is `answer`, you must define both `data_source_context` and `answer_context` in the request payload. +** `liveboard` - To use an existing Liveboard as context. + +If the context type is `liveboard`, you must define `data_source_context`, `liveboard_context`, and `answer_context` in the request payload. * `answer_context` + -If the metadata type is set as `answer`, specify the following attributes: +If the metadata type is set as `answer` or `liveboard`, specify the following attributes: ** `session_identifier`: __string__, Unique ID representing the answer session. ** `generation_number`: __Integer__. Specific generation/version number of the answer within a conversation session. + The session identifier and generation numbers are assigned to the Answers generated from the Spotter AI REST APIs. These properties serve as the ID of the AI-generated Answer within the ThoughtSpot system. * `liveboard_context` + -If the metadata type is set as `liveboard`, specify the GUID of the Liveboard and visualization. +If the metadata type is set as `liveboard`, specify the GUIDs of the Liveboard and visualization. * `data_source_context` + -If the metadata type is set as `data_source`, specify the GUID of the data source object. +Specify the GUID of the data source object. Required parameter for all types of metadata context. |`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: @@ -115,6 +125,8 @@ __Boolean__. Allows Spotter to use reasoning for deep analysis and precise respo ==== Example request +The following example shows the request payload for the `data_source` context type: + [source,cURL] ---- curl -X POST \ @@ -137,6 +149,63 @@ curl -X POST \ }' ---- +The following example shows the request payload for the `liveboard` context type: +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "liveboard", + "answer_context": { + "session_identifier": "c3a00fa7-fd01-4d58-8c84-0704df986d9d", + "generation_number": 2 + }, + "liveboard_context": { + "liveboard_identifier": "cffdc614-0214-42ba-9f57-cb6e8312fe5a", + "visualization_identifier": "da0ed3da-ce1f-4071-8876-74d551b05faf" + }, + "data_source_context": { + "guid": "54beb173-d755-42e0-8f73-4d4ec768114f" + } + }, + "conversation_settings": { + "enable_contextual_change_analysis": false, + "enable_natural_language_answer_generation": true, + "enable_reasoning": false + } +}' +---- + +The following example shows the request payload for the `answer` context type: + +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "answer", + "answer_context": { + "session_identifier": "f131ca07-47e9-4f56-9e21-454120912ae1", + "generation_number": 1 + }, + "data_source_context": { + "guid": "cd252e5c-b552-49a8-821d-3eadaa049cca" + } + }, + "conversation_settings": { + "enable_contextual_change_analysis": false, + "enable_natural_language_answer_generation": true, + "enable_reasoning": false + } +}' +---- + ==== API response If the API request is successful, the API returns the conversation ID. You can use this ID to send follow-up questions to the conversation session. @@ -146,7 +215,7 @@ If the API request is successful, the API returns the conversation ID. You can u {"conversation_id":"q9tZYf_6WnFC"} ---- -Note the conversation ID for further agentic interactions and API calls. +Note the conversation ID for subsequent agentic interactions and API calls. === Create a conversation session (legacy API endpoint) To create a conversation session, send a `POST` request body with the data source ID and search token string to the `/api/rest/2.0/ai/conversation/create` API endpoint. @@ -728,6 +797,7 @@ To send a question to an ongoing conversation session or ask follow-up questions curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/conversation/03f48527-b973-4efa-81fd-a8568a4f9e78/converse' \ -H 'Accept: application/json' \ + -H 'accept-language: en-US', \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ @@ -815,7 +885,6 @@ The API retrains the context of the initial question and returns a response: |=== //// - == Generate a single Answer To generate an Answer from a natural language search query, send a `POST` request to the `/api/rest/2.0/ai/answer/create` API endpoint. In the request body, include the query and the data source ID. @@ -836,6 +905,7 @@ To generate an Answer from a natural language search query, send a `POST` reques curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/answer/create' \ -H 'Accept: application/json' \ + -H 'accept-language: en-US', \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN} \ --data-raw '{ @@ -875,7 +945,6 @@ Note the session ID and generation number. To export the result generated from t }] ---- - [#process_results] == Process results generated from Spotter APIs To generate an Answer using the data returned from the Spotter APIs, use the following options: