Sessions and tools in Maia AI Agents🔗

A session is an ongoing, structured interaction between you and Maia AI Agents. A session includes your full conversation history, relevant context, and any tool based actions Maia AI Agents have performed on your behalf, all within the current Designer branch.

Sessions are designed to help you work more efficiently. They are:

Context-aware: Maia AI Agents build on prior messages within the same session, allowing for more coherent, informed responses across multiple prompts.
Session-scoped: Your chat with Maia AI Agents remains active and visible in the Maia AI Agents panel as long as you're working in the same Designer project and branch. Once you close a branch, your conversation is saved in your conversation history.
Resettable: If you'd like to start fresh or you're seeing unexpected behavior, click the New Chat icon in the top-right of the Maia AI Agents panel to clear the current session and begin a new conversation.
Private: Your conversations with Maia AI Agents are only visible to you. When you open a branch, the recent conversations you see in your conversation history are your own.

Maia AI Agents sometimes need more context to get things right, particularly when planning pipelines or working on complex prompts. When Maia AI Agents need more information from you, they will present clear, structured questions to help clarify how to respond to your prompts. These can be:

Multiple choice questions: Choose from predefined options, or provide your own answer with the "Other" option.
Multi-step forms: When Maia AI Agents need to ask several questions, they will present them one at a time with step-by-step navigation.

Note

You can switch between pipelines in the same branch without losing session context. However, switching branches will close your session and save your conversation in the conversation history.

If Maia AI Agents appear to misunderstand your intent or lose context, use New Chat to reset and start a clean conversation. If you have a long conversation with Maia AI Agents, they may summarize your chat so far, and then continue. If this happens, we recommend starting a new chat the next time you start to discuss a new topic with Maia AI Agents.

Plan mode🔗

You can chat with Maia AI Agents about your pipeline without making any changes to it using Maia AI Agents' plan mode. Plan mode provides you with extra visibility and control over Maia AI Agents' suggested actions, which can be useful when working on complex pipelines, and enables you to suggest changes to Maia AI Agents' approach before any work is performed on your pipelines. To use plan mode, switch on the Plan mode toggle at the bottom of Maia AI Agents' chat interface.

Maia AI Agents will automatically suggest switching to plan mode if they think your prompt is complex enough to require planning. When this happens, you will see a message in the Maia AI Agents chat interface—click Accept to allow Maia AI Agents to use plan mode.

When plan mode is active, Maia AI Agents can analyze your pipeline and explore your data warehouse, then present a multi-step plan to achieve your goal without making any changes to your pipeline. You can then suggest changes to the plan if needed, or accept Maia AI Agents' suggestion. Maia AI Agents will only make changes to your pipeline after you have approved their suggested plan.

Expand this box to watch our video about using Maia AI Agents' plan mode.

Video

Visualizing data🔗

Maia AI Agents can visualize the data they sample in a component directly in the chat interface. These visualizations enable you to discover key insights and identify trends. To visualize your data in the Maia AI Agents interface, prompt Maia AI Agents to create a chart or graph representing the data in a specific component.

These visualizations are based on sampled data and include between 10 and 20 rows, not the entire dataset. For more information about how Maia AI Agents samples data, read Sampling data.

Conversation history🔗

Maia AI Agents automatically save your recent conversations, making it easy to continue where you left off or revisit previous work. This ensures that important context and progress aren't lost when you need to step away or switch tasks. Conversation history is tied to your current branch, and you can only view your own conversation history on each of your branches. Switching to a different branch will show conversations specific to that branch.

Note

For the best results, we recommend starting a new chat for each distinct task or pipeline project. This helps Maia AI Agents provide more focused, relevant assistance while still allowing you to return to previous conversations when needed.

When you open the Maia AI Agents chat panel, you'll see the titles of your most recent conversations from the past three days displayed in the Branch conversations section, as shown in the image below. Maia AI Agents dynamically update the title of your conversation as you work, so that it always reflects the topic you're discussing. To view more conversations and resume any of them, you can:

Click See more above the two most recent conversations when you first open the Maia AI Agents chat interface.
While chatting with Maia AI Agents, click Chat history in the top right of the chat interface.

When you select a previous conversation, Maia AI Agents load the complete chat history and you can continue exactly where you left off. To start a completely new conversation instead, type a message in the chat input field when it opens.

Renaming and deleting conversations🔗

You can rename and delete your previous conversations with Maia AI Agents. Renaming a conversation makes it easier to find useful pipeline information or data analysis, while deleting conversations lets you clear conversations you no longer need.

To rename or delete a previous conversation, click the three dots ... next to the conversation name, and then click Rename or Delete as shown in the image below. If the conversation you want to rename or delete is not one of your two most recent conversations, click See more above the recent conversations to open your conversation history.

File exploration🔗

Maia AI Agents can search through and explore files in your project, making it easier to understand existing work, find specific configurations, or perform project-wide updates.

Maia AI Agents' file search capabilities help you:

