Long-running agents
Most questions take an agent a few seconds and a handful of tool calls. Some jobs need far more: researching a market, reading dozens of pages, going through every file in a folder. For those, an agent can work in the background. The chat carries on, and the agent reports back when it’s done.
Start one
Section titled “Start one”Ask for long, thorough work in a chat. Words like these tell the agent it’s a big job:
Do some market research on home battery prices in Australia.
Research the best e-bikes under $3,000, in depth.
Take your time and go through all the PDFs in my workspace. Which ones mention penalties?
Deep dive into what people are saying about the new tax rules.
The agent starts a background task, says it’s started, and the chat is free again. You can keep chatting with the same agent, or anyone else, while it works.
Background tasks start from chats that are kept: My team or a chat you started, not Quick assist.
Watch it work
Section titled “Watch it work”A card in the chat shows the task while it runs:
- how long it’s been going,
- how many steps it’s taken and pages it’s read, and
- what it’s doing right now.
On a model on your Mac, its requests take turns with your chats, so your chats still get answered in between.
Stop it
Section titled “Stop it”- Stop stops its tools at once and has it write up what it found so far, saying plainly what it didn’t get to.
- Stop now (press Stop again) drops the task without a report.
The report
Section titled “The report”When it’s done, the agent:
- posts its report to the chat: findings first, then the details, then links to the pages it used,
- saves it as a file in the System agent’s workspace, under
reports/, and - remembers it, so you can ask follow-up questions in the same chat (“which of those had the longest warranty?”).
How much it can do
Section titled “How much it can do”An agent’s Steps setting is how many times it may use its tools for one job. Set it per agent in its settings (the cog on its card), from 5 to 200. By default:
| Where | Steps |
|---|---|
| A normal chat reply | 10 |
| In the background, on a cloud model | 100 |
| In the background, on a model on your Mac | 30 |
An agent’s own Steps setting, if you set one, applies everywhere.
A task in the background is told that nobody is waiting, so it should be thorough, decide for itself (nobody can answer its questions), avoid repeating searches or re-reading pages, and stop once it has enough to answer well.
For long work, agents that read the web get tools that read up to 50 pages at once, two per site at a time, retrying a busy site once. Each page is saved to the workspace, and the agent only sees short excerpts, so its context doesn’t fill up. As a long run goes on, older tool results are shortened to fit the model.
Choosing a model for long work
Section titled “Choosing a model for long work”Long tasks are where a stronger model pays off. Small local models can lose track over dozens of steps. A good pattern is to keep the default model local and give your research agent (Scout, or the System agent) a cloud model under Model in its settings. See More models.
Limits
Section titled “Limits”- Up to 3 background tasks at once.
- Background tasks don’t survive a restart. If Agent City quits, a running task is lost.
- The System agent’s Read web pages switch must be on for System to research the web. Scout searches the web out of the box.
Long-running work on a schedule
Section titled “Long-running work on a schedule”A background task runs once. For work that should happen again and again, like a weekly competitor round-up or a nightly check of your inbox, make it an automation. See Goals for putting the two together.