# Agent chat
> Work with MotherDuck in plain language. Ask the agent questions about your data, and have it load data with Flights, save business context in Guides, and build Dives. Learn how chats are saved and billed, and where model inference runs.
Agent chat lets you work with MotherDuck in plain language from the [MotherDuck UI](https://app.motherduck.com/). Tell the agent what you want, and it writes and runs the SQL and Python for you. It can answer questions about your data, and it can build the pieces that turn an answer into something your team keeps using:

- **[Flights](/key-tasks/flights/)** to load and transform data on a schedule.
- **[Guides](/key-tasks/guides/)** to record what your data means, such as metric definitions and which tables to trust.
- **[Dives](/key-tasks/dives/)** to share the results as interactive data apps. With [Dive apps](/key-tasks/dives/run-flights-from-dives/), your team can also act on the data, for example approve an order or refresh a pipeline, without leaving the Dive.

What the agent builds is saved in your organization, not in the chat. You can rerun a Flight, edit a Guide, or share a Dive after the conversation ends, and the next chat can build on it.

Start a chat from Home, where your chats are saved so you can come back to them, or open one beside a Dive.

## Availability

- **Paid plans and free trials.** Agent chat isn't available on the Free plan.
- **Organization Admins can turn it off.** Admins turn Agent chat on or off on the [AI Features](https://app.motherduck.com/settings/ai-features) page in Settings. Turning it off hides Agent chat across MotherDuck for everyone in the organization.

## Billing

Agent chat is billed in [AI Units](/about-motherduck/billing/pricing/#agent-chat-pricing), the same unit as [AI functions](/about-motherduck/billing/pricing/#ai-function-pricing), where 1 AI Unit = $1.00. Each message you send uses model tokens: the input the agent reads, such as your question, the conversation so far, and the query results it looks at, plus the output it writes. MotherDuck converts that token usage to AI Units and adds it to your bill with your other AI usage.

A short question about one Dive uses fewer tokens than a long chat where the agent explores many tables, runs many queries, or builds and edits a Dive. Starting a new chat for a new task keeps the agent from re-reading a long conversation.

Agent chat charges are separate from the [compute](/about-motherduck/billing/pricing/#compute-pricing) charges for the queries the agent runs.

Organization Admins and Builders can query [`MD_INFORMATION_SCHEMA.AGENT_USAGE`](/sql-reference/motherduck-sql-reference/md_information_schema/agent_usage/) to review AI Unit usage for each chat turn across the organization.

## Start a chat

[Home](https://app.motherduck.com/) opens with a prompt box. Type a question about your data, or ask for a Dive, and press Enter. The chat opens on its own page.

Your most recent chats are listed under the prompt. To see all of them, open **Chats**.

After you upload a file, you can also click **Dive deeper** in the upload dialog. That starts a chat where the agent builds a Dive from your new table.

## Saved chats

Chats you start from Home are saved to your account, so you can leave and pick them up later. They're private to you.

On the **Chats** page, you can:

- **Search** your chats by title.
- **Open** a chat to see its earlier turns and keep going where you left off.
- **Star** a chat to add it to **Favorites** in the sidebar, so you can get back to it in one click. Click the star again to remove it.
- **Rename** a chat from its **⋮** menu.
- **Delete** a chat from its **⋮** menu. Deleting is permanent and can't be undone.

Select **New chat** to start a new conversation.

Saved chats are only available in the MotherDuck UI. The agent can't look up your other chats, and AI tools you connect through the [MotherDuck MCP server](/key-tasks/ai-and-motherduck/mcp-workflows/mcp-setup/) can't list or read them.

## Chat with a Dive

Ask an AI agent questions to get answers to anything you want to know about a Dive. The agent sees the Dive's queries, the data behind them, and the view you have open, so you can drill into the numbers without writing SQL.

1. Open a Dive in the [MotherDuck UI](https://app.motherduck.com/).
2. Click **AI chat** in the top-right corner of the Dive.
3. In the chat panel, type a question, or pick a suggested one such as "What stands out in the current view?" or "How are these numbers calculated?"

Every message you send includes the Dive's current state, including the filters and selections you've applied so the answers are tailored to what's shown on your screen.

When you open a Dive from a saved chat, for example from a link in the agent's answer, the saved chat moves to the panel beside the Dive. Questions you ask there are added to the saved chat. To return to the full-page chat, select **Open full chat** in the panel's header.

### Chat in presentation mode

Agent chat also works when you present a Dive. Open the Dive's menu, choose **Open in presentation mode**, then click the AI Chat button in the presentation toolbar to open the chat beside the Dive. If you hide the toolbar, the chat panel stays open. Presentation mode opens in a new tab, so its chat starts empty and doesn't include the conversation from the Dive viewer.

## Load and transform data with Flights

Ask the agent to get data into MotherDuck or keep it up to date, for example "Load last year's public daily weather data from S3 into a table" or "Sync our Postgres orders table every morning." The agent writes a [Flight](/key-tasks/flights/), a Python job that runs in MotherDuck, then runs it and reads the logs to check that it worked. If a run fails, ask the agent why, and it can fix the code and run it again.

You can also ask it to schedule a Flight, change one, cancel a run, or delete a Flight you no longer need.

If a Flight needs credentials, such as an API key or a database password, the agent asks you to enter them in a form in the chat. MotherDuck saves them as a [secret](/sql-reference/motherduck-sql-reference/create-secret/), and the values aren't sent to the agent or kept in the chat.

## Save business context in Guides

The agent reads your organization's [Guides](/key-tasks/guides/) before it answers, so it uses your definitions instead of guessing. When a question depends on a term that could mean several things, like "active customer," the agent asks which one you mean and can offer to save the answer to a Guide. You can also ask it directly, for example "Write a Guide that explains how we calculate MRR."

Guides can be private to you or shared with your organization. The agent doesn't create or change a Guide unless you ask, and it checks with you before it shares one with your organization.

## Create and edit Dives

Ask the agent to build a Dive or change one in plain language. The agent writes the Dive's code and queries for you.

- **Create a Dive.** Describe what you want to see, for example "Make a Dive of weekly sign-ups by region."
- **Edit the Dive you're viewing.** Ask for a change such as "Add a chart of revenue by month," "Change the date filter to the last 90 days," or "Fix the query behind the second chart."
- **Turn it into a Dive app.** Ask for buttons and forms that do something, for example "Add an Approve button to each pending order" or "Add a Refresh button that reruns the sync." The agent writes a Flight that does the work and connects it to the Dive, so your team can act on the data without leaving it. See [Build Dive apps](/key-tasks/dives/run-flights-from-dives/) for how it works and who can run the Flight.
- **Update its title and description.** Ask the agent to rename the Dive or rewrite its description.
- **Share the data behind it.** A new Dive is private, so first [share the Dive](/key-tasks/dives/#choose-who-can-open-a-dive) with your teammates, or ask the agent to share it with a role or with your organization. If it queries databases you own that aren't shared with your organization, they still can't see its data. Ask the agent to [share the Dive's data](/sql-reference/mcp/dives/share-dive-data/), and it will create organization-wide [shares](/key-tasks/sharing-data/sharing-overview/#creating-a-share) for those databases. You need to own the Dive.
- **Delete a Dive.** Ask the agent to delete a Dive you no longer need. Deleting is permanent and can't be undone.

After each change, the agent shows you the Dive so you can check the result. In a Dive's chat panel, the Dive reloads with the change. In a chat on its own page, the Dive appears in the chat under the agent's answer. Every edit saves a new version. Earlier versions are preserved in the Dive's [version history](/key-tasks/dives/#version-history).

## How conversations work

- **It works as you.** The agent uses your account's permissions, so it can only see and change what you can.
- **It changes data only when you ask.** The agent reads your data to answer questions. It writes to tables or databases only when you've asked for that change, and before anything destructive, such as dropping a table or replacing data, it explains what it will do and waits for you to confirm.
- **Chats from Home are saved. A Dive's own chat isn't.** A chat you start in a Dive's panel lives in your browser tab only, and reloading or closing the tab clears it. A [saved chat](#saved-chats) that you open beside a Dive stays saved.
- **Long chats are compacted.** When a conversation gets long, the agent summarizes the earlier turns so it can keep going. You'll see "Compacting conversation…" while it does this.

## Data processing and regions

Agent chat uses models hosted on Amazon Bedrock. Where model inference runs depends on your organization's [cloud region](/about-motherduck/cloud-regions/#agent-chat).

Amazon Bedrock has a zero data retention policy and does not share your prompts or data with model providers.

For what each MotherDuck AI feature sends to a model and how admins turn features off, see [AI features and your data](/about-motherduck/ai-and-your-data/).

## Web search

Admins can let the agent search the web, for example to look up public information that isn't in your data. Turn on **Web Search for Agent Chat** on the [AI Features](https://app.motherduck.com/settings/ai-features) page in Settings. It's off by default, and it isn't available on the Free plan.

Web search is provided by Context.dev, and requests from your organization are processed in the United States, whatever your organization's cloud region.


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fkey-tasks%2Fai-and-motherduck%2Fai-in-the-ui%2Fagent-chat%2F&page_title=Agent%20chat&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.
