Agent databases (also known as data documents) let your agent store and query structured records. Use agent databases to track invoices, manage inventories, store research findings, or maintain structured logs of anything it needs to remember across conversations. Pair them with interactive apps to browse, filter, and edit your data visually.
Technically, an agent database is a special type of agent document that stores data as a collection of JSON records—like a lightweight MongoDB collection. The agent has tools to insert, query, update, and delete records.
Creating an agent database
Creating a database is simple - just ask your agent to create it. No setup needed.
- “Create a database to track processed invoices”
- “Set up a database for customer feedback with fields for date, rating, and comments”
- “Make a database to log all emails you send”
- “Turn these notes from our product brainstorm workshop into a database of ideas”.
The agent creates the database instantly and defines an appropriate data schema based on your description. It shows up alongside your other agent documents in the Documents panel.
When to use an agent database
Think of it like choosing between a word processor and a spreadsheet. You’d personally write an article or report in a document, but you’d track a list of products, transactions, or tasks in a spreadsheet or database table.
Use a database when you have many items of the same type—products with prices and stock levels, support tickets with status and priority, research findings with sources and dates.
Use a text document when the content is prose—articles, meeting notes, guidelines, templates. If you’re writing something you’d read top to bottom, it belongs in a document.
Could you store a product list in a text document? Sure—it works fine for a handful of items. But once you have dozens or hundreds, text gets inefficient: every insert or update requires the agent to find the right spot, parse the format, and rewrite the text. That’s slow, token-expensive, and error-prone. Databases handle this with precise operations—faster, cheaper, and no risk of corrupting the format. Plus you get a visual table view instead of scrolling through text.
Not sure which to use? Just pick one—you can always ask your agent to convert a text document into a database or vice versa.
Agent databases are a simple way to create an instant data store, but you can also connect to an external database if needed—see Agent database vs external database below.
Editing data
You can ask the agent to make direct changes. The agent will interpret your request and use database operations to make the changes. Examples:
- Insert data: “Add this invoice to the database” (drop PDF in chat)
- Update data: “Update the status of invoice 123 to ‘paid’”
- Delete data: “Delete last week’s invoice from company Y”
If the database should be used as part of the agent’s workflow, describe that in the agent’s instructions:
- “When you receive an invoice, add it to the database”
- “Keep the product catalog up to date whenever you hear about changes”
- “After your weekly research, update the database with the new findings”
Querying data
Ask your agent questions about the data in natural language, and it will execute database queries to answer your question. Examples:
- “How many invoices did you process this week?”
- “Show me all pending tickets from the last 24 hours”
- “What’s the total amount of approved expenses?”
Direct queries find records by exact field values—status equals “pending”, amount greater than $1000, category is “urgent”.
Semantic search finds records by meaning, not just exact matches. This uses RAG (retrieval-augmented generation) to understand what you’re looking for:
- “Find all feedback with negative sentiment”
- “Show me bug reports that mention data loss”
- “Which research findings are about competitor pricing?”
Semantic search is especially useful when you don’t know the exact wording used in the records.
You can also make search part of the agent’s workflow:
- “When you receive a customer support email, check the FAQ database for similar questions before suggesting an answer”
Viewing agent database contents
The agent database is listed alongside the other documents in the Documents panel. Click on it to see the contents.
- Data tab — Raw JSON data (editable)
- Preview tab — A simple database viewer. You can toggle between table view (like a spreadsheet) and card view (grid of cards for each record). Nested objects and arrays appear as clickable links that expand for details.
This is useful for small databases, or to get an overview of what kind of data is in the database.
For larger databases, consider asking the agent to create an interactive app to browse the data. One or two prompts is usually enough to get you something like this:
Importing and exporting data
When viewing an agent database, you can click on the menu to import or export data in JSON text format.
- Export data — Download the data as a JSON text file.
- Import data — Upload a JSON file from your computer. When importing data, you can choose to append to the existing data or replace it.
Connecting to apps and scripts
Databases pair naturally with apps and scripts (which also are agent documents):
Example:
- “Create a database to track beta feedback”
- “Build a dashboard showing feedback trends and top issues”
- “Add a form so users can submit new feedback”
- “Write a script to import feedback from this google spreadsheet”
If you want the data to be visible to other users, you can publish the dashboard app. Open the dashboard app and click “Publish” in the menu.
Data schema
A database can have a schema that describes the shape of its records (which fields etc). The agent defines the schema automatically when creating the database, so you don’t need to manage this unless you want to.
To view or edit the schema, open the database and click Schema in the Data tab.
Schemas can be written in any format, but the agent uses TypeScript by default—a concise way to express data structures. For example here is a simple schema for a task list:
interface Task {
title: string;
assignee: string;
status: 'todo' | 'doing' | 'done';
}
interface Task {
title: string;
assignee: {
name: string;
email: string;
};
status: 'todo' | 'doing' | 'done';
}
Need to change the schema? Ask your agent—it can update the schema and migrate existing records in one step. For example: “Add a priority field to all tasks, default to ‘medium’.”
Security
Agent databases follow the same access model as other agent documents:
- By default, the agent can read and write to databases (disable via the Edit Documents capability)
- Users with access to the agent can view database contents
- For detailed permissions, see access control
Agent database vs external database
Agent databases are included by default—instant to create, no setup required, and tightly integrated with your agent. However, sometimes you may want your agent to connect to an external database, such as an existing company database, a shared data source used by multiple systems, or when you need enterprise-grade scaling. External databases (PostgreSQL, MongoDB, etc.) can be connected via MCP or other integrations.
| Agent database | External database |
|---|
| Instant creation, no setup | Requires provisioning and configuration |
| Great for prototyping and simple workflows | Enterprise-grade with backups and scaling |
| Hundreds of records | Millions of records |
| Data stays within the agent | Multiple systems can access the same data |
| Query within single collection (no joins) | Complex queries, joins, transactions |
| RAG included (semantic search) | No RAG (in most cases) |
If you aren’t sure that you need an external database, then start with an agent database. It is the simplest way to get you agent up and running quickly, and you can always migrate to an external database later if your needs grow.
Agent database vs spreadsheet
Your agent can access external spreadsheets via capabilities like Google Drive. This works well for small data (a few hundred cells), for example to maintain a product catalog with a few dozen products.
But with large and complex spreadsheets with 1,000+ cells, agents struggle—reading and updating cells requires parsing row/column coordinates, which gets slow, expensive, and error-prone. In that case it is better to use an agent database or external database.
Learn more
