Build Sigma agents (Beta)

Build Sigma agents in a workbook to provide AI capabilities to a dashboard or application based on selected context. Instructions and data sources provide context to the agent, while actions, warehouse agents, warehouse search services, and MCP tools provide tools for an agent to take action or enrich insights.

You can build agents specific to business tasks, like forecasting different sales promotions, or summarizing the status of an incident in a debugging app. For more examples, see Example use cases for Sigma agents.

After you build an agent, you can schedule it to run automatically, or add a Chat element for users to interact with the agent using natural language in a conversational interface.

User and system requirements

To build a Sigma agent in a workbook, you must have the following:

• The Manage agents and Create, edit, and publish workbooks permissions enabled on your account type
• Can edit access to the workbook

Your Sigma organization must have an AI provider configured. See Set up an AI provider. The configured AI provider is used for all AI functionality in Sigma. Agents that you build can run with an external AI provider or a warehouse-hosted model as an AI provider.

Limitations of Sigma agents

When building AI agents in Sigma, consider the following limitations:

• You can trigger an agent to run as part of an automated action sequence, but not from an action sequence triggered on select or on click.
• An agent can exist in only one workbook.
• An agent does not have context about data elements that do not exist in the workbook and are not made available to the agent.

Data security for agents

When a user interacts with an agent, the agent can access the same data that the user can access in the workbook. Agents respect role-based access control (RBAC). Agents can only use tools that the user has access to or permission to use.

💡

When the agent queries data from data sources, the queries are run on behalf of the user that interacted with the agent. As a result, performance benefits from Alpha Query and query caching also apply to queries run by agents.

Build an agent in a workbook

To build an agent in a workbook:

1. Open an existing workbook for editing, or create a workbook from Sigma Home by choosing Create new > Workbook.

2. In the editor panel, select Agents, then click Add agent (+).

   A Configure agent modal appears.

3. Next to the placeholder agent name (Agent 1) select (Rename agent) to provide a descriptive name for the agent. Press Enter to save the name.

   💡

   At any time, you can use the Agent builder assistant () to write instructions, add data sources, and set up action tools. Where prompted with How can I help you build your agent?, enter a question or prompt. Select + to add data sources or tools to the agent, and @-mention data sources or tools available to the agent in the conversation with the agent builder assistant.

4. Add one or more data elements from the workbook that the agent can use as context. For Data sources, click Add data source (+). See Add data for the agent.

5. Add tools that the agent can use to perform actions, retrieve additional context, call warehouse agents, search a warehouse search service, and more. For Tools, click +, then choose an option:

   • Select Action to add one or more actions or action sequences that the agent can run in the workbook. See Set up actions for the agent.
   • If you have a Snowflake Cortex Agent or a Databricks Genie Space in your connected data platform, select Warehouse tool, then select Warehouse agents to add the warehouse agent as a tool for the Sigma agent. See Set up warehouse agents as tools for the agent.
   • If you have a Snowflake Cortex Search service available in a Snowflake connection or a Databricks AI search index available in a Databricks connection, select Warehouse tool, then select Search services to add the search service as a tool for the Sigma agent. See Set up warehouse search services as tools for the agent.
   • If you have an MCP tool configured in Sigma, select MCP tool, then add the MCP server as a tool for the Sigma agent. See Add an MCP tool to a Sigma agent.

6. In the Instructions section, provide instructions and context to the agent about its tasks and when to use the configured tools. See Add instructions for the agent.

7. When you are satisfied with your agent, click Save.

You can build multiple agents in a workbook. After building an agent, add a chat element to allow users to interact with the agent, or schedule the agent to run automatically.

Add data for the agent

Add data to the agent that it can use as context when answering questions and responding in chat conversations. Data sources must already be added to the workbook.

1. When creating or editing an agent, for Data sources, click + (Add data source) to add one or more data elements from the workbook to provide context to the agent. You can add a table, pivot table, chart, input table, or linked input table element in the workbook.

   When adding a data source, consider the following:

   • Data sources can be from different connections. The agent can use any of the specified data sources to respond to questions and prompts in a chat.
   • If the data source contains metrics, and the columns used by the metric are visible in the data element, the agent can use the metrics.
   • If the data source for the agent is sourced from a data model, the agent cannot access related columns or metrics available through relationships.
   • Agents use metadata on data sources as part of their context. High-quality metadata can improve agent results. Make sure elements and columns have descriptive names and include column descriptions and element descriptions where relevant. For details about high-quality metadata, see Data modeling best practices.

