Embed the Tableau Agent

Bring your Tableau agent directly into your app. This agent helps your users see and understand data with conversational analytics. The agent generates natural language insights, visualizations, and proactive alerts in your flow of work.

Use the AnalyticsAgent class to embed your agent as a component in your app.

Create Your Agent

Tableau Agent is a collection of pre-built agentic capabilities made available through the Analytics and Visualization agent template. Turning these settings on in Tableau Next makes the Analytics and Visualization agent template and its subagents and actions available to you

To set up and create your agent, see Set Up Tableau Agent in Tableau Next.

Get Your Agent ID

Get the ID for your agent.

1. From Setup, in the Quick Find box, enter Agentforce, and select Agentforce Agents.

2. In the list of agents, click your agent name.

3. To get the ID of the agent, the ID from the Agent Details page URL.

   

Add the AnalyticsAgent Component to Your App

Embedding the AnalyticsAgent component is the same as embedding the other analytics components, using a container, the authentication configuration, and the SDK initialization.

Construct the AnalyticsAgent component, using the AgentProps. The AgentProps specify the container name and agent ID, along with the agent context type and the API name for the context type.

The AUTH_CREDENTIAL value is the Frontdoor URL or access token provided by the code you created to authorize your users with Salesforce. The orgUrl is the URL for your Salesforce org.

The AnalyticsAgent component is designed to be embedded independent of other analytics components and works on its own. You can embed one or more corresponding analytics components to give your user context for asking the agent questions, but it isn't required for the agent to work.

Single Component Mode

To track a single analytics asset, provide a contextConfig with contextType and contextTypeIdOrApiName. The AgentContextConfig specifies the analytical view or data scope for the agent to use.

<div id='agent-container'></div>
<script type="module">
  import {initializeAnalyticsSdk, AnalyticsAgent, AgentContextType} from '@salesforce/analytics-embedding-sdk';

  const config = {
		authCredential: 'AUTH_CREDENTIAL',
		orgUrl: 'https://my-domain.lightning.pc-rnd.force.com'
	};

	await initializeAnalyticsSdk(config);

  const agent = new AnalyticsAgent({
    parentIdOrElement: 'agent-container',
    idOrApiName: '0Xxfib0000000xxxxx',
    contextConfig: {
      contextType: AgentContextType.METRIC,
      contextTypeIdOrApiName: 'MyMetric1'
    }
  });
  agent.render();
</script>

Agent Context

The agent context specifies the analytical view or data scope for the agent to use. The agent uses this context to answer user questions.

You must reference the ID or API name of a semantic model, dashboard, or metric that exists in the same org as your Tableau agent.

You can find the API name using the asset URL from Salesforce. In Tableau Next, view the asset you want to embed. When viewing the asset, the URL for the asset provides the asset API name.

• Dashboard URL: https://<salesforce.org>.force.com/tableau/dashboard/<asset-api-name>/view.
• Semantic Model URL: https://<salesforce.org>.force.com/tableau/sdm/<asset-api-name>/edit.
• Metric URL: https://<salesforce.org>.force.com/tableau/exploreMetric/<asset-api-name>?{metricParameters}.

Set the context type to the matching enum value, AgentContextType.SDM, AgentContextType.DASHBOARD, or AgentContextType.METRIC of the component type you selected.

Multiple Component Mode

To have the agent automatically track all embedded AnalyticsDashboard and AnalyticsMetric components on a page, omit the contextConfig. Omitting the contextConfig runs the agent in multiple component mode. The agent receives context updates from every dashboard and metrics component and can answer questions across all of them.

<div id='dashboard-container'></div>
<div id='metric-container'></div>
<div id='agent-container'></div>
<script type="module">
  import {initializeAnalyticsSdk, AnalyticsAgent, AnalyticsDashboard, AnalyticsMetric} from '@salesforce/analytics-embedding-sdk';

  const config = {
		authCredential: 'AUTH_CREDENTIAL',
		orgUrl: 'https://my-domain.lightning.pc-rnd.force.com'
	};

	await initializeAnalyticsSdk(config);

  const dashboard = new AnalyticsDashboard({
    parentIdOrElement: 'dashboard-container',
    idOrApiName: 'MyDashboard1'
  });

  const metric = new AnalyticsMetric({
    parentIdOrElement: 'metric-container',
    idOrApiName: 'MyMetric1'
  });

  const agent = new AnalyticsAgent({
    parentIdOrElement: 'agent-container',
    idOrApiName: '0Xxfib0000000xxxxx'
  });

  dashboard.render();
  metric.render();
  agent.render();
