Agent runs
Start a small agent from your panel that works on the folders the user granted — with only file tools (and your own tools), no shell and no web, a step and time limit, and a place in Activity where the user can watch and stop it.
An agent run is a short task your app hands to the user's model, with tools: "Tidy the notes in notes/ — one topic per file, fix the titles." It runs on Chataway's side, uses the user's AI, and can touch only what you pass it.
It is not the user's chat agent. A run has no shell, no web access and none of the provider's built-in tools. Its only tools are the file tools below and, if you ask, your own app's tools. The folder limit is built into those tools, so it doesn't depend on the model behaving.
#What you need
{
"requires": { "hostApi": 4 },
"grants": ["models", "folders", "agent"],
"permissions": [
"Use your AI to tidy the notes you ask it to (counted in your daily AI limit for this app)",
"Open and save the notes in the folder you choose"
]
}agent needs models (a run uses the user's model), and folders for any root other than storage — a granted folder or a file the user opened with your app.
#Start a run
tidyButton.onclick = async () => {
const { runId } = await app.agent.run({
task: 'Tidy the notes: one topic per file, a "# Title" on the first line, merge duplicates. Report what you changed.',
roots: ['folder:notes'],
maxSteps: 30,
});
const run = await app.agent.wait(runId, ({ run, step }) => {
status.textContent = step ? `${step.tool}…` : run.status;
});
result.textContent = run.status === 'done' ? run.result ?? '' : run.error ?? run.status;
};| Option | Type | |
|---|---|---|
task | string | What to do, in plain words. 1–4000 characters. |
roots | string[] | 1–10 roots the run may touch: granted folder:<id> roots, a file:<handle> the user opened, and/or storage. |
appTools | boolean | Also let the run call your app's own tools. Default false. |
tier | 'fast' | 'balanced' | 'best' | A model hint. Default balanced. |
maxSteps | number | Tool calls before it stops. Default 30; more than 60 counts as 60. |
agent.run must run inside a click or key handler in your panel, one run per click (click only; needs-gesture otherwise). A run is something the user started, never something your app starts on its own.
#What a run can do
| Tool | Does |
|---|---|
list_files | List a root (or a folder in it). |
read_file | Read a text file. For a binary file it gets a short description (type and size). |
write_file | Write a text file. To change a file it passes the version it read; without one it can only create a new file. So it never overwrites a change it didn't see. |
rename_file | Rename or move a file or folder. Never overwrites. |
trash_file | Move a file or folder to the system Trash. |
search_files | Find text (case-insensitive) in the text files of a root, up to 1 MB each. |
| Your app's tools | Only with appTools: true. Called with the run's chat (the panel's chat), if it has one. A tool that needs a card fails with a readable error when there is no chat to show it in. A tool named like a file tool gets app_ in front (app_read_file). |
Every file tool goes through the same checks as your panel's fs calls: inside the roots, your file types only, never .env, keys or .git/, never a write to an agent-instructions file (CLAUDE.md, AGENTS.md…) or a hidden file or folder, and Chataway keeps a backup before each overwrite or trash. On the storage root, the run sees only what your storage zones allow: nothing of internal, read-only for readonly.
The run's system prompt is a short preamble from Chataway (what it may touch, that it has no shell or web, to stop when it's done) followed by your contributes.instructions.
#Limits
| Limit | Value |
|---|---|
| Tool calls | maxSteps: 30 by default, 60 at most. Past it, each tool call answers "stop now"; a run that goes on anyway fails. |
| Time | 10 minutes, then it fails |
| Roots | 1–10 |
| Runs at once | One running run per app per project. A second agent.run fails with busy. |
| AI budget | Every model request of the run counts in your app's daily budget. Over the limit, agent.run fails with budget; a run that reaches it on the way fails. |
A run that is still working when Chataway quits or restarts ends as failed.
#What the user sees
A running run shows in Activity → Live with your app's name and what it works on ("Sketch Notes · working on notes/"), and a Stop button. When it's done, a toast offers View (the task, every step and the result) and Continue in chat, which opens a new chat with the run's summary in the composer, unsent. A failed run shows an error toast with View; a stopped one shows nothing. Your app's page in Apps lists its recent runs.
#Follow and stop a run
| Method | Result |
|---|---|
agent.run(options) | { runId } |
agent.get(runId) | The run, with its steps |
agent.list() | Your app's recent runs in this project, newest first (up to 50), without steps |
agent.stop(runId) | { stopped: true }. Steps already done stay done. |
agent.wait(runId, onUpdate?) | Resolves with the run once it is done, failed or stopped |
A run is { id, appId, appName, projectId, chatId, task, roots, status, model, stepCount, result, error, startedAt, endedAt }, and agent.get adds steps. status is running, done, failed or stopped. model is the model's label, result the run's last answer, and error why it failed (null when it was stopped). Times are milliseconds. Each step is { at, tool, args, result, isError? }, with long args and results cut short. Runs of another app fail with denied.
The agent-run event carries { run, step? } every time one of your runs takes a step or changes status:
app.on('agent-run', ({ run }) => {
if (run.status === 'done') refreshList();
});The event's run has stepCount but no steps, and so does the run agent.wait resolves with when the run ends while you wait. Call agent.get for the steps.
Files the run changes also arrive as fs-change events on a watched root.
#From server code
Local apps can start a run from their server with ctx.agentRuns.start(options) — the same options, plus an optional chatId — but only inside an action handler (ctx.actions.register) that your panel called with invokeAction from the user's click, and once per such action; anywhere else it throws. Panels also call actions to load data, so an action without a click can't start a run. ctx.agentRuns.stop(runId), get(runId) and list() work anywhere in your server code. Cloud apps start runs from their panel.
#Write good tasks
- Say what done looks like. "…and finish with a list of the files you changed." The run's
resultis its last answer. - Name the scope. Pass only the roots the task needs. A run on
folder:notescan't touch anything else, whatever the notes say. - Prefer small runs. A 60-step run that renames half a folder is hard for the user to check. Several small runs are easier to trust.
- Expect the files to change. The run writes real files in the user's workspace. Watch the root, and reload what your panel shows.
#In the mock host
The mock host does a fake run: it lists each root as a step and finishes with a summary. No model runs and nothing changes. Pass agent to script a run with real file tools:
const app = await connect({
mock: {
manifest,
fs: { 'folder:notes': { 'a.md': '# a' } },
grantedFolders: ['notes'],
agentStepMs: 300, // time between steps (default 200)
agent: async (task, tools) => {
const text = await tools.read('folder:notes', 'a.md');
await tools.write('folder:notes', 'a.md', text.replace('# a', '# A'));
return 'Fixed one title.';
},
},
});It enforces busy, stop, clicks and grants like Chataway does (without the one-call-per-click limit).