2. After you add data sources, add tools or instructions, or click Save to save the agent and return to editing the workbook.

Set up actions for the agent

The agent can run actions in the workbook as tools. When you create an action tool for an agent, you can define a set of deterministic steps to be performed when the tool is called. Each step can do one of the following:

• Run an action.
• Trigger an action sequence defined in the workbook, if the action is associated with an "On click" action. For example, actions triggered when clicking a button.

💡

In your workbook, rename action sequences to more descriptive names to make it easier to locate specific sequences when adding them as tools for the agent.

To add an action tool for an agent:

1. When creating or editing an agent, for Tools, click + (Add tool), then select Action.

2. By default, the tool is Untitled. For Name, enter a name for the tool. Specify a name that makes it clear what the tool does.

3. For Instructions, enter instructions for the agent about what the action tool does and how to use the tool. For example, describe a tool that sends a notification to a Slack channel about the current state of the agent conversation with: "Summarize current state of the chat conversation for teammates in Slack. Format the response using Slack-specific mrkdwn syntax instead of HTML or Markdown.".

   💡

   The agent uses the tool name and instructions to decide when to use the tool.

4. (Optional) To prompt the user to approve the tool before it runs in a chat conversation with the agent, select No approval required and select Requires approval. When a user is prompted for approval, the name and any step names for the action tool are shown in the chat conversation. If the agent is scheduled to run automatically, approval prompts are skipped.

   💡

   An agent can run an action tool with or without approval. The best option depends on the importance of data governance to your use case and how much autonomy you want to give the agent:

   • Restrict agent autonomy with strict human-in-the-loop review: Require user approval for the action.
   • Guided agent autonomy without review: Do not require user approval for the action. Guide the agent behavior with action tool instructions and guidance for agent input placeholders.

5. For Steps, click Add step (+).

6. For the step, select a Step type. Choose between Run an action and Trigger an action sequence, if one exists.

   • If you choose Run an action, for Action, select the action to perform in this step, then complete the relevant fields for the action.
   • If you choose Trigger an action sequence, for Sequence, select the action sequence in the workbook that you want to trigger. The sequence must be one triggered "On click".

   💡

   If your action tool outputs data, such as by inserting or updating a row in an input table, setting form field values, or setting control values, you can choose the Agent input option to allow the agent to provide the input for the action. After selecting Agent input, you can replace the placeholder text with further instructions to the agent about what information to enter.

   For examples, see Example: Add conversational memory as an action tool.

7. Repeat steps 5 and 6 to add more steps to the action tool.

8. After you finish adding action tools, add instructions with guidance about when to call the tool. For example:

   Text

   When prompted to send an email update, use the "Notify leadership of recent updates" action tool.

9. Click Save to save the agent and return to editing the workbook.

Set up warehouse agents as tools for the agent

If you have a Snowflake Cortex Agent or a Databricks Genie Space set up in a connected data platform, your Sigma agent can call one or more to perform tasks. Using a warehouse agent like a Snowflake Cortex Agent or Databricks Genie Space, you can give the Sigma agent context about data that exists only in your data warehouse, and doesn't exist in Sigma or in the workbook that the Sigma agent is operating in. For requirements and setup steps, see Use warehouse agents with Sigma.

💡

A Sigma agent can function as an orchestrator, instructing a set of warehouse agents to perform narrowly scoped tasks on specific data sources, and summarizing the responses to inform further analysis or take action in Sigma.

User permissions

A Sigma agent respects role-based access control of the user interacting with the agent. To use a warehouse agent:

• You must be granted Can use access to the warehouse agent, schema, database or catalog, or connection that contains the agent.
• If you connect to Snowflake using OAuth and want to use a Snowflake Cortex Agent, your role must be granted USAGE privileges on the agent in Snowflake.
• If you connect to Databricks using OAuth and want to use a Databricks Genie Space, your role must have CAN VIEW or CAN RUN on the Genie Space in Databricks.

If you do not have access to the warehouse agent, the Sigma agent cannot use it.

Add a warehouse agent to a Sigma agent

1. When creating or editing an agent, for Tools (+), select Warehouse tool.

