AI agents

An agent is a program that works on your tables: a script calling the API, an assistant in Claude, ChatGPT or Le Chat through the connector, or an automation of your own. In Artavolo each agent has a name, its own token and access to the bases you give it, and everything it changes is credited to it in the record's history and the audit log.

Making an agent

A workspace owner makes agents. In the API:

curl -u you@example.com:$YOUR_TOKEN -H "Content-Type: application/json" \
  -d '{"name": "Invoice bot", "mode": "review", "bases": {"Aw7e1PXjM8": "write"}}' \
  https://artavolo.com/api/v2/workspaces/$WORKSPACE_CODE/agents

The answer holds the agent's token, once. Keep it like a password; a new one can be made at any time (POST .../agents/{id}/token) and the old one stops working.

bases names each base the agent may use: "read" lets it read, "write" lets it change records. The table rules of the base apply to it as to a person: tables hidden from contributors are hidden from it, and a row rule ("only records where Owner is them") limits what it sees.

What its changes do: the mode

• direct: its changes are written at once, like a person's.
• review: a change to a record is held as a proposal, one per field, until a person accepts or rejects it. A request that changes a record answers 202 with the proposals instead of 200. New records are added at once, and a delete goes to the trash, where it can be restored.

In review mode a person sees the proposals beside the table and decides:

GET  /api/v2/bases/{base}/tables/{table}/proposals            what is waiting, by agent
POST /api/v2/bases/{base}/tables/{table}/proposals/decide     {"accept": ["p12"], "reject": ["p13"]}

An accepted proposal is written only if the cell still holds what the agent saw; if someone changed it first, the proposal is stale and nothing is written. The record's history then reads "Invoice bot, accepted by Dana".

An agent can add a reason to its change, which the person sees:

PATCH /api/v2/bases/{base}/tables/{table}/rows/{id}
{"Status": "Paid", "_reason": "Bank statement of 3 March shows the payment"}

Connecting it

The token works everywhere an API token does:

• the data API, https://artavolo.com/api/v2, in the API-KEY header (data-api.md);
• the Airtable-compatible API, https://artavolo.com/v0, as Authorization: Bearer (airtable-api.md);
• the AI connector, https://artavolo.com/mcp, as Authorization: Bearer (ai-connector.md). Its tools tell the assistant when a change was held for review.

Watching what agents do

GET /api/v2/workspaces/{code}/agents lists each agent with its access, how many changes it made in the last 7 days, how many of its proposals were accepted, rejected or went stale, and the share accepted.

Removing an agent (DELETE .../agents/{id}) ends its token and its access and rejects what it proposed that nobody decided. What it already changed stays, credited to it.