</script>

Because contextConfig isn't provided, the agent picks up context from both the dashboard and metric components automatically. You can embed as many dashboard and metric components alongside the agent as you need.

Header Settings

You can also show the agent header and header actions, which aren't visible by default. The header actions include the agent information and restart session actions. When a user restarts a session, it clears their current session history.

const agent = new AnalyticsAgent({
  parentIdOrElement: "agent-container",
  idOrApiName: "0Xxfib0000000xxxxx",
  contextType: "AgentContextType.METRIC",
  contextTypeIdOrApiName: "My_Metric_1",
  showHeader: true,
  showHeaderActions: true,
});

Customization Settings

You can customize your agent component, setting AgentProps values like agentName, welcomeText, and styleTokens.

Example for Agent Name and Welcome Message

const agent = new AnalyticsAgent({
  parentIdOrElement: "agent-container",
  idOrApiName: "0Xxfib0000000xxxxx",
  agentName: "Sales Insights Agent",
  welcomeText: "Hello! Ask me anything about your sales data.",
});

Example for welcome image and agent avatar

Override the welcome-screen image and the avatar shown next to inbound (agent) messages with the optional welcomeImage and agentAvatar props. Each takes an image src and an optional alt string for screen readers.

const agent = new AnalyticsAgent({
	parentIdOrElement: 'agent-container',
	idOrApiName: '<%- agent-id %>',
	welcomeImage: {src: 'https://cdn.example.com/img/welcome.png', alt: 'Welcome to Sales Insights'},
	agentAvatar: {src: 'https://cdn.example.com/img/agent-avatar.png', alt: 'Sales Insights agent'}
});
agent.render();

When embedding via the <analytics-agent> HTML element, pass each override as a JSON-encoded welcome-image / agent-avatar attribute:

<analytics-agent
	id-or-api-name="<%- agent-id %>"
	welcome-image='{"src":"https://cdn.example.com/img/welcome.png","alt":"Welcome to Sales Insights"}'
	agent-avatar='{"src":"https://cdn.example.com/img/agent-avatar.png","alt":"Sales Insights agent"}'
></analytics-agent>

Each src must be a https:// URL (with no embedded credentials) or a root-relative path under /img/. Any other value is ignored, and the default image is used.

The image host must also be trusted by your org, or the browser blocks the image and the default is shown. To trust the host:

1. In Salesforce Setup, go to Security > Trusted URLs.
2. Click New Trusted URL.
3. In URL, enter the image host. For example, https://cdn.example.com.
4. Under CSP Directives, enable img-src.
5. Click Save.

Example for Style Tokens

const agent = new AnalyticsAgent({
  parentIdOrElement: "agent-container",
  idOrApiName: "0Xxfib0000000xxxxx",
  showHeader: true,
  agentName: "Revenue Insights",
  welcomeText: "Ask me anything about your revenue data.",
  styleTokens: {
    containerBackground: "#faf5ff",
    headerBackground: "#ede9fe",
    headerBlockTextColor: "#5b21b6",
    welcomeBlockTextColor: "#4c1d95",
    welcomeBlockFontSize: "26px",
    welcomeBlockFontWeight: "600",
    messageBlockInboundBackgroundColor: "#ede9fe",
    messageBlockInboundTextColor: "#3b0764",
    messageBlockOutboundBackgroundColor: "#7c3aed",
    messageBlockOutboundTextColor: "#ffffff",
    messageInputTextBackgroundColor: "#faf5ff",
    messageInputFooterBorderFocusColor: "#8b5cf6",
    messageInputFooterSendButton: "#ec4899",
  },
});

To view all the available style tokens, see AgentStyleTokens

A smaller Salesforce Slack-themed agent

A larger Salesforce Slack-themed agent

Themed agents embedded in external web apps

Events

Use the COMPONENT_LOADED event to listen for when the agent component is successfully loaded with an active session and is ready for interaction. Listen for ERROR events, using the payload to get details for troubleshooting.

import {EventName} from '@salesforce/analytics-embedding-sdk';

agent.addEventListener(EventName.COMPONENT_LOADED, () => {
  console.log('Agent is ready');
});

agent.addEventListener(EventName.ERROR, (event) => {
  console.error('Agent error:', event);
});

Start a New Agent Session Programmatically

await agent.startNewAgentSession();

Reference

For detailed reference, see:

• AnalyticsAgent class
• AgentContextType enum
• AgentProps type

Agent Troubleshooting

These are possible errors users might see when using the agent and suggestions on resolving them.