2. Search for and select one or more warehouse agents.

   📘

   If you do not see any warehouse agents, or an agent that you expect to see is not listed, make sure that your connection is updated and that you are using a role with access to the agent. If you sync the connection, you must sync both the database or catalog and schema that contain the agent. For more details, see Manually sync your data.

3. After selecting the warehouse agent, review the Connection path to confirm that you selected the correct agent.

4. For Description, provide instructions about what the warehouse agent can do and when to call the warehouse agent.

5. After you add warehouse agents, add instructions. For example, add instructions for when to use a warehouse agent:

   Text

   When prompted for details about recent sales, use the RECENT_SALES agent.

6. Click Save to save the agent and return to editing the workbook.

Set up warehouse search services as tools for the agent

If you have a Snowflake Cortex Search service set up in a Snowflake connection or a Databricks Vector Search, your Sigma agent can use it as a search tool.

A warehouse search service uses retrieval-augmented generation (RAG) to perform low-latency semantic search across text-intensive columns in a warehouse table. Use a warehouse search service when you want the agent to answer questions grounded in text-heavy data in your warehouse, such as support ticket transcripts or product reviews. By setting up a search service and adding it as a tool for the Sigma agent, instead of querying a full data source and reasoning across every row, the agent retrieves the most relevant rows from the search service to inform a response, which can improve agent response time for large or unstructured datasets.

When you add a search service to a Sigma agent as a tool, the agent can access data in the data platform that is available to the service, even if the data is not available in the workbook as a data element. However, role-based access controls are always respected.

User requirements

The agent can only use warehouse search services that the user accessing the agent can access:

• For a Snowflake Cortex Search service, the role of the querying user must have USAGE privileges on the search service and the database and schema that contain the service. For more details, see Access control requirements in the Query a Cortex Search Service page of the Snowflake documentation.
• For Databricks AI Search, the user must have SELECT privileges on the vector search index, and both USE CATALOG on the catalog that contains the vector search index and USE SCHEMA on the schema that contains the vector search index. For more details, see How to query a vector search index in the Databricks documentation.

For example, if a user chatting with the Sigma agent does not have a role with USAGE privileges on the search service in Snowflake, the agent cannot use the Cortex Search service.

Add a warehouse search service

To add a warehouse search service to a Sigma agent:

1. When creating or editing an agent, for Tools (+), select Warehouse tool.

2. Select Search services.

3. For Connection, select a Snowflake connection that contains a Cortex Search service, or a Databricks connection that contains a vector search index.

4. For Search service, select a search service from the connection.

   💡

   The search service can index any table in the connection. The underlying table does not need to be added to the workbook as a data element or to the agent as a data source.

5. (Optional) For Description, provide guidance about when the agent should use the search service. The agent uses this description to decide when to call the tool.

6. After you add the warehouse search service, add instructions. For example:

   Text

   When asked about the contents of customer support tickets, use the SUPPORT_TICKETS search service to retrieve relevant tickets.

7. Click Save to save the agent and return to editing the workbook.

Add an MCP tool to a Sigma agent

Use an MCP server to add context to your conversation, retrieve ad hoc data, or permit the agent to take action in third-party tools. Before you can add an MCP server to a Sigma agent, configure it as an MCP tool in Sigma.

📘

To add an MCP tool to a Sigma agent, you must be assigned an account type with the Use MCP tools permission enabled and you must have Can use access to the MCP tool.

To add an MCP tool to a Sigma agent, do the following:

1. When creating or editing an agent, for Tools (+), select MCP tool.

2. Search for and select the relevant MCP tool.

3. After you add MCP tools, add instructions about when to use the MCP tool. For example:

   Text

   When asked questions about the latest brand styles, use the Microsoft WorkIQ SharePoint MCP tool to connect to SharePoint and retrieve details from the Branding Guidelines file.

4. Click Save to save the agent and return to editing the workbook.

For more details about MCP tools, see Add MCP tools to Sigma.

Add instructions for the agent

Add instructions for the agent to provide relevant context and guidance to help the agent function how you want. Enter @ to mention data sources, tools, or formulas to the instructions. To increase the likelihood of high-quality agent performance, follow these best practices:

• Describe the role of the agent and the tasks it can perform.
• List any rules it should follow.
• Provide guidance for when to use different tools or data sources, but avoid duplicating instructions specified for action tools.
• Reference data sources by name.
• Reference control values with a formula that references the control ID.

