Knowledge & tools

Airtable tool

The Airtable tool lets an agent work in your Airtable bases - reading and filtering records, creating and updating them, and managing tables and fields. It has 11 actions, and one tool configuration maps to one Personal Access Token, which is itself what decides which bases the agent can reach and what it's allowed to do there.

How Airtable is organized: a base contains tables, and tables contain records. Record values are keyed by the exact field name, so before the agent writes anything it calls get_base_schema to learn the real table and field names rather than guessing at them.

What it can do

Eleven actions, in four groups:

Discover - list_bases, get_base_schema (tables plus field names and types).
Read - list_records (filter with an Airtable formula, sort, pick which fields to return, limit and paginate), get_record.
Write records - create_records, update_records (partial: only the fields you include change), delete_records.
Schema - create_table, update_table (rename or describe), create_field, update_field (rename or describe).

Two conveniences worth knowing: updates are always partial, so fields the agent doesn't mention are never wiped; and typecast lets it write human-readable values - a date as text, a select option by its name, a linked record by name - and Airtable converts them for you.

Creating a Personal Access Token

Airtable retired API keys in February 2024, so a Personal Access Token is the only way to connect.

Go to airtable.com/create/tokens and choose Create token.
Scopes - add data.records:read, data.records:write and schema.bases:read. Add schema.bases:write only if the agent should create or rename tables and fields; leave it off for a records-only token.
Access - under Add a base, attach every base the agent should work with. See the callout below.
Create the token, copy it (Airtable shows it once), and paste it into the Hania form.

Attaching a base is the step everyone misses. Scopes alone are not enough. A token with perfect scopes but no base attached looks completely valid, yet every call comes back empty - the agent will tell you it can't see any bases. If that happens, edit the token, open Access, and use Add a base.

Start narrow if you like. A token scoped to less than the full set still works fine - anything it isn't permitted to do returns a clear permission error that the agent reports back to you. Plenty of people start read-only and widen the token later.

Airtable updates its token screens from time to time, so treat the section names above as authoritative and the exact labels as approximate - find the named section if a label has moved.

Field reference

Personal Access Token (required, secret) - an Airtable Personal Access Token from airtable.com/create/tokens. It needs the right scopes (data.records:read / data.records:write, schema.bases:read, and schema.bases:write for schema changes) and the base or bases added to it as resources. Stored encrypted and never returned.

What the agent can and can't do

The actions above are the full set, with one boundary that comes from Airtable itself:

The agent can add tables and fields, but it can't remove them. The Airtable API has no way to delete a table or a field, so anything the agent creates with create_table or create_field is permanent as far as the agent is concerned - removing it means doing so yourself in the Airtable UI. Because of that, the Airtable Manager blueprint treats schema changes as high-stakes: it confirms with you first and never creates a table or field speculatively.

Records are a different story - those the agent can delete, up to 10 at a time.

Limits

Airtable allows up to 10 records per write and roughly 5 requests per second per base. The agent batches its work to stay inside both, so large jobs simply take a few more calls rather than failing.

Troubleshooting

The agent can't see any bases, or list_bases comes back empty - no base is attached to the token. Edit the token, open Access, and add a base. This is by far the most common cause.
"insufficient permissions" on a write or schema action - the token is missing that scope. Add data.records:write for record changes, or schema.bases:write for table and field changes.
422 INVALID_PERMISSIONS_OR_MODEL_NOT_FOUND - usually a wrong table or field name rather than a permissions problem. The agent re-reads the schema and corrects itself.
429 rate limited - the 5-requests-per-second cap; Airtable asks for a 30-second wait and the agent backs off.
401 or 403 - the token is wrong, expired, or revoked. Create a fresh one and re-paste it.
Validation errors (a missing base or table, or more than 10 records in one write) - the agent self-corrects these, so they may flash through a trace before the call succeeds.

Safety in autonomous runs

Like any tool, the Airtable tool carries a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Because it deletes records and creates schema that can't be undone through the API, a new configuration is created with Read-only switched off, Destructive switched on, and Sends data externally on - so destructive actions are gated in autonomous runs unless the bot's "Allow destructive actions in autonomous runs" is enabled. Keep those defaults, and prefer the tighter control: scope the token to just the bases and operations the agent needs, so the limit is enforced by Airtable rather than only by an app-layer flag. Interactive chat is never gated by these flags.

Security

The token is stored AES-encrypted at rest and is never returned by the API - the console shows only whether a token is set. Editing a configuration without retyping the token preserves the stored one, so you must retype it to replace it. To revoke the agent's access, delete or re-scope the token at airtable.com/create/tokens; you can also just detach a base to take it out of reach.

Blueprint

The fastest way to a working Airtable agent is the Airtable Manager blueprint (productivity category) - a pre-built agent for reading, filtering and updating records, with the read-the-schema-first and confirm-before-schema-changes habits described above already in place. Pick it from the blueprint gallery when creating a bot; the only thing you supply is the token from this guide.