# 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 tok...

Source: https://artavolo.com/docs/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](https://artavolo.com/docs/data-api.md));
- the Airtable-compatible API, `https://artavolo.com/v0`, as
  `Authorization: Bearer` ([airtable-api.md](https://artavolo.com/docs/airtable-api.md));
- the AI connector, `https://artavolo.com/mcp`, as `Authorization: Bearer`
  ([ai-connector.md](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.
