> ## Documentation Index
> Fetch the complete documentation index at: https://help.teable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Chat

> Interact with your data using natural language for analysis, visualization, and creation.

<Note>Available on all Cloud plans; Self-Hosted requires Business or higher.</Note>

AI Chat helps analyze the current table, explain record content, generate charts and reports, and create or update tables, views, apps, and automations.

AI prioritizes the current page. To reference other tables, views, apps, automations, or folders, type `@` in the input box and select the related node.

## How to Open

Open a table or view, then click the <img src="https://mintcdn.com/teablecn/TO9j-Q8_3sjEReNV/images/docs/ai/cuppy-icon.svg?fit=max&auto=format&n=TO9j-Q8_3sjEReNV&q=85&s=1e7abd74de22dba2ee1e4bb40c1ca2d0" alt="Cuppy" className="docs-inline-icon" width="72" height="72" data-path="images/docs/ai/cuppy-icon.svg" /> in the top right corner to open AI Chat. Describe the question or task in the input box. If the task will modify data or create nodes, ask AI to list the plan first, then confirm before execution.

## What AI Can Reference

AI prioritizes information from the current page:

* **Current table and view**: The current table, current view, and the filtered or sorted results in that view.
* **Selected rows, columns, and cells**: If rows, columns, a single cell, or a cell range are selected in Grid view, AI uses that selection as key context.
* **Uploaded files**: Add PDFs, Excel files, Word documents, images, and other files to the conversation.
* **More nodes with `@`**: Type `@` in the input box to add tables, views, apps, automations, or folders from the tree.

Files can also be pasted or dropped directly into the input box. They appear as attachment chips first, then become available to AI after the message is sent.

When you paste a long block of plain text, Teable converts it to a Markdown attachment so the message input stays easy to read. You can preview text and Markdown attachments from their attachment chips.

## Input Controls

* **Voice input**: Click the microphone button in the input box and allow microphone access to start recording. While recording, choose **Finish voice input** or **Discard voice input**. After you choose finish, Teable transcribes the recording into the input box.
* **Model**: Use the model menu to choose the model for the conversation. Use a lighter model for simple queries, cleanup, or rewriting, and a stronger model for complex planning, cross-table analysis, and app building.
* **Intelligence**: Choose the **Intelligence** level separately in the model menu. It controls thinking depth; higher levels produce more thorough reasoning.
* **Secrets**: Open the **+** menu and choose **Secrets** to store API keys or other credentials for AI Chat. AI Chat can read these values as environment variables. Saved values are write-only; enter a new value to update a secret.
* **Integrations**: When AI needs access to a third-party account, it can show a card such as **Connect Slack** in the conversation. Click **Connect** to authorize with OAuth. Click **Skip** to cancel this authorization; AI continues with the parts it can complete without that connection.
* **Skills**: Open the **+** menu and choose **Skills** to import, enable, disable, or try skills in the current chat. When you import one, choose who can use it: **Personal** keeps it to yourself, **Base** gives it to collaborators in this base, and **Space** gives it to everyone in this space. Type `/` in the input box to choose an enabled skill. To connect or migrate an external system, see [Connect & Migrate Everything](/en/basic/ai/connect-everything).
* **Context usage**: The ring next to the input box shows how much of the model's context window the conversation currently uses. Click it for the percentage and token counts. When the context fills up, Teable compacts the conversation; start a new chat if you want a clean context instead.
* **Manage files**: Open **+** → **More** → **Manage files** to view files in the current chat sandbox. You can preview supported files, download files, or delete files and folders you no longer need. A conversation must exist before its files can be managed.
* **Queued messages**: If you send another message while AI is still working, the message is queued. Queued items show the same table, view, attachment, and selection chips as the chat input. Use **Edit** to move a queued item back into the input, **Send follow-up without interrupting** to add a text follow-up to the current run when that action is available, or **Remove** to delete it from the queue. Items that cannot be sent as follow-ups stay queued until the current run finishes.

## Common Uses

