---
schema_version: "1"
id: d527c249d7777357bc42265719a2607c30cff3fede8c7335fe0a2c65e2e66703
title: Embed the Tableau Agent
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/analytics/sdk/guides/sdk-integration-embed-agent.md
canonical_url: https://developer.salesforce.com/docs/analytics/sdk/guide/sdk-integration-embed-agent.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: ff07e8210e0d2af722950ca0a07b767bf27792e5fde4858d7055c89b89b98150
products:
  - Tableau Next Embedding SDK
  - analytics
---
# 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](https://help.salesforce.com/s/articleView?id=analytics.tua_admin_enable_agentforce_templates.htm).

## 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.

   ![The agent ID in the Agent Details page URL.](https://developer.salesforce.com/docs/media/sdk/setup_agent_url_id.png '{"class": "image-lg"}')

## 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.

```javascript
<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.

```javascript
<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.

```javascript
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

```typescript
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.

```javascript
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:

```html
<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>
```

| Property       | Type           | Description                                  |
| -------------- | -------------- | -------------------------------------------- |
| `welcomeImage` | `WelcomeImage` | Image shown on the agent welcome screen.     |
| `agentAvatar`  | `AgentAvatar`  | Avatar shown next to inbound agent messages. |

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

```typescript
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`](/docs/analytics/sdk/references/sdk-js-v11/AgentStyleTokens.html)

A smaller Salesforce Slack-themed agent

![A Salesforce Slack-themed agent ](https://developer.salesforce.com/docs/media/sdk/embedded_agent_small_slack_theme.png '{"class": "image-xs"}')

A larger Salesforce Slack-themed agent

![A Microsoft Teams-themed agent embedded in Teams](https://developer.salesforce.com/docs/media/sdk/embedded_agent_large_theme.png '{"class": "image-lg"}')

Themed agents embedded in external web apps

![A dark themed agent embedded in an external web app](https://developer.salesforce.com/docs/media/sdk/embedded_agent_dark_theme.png '{"class": "image-xs"}')

![A green-themed agent embedded in an external web app](https://developer.salesforce.com/docs/media/sdk/embedded_agent_green_theme.png '{"class": "image-xs"}')

## 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.

```Typescript
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

```typescript
await agent.startNewAgentSession();
```

## Reference

For detailed reference, see:

- [`AnalyticsAgent`](/docs/analytics/sdk/references/sdk-js-v2/AnalyticsAgent.html) class
- [`AgentContextType`](/docs/analytics/sdk/references/sdk-js-v2/AgentContextType.html) enum
- [`AgentProps`](/docs/analytics/sdk/references/sdk-js-v2/AgentProps.html) type

## Agent Troubleshooting

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

| Error Message                        | Possible Resolutions                                                                                      |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| "Something went wrong, try again"    | Users can check the access in the agent access section. The Agent `idOrApiName` value might be incorrect. |
| Agent doesn't understand the context | Check the topic in the agent home. Check the context in the code.                                         |