CRUD Operations

How agents create, read, update, and delete rows in data tables.

Overview

Agents interact with data tables through four operations: Create, Read, Update, and Delete. These operations are exposed as tool calls that agents can use during their heartbeat reasoning.

Create (Insert Rows)

Agents can insert one or more rows into a table by specifying column values:

{
  "tool": "data_table_create",
  "params": {
    "table": "leads",
    "rows": [
      { "name": "Jane Smith", "email": "jane@example.com", "company": "Acme Corp", "status": "new" },
      { "name": "Bob Johnson", "email": "bob@example.com", "company": "Widgets Inc", "status": "new" }
    ]
  }
}

Columns not specified in the row data will use their default values (or be left empty if no default is set).

Read (Query Rows)

Agents can query rows with optional filters, sorting, and pagination:

{
  "tool": "data_table_read",
  "params": {
    "table": "leads",
    "filters": [
      { "column": "status", "operator": "eq", "value": "new" }
    ],
    "sort": { "column": "name", "direction": "asc" },
    "limit": 25,
    "offset": 0
  }
}

Supported filter operators:

Operator	Description
eq	Equals
neq	Not equals
gt	Greater than
gte	Greater than or equal
lt	Less than
lte	Less than or equal
contains	Text contains substring (case-insensitive)
in	Value is in a list of options

Update (Modify Rows)

Agents can update rows by specifying filters and the new values:

{
  "tool": "data_table_update",
  "params": {
    "table": "leads",
    "filters": [
      { "column": "email", "operator": "eq", "value": "jane@example.com" }
    ],
    "values": { "status": "contacted" }
  }
}

warning

If no filters are specified, the update applies to ALL rows in the table. Always include filters unless you intend a bulk update.

Delete (Remove Rows)

Agents can delete rows matching a filter:

{
  "tool": "data_table_delete",
  "params": {
    "table": "leads",
    "filters": [
      { "column": "status", "operator": "eq", "value": "rejected" }
    ]
  }
}

Audit Trail

Every CRUD operation is logged with the agent ID, timestamp, and operation details. You can view the audit trail from the data table settings page in the dashboard.