<CardGroup cols={2}>
  <Card title="Create tables and automations" icon="sitemap">
    Plan a business database, create tables, views, apps, automations, or update existing records.
  </Card>

  <Card title="Analyze data" icon="chart-line">
    Summarize data in the current table or view, or analyze across multiple related nodes.
  </Card>

  <Card title="Charts and reports" icon="chart-pie">
    Turn queried data into a chart, report, or small interactive page you can reopen and share.
  </Card>

  <Card title="Read files" icon="file-lines">
    Answer questions using PDFs, Excel files, Word documents, images, and other attachments.
  </Card>
</CardGroup>

### Create Tables and Automations

AI Chat can help create, update, and organize data, not only answer questions. For a new business workflow, discuss the data structure first, then ask AI to create the tables, views, apps, and automations.

Suitable prompts include:

* Help me plan a customer follow-up system. What tables and fields do I need?
* Based on the plan above, create these tables, views, and fields.
* Add priority, assignee, due date, and status fields to the task table, then create common views.
* Change the selected records to Completed.
* Create a new table from this Excel file and check whether the field types are appropriate.
* Create a CRM app from this customer table, with customer list, customer detail, and follow-up record pages.
* When a new order is created, notify the owner and include the order number, customer name, and amount.

For a complete business database, start by asking AI to plan the table structure. After reviewing the plan, continue with table, view, app, and automation creation.

<Steps>
  <Step title="Plan first">
    Describe the business goal, such as building a customer follow-up system, and ask AI to outline the required tables, fields, views, and automations.
  </Step>

  <Step title="Confirm the structure">
    Review the proposed tables, fields, field types, and relationships. Add any missing rules or workflow details.
  </Step>

  <Step title="Create next">
    Ask AI to create the confirmed tables and views, then continue with apps or automations.
  </Step>
</Steps>

For app creation details, see [App Builder](/en/basic/ai/app-builder). For automation details, see [Automation](/en/basic/automation).

### Analyze Data

Ask questions about data in the current table, for example:

* Count completed tasks this month by assignee.
* Find the customers with the highest sales in the past 30 days.
* Analyze unusual records in this view.

If the question involves multiple tables, use `@` to add the related tables or views to the conversation.

In Grid view, you can also select rows, columns, a single cell, or a cell range, then use **Add to Chat** from the context menu. The selection appears as a chip in the input box, and clicking the chip highlights the related grid area again. Column chips use field names when available and shorten long selections after the first few names.

### Create Charts and Reports

Ask AI to turn queried data into a chart, a written report, or a small interactive page:

* Generate a weekly sales trend chart.
* Turn this query result into a pie chart.
* Create a summary report from these records.