When instructions are changed (including formula output), active chats with the agent refresh.

💡

At any time, you can use the Agent builder assistant () to write instructions, add data sources, and set up action tools. Where prompted with How can I help you build your agent?, enter a question or prompt. Select + to add data sources or tools to the agent, and @-mention data sources or tools available to the agent in the conversation with the agent builder assistant.

Examples:

• Example tool guidance instructions
• Example added context instructions
• Example response format and structure instructions
• Example response content instructions

Example tool guidance instructions

• Mention different tools configured to run actions or retrieve data, with additional guidance for the agent about when to run different tools. Enter @ to @-mention a specific tool.

  For example, guide the agent about when to use an action tool:

  If a question requests more details about a row of data, use the View Details action tool in the response.

  Or provide explicit instructions about when to use an agent from a data platform connection:

  If a question mentions the word "sales", use the Sales Insights Genie Space.

  Or provide context about when to call an MCP tool:

  To confirm that a recommendation complies with the company sales & promotion policy, use the Sharepoint MCP server "get document contents" tool to retrieve the sales and promotion policy details from the **Promotion Regulations** Microsoft SharePoint folder.

Example added context instructions

• Add organization-specific context, such as the fiscal year quarters that your organization uses to conduct business or the names of subsidiary organizations.

• Define specific user context by adding formulas that reference, for example, the current user's full name:

  When possible, address the user chatting with you by name: CurrentUserFullName()

• Provide factual information by adding formulas that reference the current day or time:

  If asked for the time, or when using temporal language, use the time: Now()

• Pass additional context by retrieving values from control elements in your workbook with a dynamic text formula.

  For example, if you have a list values control with an ID chatbot-tone with 3 manually provided options: one "short and sweet", another "professional tone", and another "term paper length", reference the control value in the instructions using a formula:

  When responding, use the following tone: [chatbot-tone]

  Then a user can choose the desired tone of the agent using the list values control, and the instructions can pull the user selection from the control and use the selected tone when responding to the user.

Example response format and structure instructions

• Instruct the agent with desired response details, such as output structure to use, desired response length, or information to include:

  If asked to summarize findings, respond in no more than 5 bullet points and use action verbs. Always include a title of "Summary".

Example response content instructions

• Increase the likelihood that the agent generates responsible insights by instructing the agent to cite sources:

  When asserting a fact, include a reference to the source of the fact. If you provide a link to relevant documentation page or a webpage, make sure that the page is accessible on the web before providing it.

  Also, provide explicit instructions to avoid off-limits topics:

  Never provide investing advice or guidance, even if asked for it. Instead, politely decline.

Add a chat element to interact with an agent

After building an agent, add a chat element to allow users to interact with the agent:

📘

To add a chat element, you must have Can edit access to the workbook and the Create, edit, and publish workbooks permission enabled on your account type. You do not need the Manage agents permission to add a chat element.

1. Open a workbook for editing.

2. In the Add element bar, select UI > Chat.

3. Select the chat element.

4. In Connect an agent, select an agent.

5. Publish the workbook to save the default agent selection.

   The chat element displays content relevant to the instructions, inviting a user to interact with the chat element. See Chat with an agent in Sigma.

Format a chat element

Chat elements support element formatting. Select the Format tab to configure the following:

• Padding
• Border
• Corner

Call an agent on a schedule with an action

You can call an agent as part of an automated action sequence to automate multi-step workflows that gather data, generate structured output, and trigger downstream actions without any user interaction.

When an automated action sequence calls an agent, the agent runs once with the prompt included with the configured action, then runs its available tools (such as querying data sources), and returns structured output. The output is structured as action variables that you can reference in following actions in the sequence.

A typical automated action sequence that calls an agent might look like the following:

1. Call agent: The agent receives instructions to query multiple data sources and return structured output, such as a summary and description. See Create actions that interact with agents.
2. Update input table: An insert or update row action writes the agent's output, passed as action variables, to an input table for a persistent record. See Create actions that modify input table data.
3. Send notification: A notification action uses the action variables to send the summary and description to a Slack channel, Microsoft Teams, or email. See Create actions that send notifications and export data.

For a complete example, see Example: Nightly usage summary agent.