Locate specific files: Find pipeline files, scripts, or documentation by name or pattern.
Discover existing components: Find configured components to copy or reference.
Validate project-wide changes: Ensure parameters or configurations are updated everywhere they're used.
Understand your project structure: Get an overview of what files and pipelines exist in your project.

For example, you could prompt Maia AI Agents as follows:

"Find all transformation pipelines that connect to the "product-orders" table."
"Show me any existing Salesforce load components I can copy."
"Find every time the database name 'PROD_DB' is mentioned."
"Summarize the content of the pipeline files in the analytics folder."

Search performance🔗

For larger projects with many files, searches may take longer to complete. Maia AI Agents will let you know when they're working on your search request. Using file search is much more efficient than having Maia AI Agents view each file individually, especially when you need to:

Perform large-scale refactors across multiple pipelines.
Check whether changes were applied consistently throughout your project.
Find specific patterns or configurations across many files.

Slash commands🔗

Slash commands are a command-line interface (CLI) style method of interacting with Maia AI Agents. These commands simplify complex prompts into a one-word command to standardize common tasks. The table below explains what Maia AI Agents will do as a response to each slash command.

To use a slash command, type a forward slash / in the Maia AI Agents chat interface, followed by the command you want to give. After you type /, an autocomplete list of available slash commands will appear. After typing the command, enter the name of the object that you want Maia AI Agents to process—you can use the @ symbol here to mention a specific file in your project. For example, you could prompt Maia AI Agents "/document the customer_data folder", "/explain this pipeline" or "/fix @weekly_orders".

Command	Maia AI Agents' task
`/document`	Generate a Markdown file containing information about a specified pipeline, file or directory. The information Maia AI Agents provide will include a summary of the file, the components used (when documenting a pipeline), how to use the file, and important information like dependencies and performance considerations.
`/explain`	Generate a brief explanation of a specified pipeline or concept. The information Maia AI Agents provide will include a short explanation of the pipeline's purpose, data flow, and key components.
`/fix`	Identify issues in a specified pipeline and suggest ways to fix them. Maia AI Agents will determine the cause of any errors or configuration problems in the pipeline and present you with options to resolve the issues. Maia AI Agents will not take any action until you approve one of the options presented.
`/multi-table-load`	Load multiple tables from a data source using incremental or full load.
`/notes`	Add notes to a specified pipeline. Maia AI Agents will add notes to the Designer canvas with information about the purpose of components, the data flow in the pipeline, any potential issues, and opportunities for optimization.
`/optimize`	Analyze a specified pipeline and suggest opportunities for optimization. The suggestions Maia AI Agents provide can include information about generic SQL that could use specialized components, opportunities for parallelization, and performance bottlenecks. Maia AI Agents will not make any changes to your pipeline until you approve one or more of their suggestions.

Video example🔗

Expand this box to watch our video about using Maia AI Agents' Slash commands.

Video

Tools🔗

Maia AI Agents use tools to perform tasks in your Designer workspace based on your prompts. These tools let Maia AI Agents go beyond chat and perform real, interactive actions.

Maia AI Agents tools allow them to:

Create and modify orchestration or transformation pipelines.
Add and configure pipeline components.
Search for tables in your data warehouse.
Preview or sample table data.
Run pipelines and monitor their status.

Note

Tools let Maia AI Agents take real actions in Designer, not just respond with suggestions for you to take yourself. These actions include building pipelines, configuring components, and running tasks directly in your workspace.

Tool permissions🔗

For security and transparency, Maia AI Agents ask you for explicit permission before using tools that can affect your work. When relevant, you will see a permissions dialog in the Maia AI Agents chat interface. You can:

Accept: Approve the action for a one-time use.
Accept for session: Allow Maia AI Agents to repeat this action without asking again during the current session.
Decline: Deny the request and optionally provide a reason for declining. This helps Maia AI Agents adjust their response or better understand your prompt.

This permission-based model ensures that you stay in control while enabling Maia AI Agents to act confidently on your behalf.

Background notifications🔗

Background notifications enable Maia AI Agents to notify you when they finish a task or require your input, such as requiring permission to sample data. This means you can give Maia AI Agents a prompt, then switch to a different browser tab or program while Maia AI Agents are working, and resume your task as soon as Maia AI Agents finish.

Background notifications are provided as:

Tab indicators: A dot in the browser tab title.
Audio chimes: A notification sound.
Browser notifications: A system-level notification, if you grant Maia permission to show browser notifications.

To activate background notifications:

In the Maia AI Agents chat interface, click the three dots in the top right to open the Settings drop-down.
Enable the Notifications toggle.

Canceling the current prompt🔗

If you want to cancel Maia AI Agents' current response, click Cancel—this icon appears in the input field of the Maia AI Agents chat interface when Maia AI Agents are responding to a prompt. This stops the current response but keeps your session open. You can continue the conversation or ask something new immediately. Canceling a task does not clear the conversation history.