Agent Tasks
Handing an agent a task is like passing a single file to a coworker with a sticky note on top: "summarize this," "score this," "draft a reply for this." You pick an agent, pick one record (one row of one of your databases), write a one-line instruction, and the agent runs once with that row's full content in front of it. It can read every field, then update fields, write into the body of the record, or update a different record to set off the next agent in line.
This page is the short version, from the agent's side. The full guide — how to turn Agent Tasks on for a table, the different ways a task can run, what each status means, agent chains, how many can run at once, and the run history viewer — lives in the Databases section.
Image: Agent task section in the record drawer with execution history
Before you start
- A saved agent you've already built — any agent will do, there's no special "task" type to create.
- The agent must be connected to the database where the record lives. You add that connection in the Agent Control Panel by adding the database to the agent's connections.
- The agent needs at least read permission on that database. Give it write or full if you want it to update fields, write into the record body, or update other records to set off a chain.
If those three are in place, the agent shows up in the agent picker on any record in that database.
Step-by-step
- Open the database and click the record (row) you want the agent to work on. The record drawer slides open.
- Find the Agent Task section in the drawer.
- Pick the agent you want from the agent picker.
- Write a one-line instruction — what you want the agent to do with this record, in plain words ("Summarize the notes and set a follow-up date").
- Run the task. The agent reads the record, does the work, and writes the result back.
What the agent sees and does
When a task runs, the agent receives:
- The record's full content — every field name and its value, handed over as context.
- The instruction you wrote in the record drawer.
- Access to all of its normal tools and knowledge — so it can search the web, look up other databases, or reach other connected services as part of finishing the job.
The agent then writes its results back to the same record (or to another one) using its database tools.
When to use a task instead of an automation
| You want to… | Use |
|---|---|
| Run a one-off job on a specific row | Agent Task |
| Use the row's own data as context | Agent Task |
| Set off another agent when this row's status changes | Agent Task |
| Run the same job every morning / whenever an outside alert arrives | Agent Automation |
| Coordinate several agents across multiple steps | Agent Automation |
See the Tasks & Automations overview for a fuller comparison.
Troubleshooting
| Problem | Fix |
|---|---|
| My agent isn't in the picker on a record | Connect the agent to that database in the Agent Control Panel, and confirm it has at least read permission. |
| The task ran but nothing was written back | The agent likely only has read permission. Raise it to write or full so it can update fields or the record body. |
| The task didn't set off the next agent in a chain | Chains need the agent to update the other record, which requires write or full permission on that database. |
| I need the task to run on a schedule or repeat | A task runs once. For recurring work, build an Agent Automation instead. |
What's next
After this, continue to Agent Automations to combine agents into multi-step routines that run on schedules, outside events, or a button. For everything a task can do — the ways it can run, status meanings, chain protection, run limits, and the run history viewer — see Databases → Agent Tasks.