Managing Data

Your agent's service database lives in the data/ folder. This is where you store product listings, user records, FAQs, or any structured information your agent needs. You can build this database without writing any code.

JSON Files

The simplest approach. Drop JSON files in the data/ folder:

// data/products.json
[
  {
    "id": "iphone-15-pro-001",
    "model": "iPhone 15 Pro",
    "storage": "256GB",
    "color": "Natural Titanium",
    "condition": "Excellent",
    "battery_health": 94,
    "price": 950,
    "available": true,
    "listed_by": "ahmed",
    "listed_at": "2026-03-15"
  },
  {
    "id": "iphone-14-002",
    "model": "iPhone 14",
    "storage": "128GB",
    "color": "Blue",
    "condition": "Good",
    "battery_health": 87,
    "price": 520,
    "available": true,
    "listed_by": "maria",
    "listed_at": "2026-03-20"
  }
]

You can have as many JSON files as you want. The agent searches across all of them.

SQLite Database

For larger datasets or when you need relationships between tables, use SQLite:

-- The agent can create and manage tables using the run_query tool
CREATE TABLE products (
  id TEXT PRIMARY KEY,
  model TEXT,
  storage TEXT,
  condition TEXT,
  price REAL,
  available BOOLEAN DEFAULT 1
);

Place a database.sqlite file in data/ or let the agent create one through conversations.

Ways to add data

Drop files: Create JSON files and place them in the data/ folder directly
Dashboard: Use the Data page in the web dashboard to create and edit files visually
Upload: Drag and drop files into the Data page
Conversation: Tell the agent to add records during chat. It will create or update data files on its own
CLI: Use echo '{"key":"val"}' | aaas data add file.json to add records from the command line

Agent data tools

The agent has access to these tools automatically during conversations:

`search_data`	Search across all JSON files and SQLite tables
`add_data_record`	Add a new record to a JSON file or table
`update_data_record`	Modify an existing record
`delete_data_record`	Remove a record
`run_query`	Execute raw SQL queries (admin mode only)
`list_tables`	Show all SQLite tables and their structure

These tools are available by default. You do not need to configure or enable them.

Keeping data up to date (Data Sources)

For data that changes regularly — product prices and stock, doctor schedules, daily menus — connect a data source. It pulls a CSV (or JSON) from the business's own system on a schedule and writes it into the agent's store. The agent reads the refreshed data live, with no restart.

Add a .aaas/data-sources.json file to the workspace. If the file is absent, nothing changes — this feature is entirely opt-in.

{
  "sources": [
    {
      "name": "products",
      "type": "url",
      "location": "https://docs.google.com/.../pub?output=csv",
      "format": "csv",
      "target": "sqlite",
      "table": "products",
      "mode": "replace",
      "mapping": { "Item Name": "name", "Price": "price", "In Stock": "stock" },
      "interval_minutes": 15
    }
  ]
}

Fields

`name`	Label for the source (shown in logs and used by `aaas data sync <name>`).
`type`	`url` (fetch over HTTP — a published Google Sheet or an export endpoint) or `folder` (a local / cloud-synced path; a file, or the newest matching file in a directory).
`location`	The URL, or the file/folder path.
`format`	`csv` (default) or `json` (an array of records, or an object wrapping one under `items`/`data`/`rows`).
`target`	`sqlite` — best for large or frequently-changing catalogs (indexed, queried with `run_query`) — or `json` for small sets.
`table` / `file`	The SQLite table name, or the JSON filename written into `data/`.
`mode`	`replace` (default — each sync rebuilds from the full export) or `upsert` (merge by `key`).
`key`	Primary-key column for `upsert` mode.
`mapping`	Optional. Rename source columns to field names (`"CSV Column": "field"`); unmapped columns pass through.
`interval_minutes`	How often to refresh (default 15).
`auth`	Optional, for secured URLs: `{ "type": "bearer"\|"header"\|"query", "apiKey": "{{ENV_VAR}}" }`. Use `{{ENV_VAR}}` so secrets stay out of the file.
`enabled`	Set `false` to pause a source.

How it refreshes

While the agent is running, due sources refresh automatically — by default every 15 minutes, each source using its own interval_minutes.
Run a sync immediately with aaas data sync (all sources) or aaas data sync <name> (one).
Writes are atomic, so the agent always reads a complete snapshot. last_synced_at and last_status are stamped back into the file after each run.

Tip: Google Sheets

The simplest source for most businesses: keep the data in a Google Sheet, choose File → Share → Publish to web → CSV, and use that link as a url source. Staff edit the sheet from anywhere and the agent picks up changes on the next sync. When the business has a proper API instead, use an Extension for live reads and write-back.

← The Soul File

Extensions →