AI builds these as **artifacts**: they appear as a card in the conversation, open in their own viewer, and stay available after the conversation ends. See [Artifacts](#artifacts) for what you can do with one.

<Info>
  An artifact holds the data AI put into it when it was created, so it does not refresh on its own. For a page that keeps reading live table data, or that collects input and stores state, create an app with [App Builder](/en/basic/ai/app-builder).
</Info>

### Read Files

After uploading files, AI can answer questions using both file content and table data:

* Summarize this PDF and connect it with the current customer record.
* Read this Excel file and identify the fields that should be imported.
* Generate a product description from this image.

Files uploaded to the conversation and files generated during the conversation are saved in the current chat sandbox. Use **Manage files** to inspect them later.

When a reply presents several files at once, use **Download all** below the file cards to save them as one zip.

### Memory

Memory stores information you explicitly ask Cuppy to remember. Memory is scoped by user and Base: each user in each Base has an independent memory context, and memory saved in another Base will not automatically appear in the current one.

* Save memory in the current Base

Say what Cuppy should remember in the conversation:

```text theme={null}
Please remember xxx.
```

* Reuse memory from another Base

Ask Cuppy to read another Base and save the relevant parts into the current Base:

```text theme={null}
Cuppy, please read the memory for Base ID bsexxxxxxxxxxxx and save the relevant memory into this current Base.
```

### Handle Long Tasks

AI Chat can keep a single conversation environment available for about 24 hours, which is enough for most data analysis, file processing, and app-building tasks. Keep long-running work in the current conversation so you can follow its progress and provide input when needed.

<Steps>
  <Step title="Follow progress in the current conversation">
    If the interface shows `Thinking` or continues to return progress updates, the task is still running. If it shows `Completed`, the current run has finished.
  </Step>

  <Step title="Save results at useful checkpoints">
    For work with multiple stages, ask Cuppy to write results back to Teable, export them, or generate a downloadable file at key checkpoints. Saved work remains available even if the conversation environment is released later.
  </Step>

  <Step title="Know when the environment is released">
    A single conversation environment has an approximate maximum lifetime of 24 hours. After foreground execution ends, an idle environment is released after about 30 minutes. Temporary files and unsaved intermediate results are not preserved if the environment restarts.
  </Step>
</Steps>

For long-running or repeatable work, use the feature that matches the workflow:

<CardGroup cols={2}>
  <Card title="AI Fields" icon="sparkles" href="/en/basic/field/ai/ai-field">
    Use for record-by-record work, such as large table processing, batch classification, content processing, or field filling.
  </Card>

  <Card title="Automation" icon="bolt" href="/en/basic/automation">
    Use for repeatable work after records are created or updated, notifications, or scheduled data processing.
  </Card>
</CardGroup>

## Artifacts

When AI builds a chart, report, dashboard-style page, or small interactive tool, it saves the result as an **artifact**: a self-contained page that renders outside the conversation. Artifacts appear as a card in the chat and stay available afterwards. Each one is either an interactive HTML page or a Markdown report.

Click the card to open the artifact. From the viewer you can:

* **Fullscreen** or **Open in new page** to give the artifact more room.
* **Download** the current version as a file.
* Open the version list to look at an earlier version and **Restore this version** to make it current again.
* **Delete** the artifact. Its cards in the conversation turn into a deleted placeholder, so delete only when you no longer need the result.

To change an artifact, ask AI in the same conversation. Each revision becomes a new version of the same artifact rather than a separate one, so the share link keeps working and you can still go back. If the page fails to run, the viewer shows the error and offers **Fix with AI**, which sends the error back to the chat so AI can correct it.

### Share an Artifact

Artifacts are private to the person who created them, so use a share link to let anyone else open one.

<Steps>
  <Step title="Turn on sharing">
    Click **Share** in the viewer and enable **Enable sharing**. Teable generates the link.
  </Step>

  <Step title="Choose who can view">
    Set **Who can view** to **Anyone with the link**, or to **Space members** so only signed-in members of the space can open it.
  </Step>

  <Step title="Add a password (optional)">
    Under the advanced settings, turn on **Password protection** and set a password. Viewers must enter it before the artifact loads.
  </Step>

  <Step title="Send the link">
    Use **Copy link** to copy it. If the link has spread too far, **Reset link** issues a new one and stops the old link from working.
  </Step>
</Steps>

### Find Artifacts Later

Open **+** → **More** → **Manage artifacts** to browse everything you have created across your chats. Search by name, then open one to view or reshare it.

## Prompting Tips

* **State the goal first**: In the first message, describe what to do, the relevant conditions, and the expected output. For example, analyze weekly sales trends over the past 3 months, grouped by region, and return a trend table with a short conclusion.
* **Use field names**: For example, sort by `Created Time`, so AI can identify the target column.
* **Provide several examples**: For fixed-format output, provide 3-5 input -> expected output examples.
* **Use `@` to select nodes**: When AI needs to reference tables, views, apps, automations, or folders, type `@` and select them directly.
* **Confirm before execution**: For tasks that modify data, create tables, create apps, or enable automations, ask AI to describe the changes before running them.
* **Choose the model by task**: If the space supports model selection, use a lighter model for simple queries, cleanup, or rewriting, and a stronger model for complex planning, cross-table analysis, and app building.
* **Adjust the Intelligence level**: **Intelligence** controls thinking depth; higher levels produce more thorough reasoning.
* **Start a new chat when the topic changes**: A new chat is recommended when the topic changes, the conversation becomes too long, or context usage should be reduced.

## FAQ

<AccordionGroup>
  <Accordion title="How do I let AI Chat reference another table, view, app, or automation?">
    Type `@` in the input box and select the node you want AI Chat to reference. For Grid view selections, you can also select rows, columns, a single cell, or a cell range, then use **Add to Chat** from the context menu.
  </Accordion>

  <Accordion title="Are the charts and reports AI creates saved?">
    Yes. They are saved as artifacts, with version history and an optional share link, and you can reopen them from **+** → **More** → **Manage artifacts**. An artifact keeps the data it was built with and does not refresh on its own. For a page that reads live table data, create an app with [App Builder](/en/basic/ai/app-builder).
  </Accordion>

  <Accordion title="Can my teammates open an artifact I created?">
    Not by default. Only you can open your own artifacts. Turn on **Enable sharing** in the viewer and send the link, choosing **Space members** if the artifact should stay inside the space.
  </Accordion>

  <Accordion title="Does memory carry across Bases?">
    No. Memory is scoped by user and Base. If you want to reuse memory from another Base, ask Cuppy to read that Base's memory and save the relevant parts into the current Base.
  </Accordion>

  <Accordion title="Can AI Chat keep working in the background after I leave?">
    Do not use AI Chat as a background task runner. Keep working in the visible conversation, and ask Cuppy to write results back to Teable, export results, or generate a downloadable file.
  </Accordion>

  <Accordion title="Why does Teable say Cuppy is busy in another conversation?">
    Each user can run up to 3 Agents at the same time, including AI Chat and App Builder. If you see `Agent is busy in another conversation. Please wait.`, another task is still running. Wait for Cuppy to finish the previous task before continuing.
  </Accordion>

  <Accordion title="How are credits refunded when an AI run fails?">
    One AI Chat turn can include multiple processing steps. The conversation and billing page both show the total credits for that turn. Work that Cuppy already completed and saved can still be used. If the final step is interrupted by an unexpected error, credits for that interrupted step are refunded automatically. You can continue working in the same conversation.
  </Accordion>

  <Accordion title="What happens if I send another message while AI is working?">
    The new message is queued. You can edit the queued message, remove it, or, when the action is available, use **Send follow-up without interrupting** to add a text follow-up to the current run.
  </Accordion>

  <Accordion title="How do I use Skills in AI Chat?">
    Open the **+** menu and choose **Skills** to import or manage skills, or type `/` in the input box to choose an enabled skill. Choose who can use the skill when you import it: personal for your own chats, base when collaborators in the same base need it, and space when everyone in the space does. Users who can manage the base can add base skills, and space owners and creators can add space skills. If AI Chat presents a `.skill` file, use **Install** on the file card to add it.
  </Accordion>

  <Accordion title="Which skill applies when two of them share a name?">
    Only one version is ever in effect, and the shared team version wins over a personal copy: a base skill beats a space skill, and a space skill beats a personal one. In an app or bot conversation, the skill added for that app or bot comes first. To move everyone to a new version, update the copy in the base or space.
  </Accordion>

  <Accordion title="Which files stay in Manage files?">
    **Manage files** holds two folders: `uploads` for the files you added, and `outputs` for the files produced in the conversation. Both use their own storage, so they survive the sandbox being released or rebuilt and you can come back later to preview, download, or delete them.

    Anything Cuppy writes outside those two folders is temporary, such as intermediate results from a script. It does not appear in **Manage files** and is gone after the sandbox restarts. For results you need to keep, ask Cuppy to write them into `outputs` or back into Teable, or download them while the conversation is open, using **Download all** when a reply produced several files.
  </Accordion>

  <Accordion title="What happens when I copy a message with chips?">
    When you copy a user message, tables, views, apps, automations, folders, selections, and attachments are kept as marker text. When you paste the text back into AI Chat, Teable restores the markers it can recognize as chips.
  </Accordion>

  <Accordion title="Where should I put API keys for AI Chat?">
    Use **+** → **Secrets** in the chat input. AI Chat can use those values during the conversation without putting the plaintext in your prompt.
  </Accordion>
</AccordionGroup>