> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Embed a Sigma agent

> Embed a Sigma agent so each of your customers can chat about their own usage trends, scoped with row-level security and impersonation.

> **Note**
>
> The use of AI features is subject to the following [disclaimer](/docs/notice-for-enabling-ai-enabled-features-in-sigma).

> **Note**
>
> Usage of this feature uses consumption credits. For details about what usage is billed, see [About billable usage events](/docs/about-billable-usage-events).

Embed a Sigma agent in a chat element for a fully managed embedded AI chat experience using the data sources and RBAC set up in Sigma. When you embed a Sigma agent in a chat element, you can do the following:

* Display different agents in different tagged versions of the same chat element.
* Embed just the chat element, instead of a full workbook.
* Restrict access to only specific data sources. Data sources not added to the agent are never available to users.
* Customize instructions to be specific to your organization and use case.
* Set a static greeting to manage token use and consumption credits.
* Apply any supported [embed URL parameters](/docs/embed-url-parameters) to customize appearance.

## Embed a chat element with an agent

To embed a chat element with an agent:

1. Open the workbook containing the chat element and agent that you want to embed.

2. Use the [embed sandbox](/docs/test-an-embed-url-in-the-embed-sandbox) to generate a URL, or select the chat element that you want to embed, then copy the URL and edit it to match the following structure. Use the value after the `:nodeId=` as the `<elementId>`:

   ```text
   https://app.sigmacomputing.com/<organizationSlug>/workbook/<workbookName>-<workbookId>/element/<elementId>
   ```

3. Apply any relevant [embed URL parameters](/docs/embed-url-parameters) to customize appearance.

4. Complete the steps in [Create an embed API with JSON Web Tokens](/docs/create-an-embed-api-with-json-web-tokens) to prepare a JWT-signed secure URL.

## Considerations for embedding an agent and chat element

* When you tag a version of a workbook, the agent in the workbook is also preserved as it was configured. If you swap sources for the tagged workbook, the agent's data sources are also swapped. If you want to iterate on an agent in a tagged version of a workbook, follow the steps to [make changes to a tagged document version](/docs/tag-a-document-version#make-changes-to-a-tagged-document-version).
* Chat history for an agent is specific to a chat element and user-scoped. Conversations are only available on the tagged version of the chat element, and only to the user that interacted with the agent.
* If you allow an agent to write to an input table as an action tool (for example, with the **Insert rows** action), make sure that the input table is set to **Editable only in published version (all users)** to prevent data from being copied when you tag versions of the workbook and to allow the agent to write to the table successfully when you embed the chat element.

## Example implementation

For example, embed an agent in a chat element to let each of your customers chat with an agent about their own usage trends, such as order volume or booking volume, without seeing usage data for other customers.

1. In a workbook, add a table protected by [row-level security](/docs/set-up-row-level-security) that contains usage metrics relevant to your customers.

2. In the same workbook, [create a Sigma agent](/docs/build-agents) and add the usage-metrics table as a data source.

3. Provide instructions to the agent with guidance like the following:

   ```text
   You are a usage analytics agent. Answer questions about order volume, booking volume, and related usage trends using only the data available to you. Never reference or compare data from other accounts.
   ```

4. Add a [chat element](/docs/build-agents#add-a-chat-element-to-interact-with-an-agent) to the workbook and select the usage analytics agent you created.

5. Publish the workbook.

6. Follow the steps to [embed a chat element with an agent](#embed-a-chat-element-with-an-agent). Include the relevant `user_attributes` or `teams` claims in the URL to enforce row-level security in the embed.

> **Tip**
>
> If you need a fully custom chat interface instead of an iframe embed, [call the agent with the API](/docs/call-agents-with-the-api) from your application's backend instead of embedding the chat element directly:
>
> * Use `stream: true` for a live chat experience.
> * To scope a request to a specific user, [impersonate that user](/docs/impersonate-users) for the API call

## Related resources

* [About Sigma agents](/docs/sigma-agents)
* [Build Sigma agents](/docs/build-agents)
* [Call Sigma agents with the API](/docs/call-agents-with-the-api)
* [Set up row-level security](/docs/set-up-row-level-security)
* [Impersonate users](/docs/impersonate-users)
* [Example use cases for Sigma agents](/docs/example-agent-implementations)