Chain agents: storage target, new files one by one, JSON result

Admin

An agent reads a source and works with its tools. Several agents can be connected into a chain: the first files documents, the next processes every new file in a run of its own and returns a structured result, a third works on from there. The agent page has four settings for this: the storage target, the read state “Only new files”, One run per file or One run per mail, and the result schema. How to create and test an agent in the first place: → Create an agent and test it in a dry run

Storage target: where the agent writes

On the Scope tab, section Storage target, you set where the agent may write. The target is enforced during the run; the model cannot write past it.

Target	Settings	Writes there
None	—	as without a target
Vault	vault, Folder in the vault (empty = vault root), Allow subfolders, Mail filing	knowledge tools (create, update, move, delete articles; file email in knowledge base)
Working folder	Working folder (absolute path); subfolders are always allowed	working-folder tools and skill scripts; desktop app only

Tools of the other kind drop out: under a vault target the run offers no writing working-folder tools, under a working-folder target no writing knowledge tools. The page shows which of the selected tools drop out: “These selected tools are not offered with this target: …”. Actions that only affect the mailbox or a message (send, archive, mark as processed) stay with every target.
Files land in the target: Office documents (presentation, spreadsheet, filled Word template) and downloaded mail attachments go into the target. With a vault target they land in the attachments/ subfolder of the target folder — everyone with read access to the vault can see them. If the target cannot take a file (folder missing, name not allowed), the tool refuses with the reason; there is no fallback location.
Skill scripts are not offered with a vault target. With a working-folder target, scripts write into the target folder. → Script skills
File email in knowledge base: with a vault target, the target sets the vault; a folder in the call lies below the target folder. → Tools: email
Mail filing: sets the form in which the tool files an HTML email as an article. Content (Markdown, best for search) turns newsletter layouts into readable text with links and online images so knowledge search finds them; tracking pixels are dropped. Presentation (layout as in the original) keeps the HTML layout as before. A newly chosen vault target starts on Content; agents whose target existed before stay on Presentation until you switch. The setting applies only to the email text, not to attachments, and not to the import page. Emails filed before are not filed again after a switch; if you want that, delete the old article first.
Check: a working-folder target must exist and must not lie inside the skills or script data folder. It is checked on saving and at every run start; if the check fails at the start, the run ends with the reason before any tool runs. In web mode, “Working folder” cannot be chosen as a target.

Vault source: only new files, one run per file

Source adapter Vault on the Scope tab — besides vault, folder path and file glob there are two checkboxes:

Only new files: every file is processed exactly once. On the first run the agent records every file already in the folder as read and processes nothing (baseline). Only files added afterwards count as new. So switch the option on and let the agent run once before the folder fills up — otherwise the first files end up in the baseline. At most 25 new files per run; the rest follows on the next run. The baseline is per folder: after a folder change, the next run sets a new one.
One run per file: every file gets its own run with a fresh context, one after the other, at most 25 per start. If a run is not clean (failed, filing or script error), the chain stops; the remaining files follow on the next start. A dry run handles only the first file. If a manual start has nothing to do, the page reports “The agent ’…’ has no new items to process.”
Failed attempts: if a run fails on a file — also through a failed script — that counts as an attempt. After the third attempt the file counts as processed and is not touched again; the run names it: “Skipped after 3 failed attempts and not processed again: …”. Errors before the model starts (no model, budget limit, PII protection) do not count. Files in the vault are never moved.
Loop protection: if the agent reads only new files from the folder it files into (vault target in the source folder or below), the page refuses to save: “The agent reads only new files from the folder it files into, so every file it writes would start its next run. …”

Who advances the read state: only scheduled runs and starts from the agent page. Dry run, workflow step and chat delegation read with the read state but mark nothing as processed.

Mailbox source: one run per mail

Source adapter Mail — mail account, folder, sender filter, Unread only (on by default; POP3 has no read status and ignores the checkbox) and Max items per run.

Read state on the schedule: a mailbox agent remembers on its schedule trigger up to which mail it has read; every scheduled run fetches the oldest mails after that point. The first run and every manual start without a trigger take the newest mails and remember nothing. If the account or folder changes, the state starts afresh.
One run per mail: every new mail gets its own run, oldest first, at most “Max items per run” per start. A dry run handles only the first mail. As with one run per file, the chain stops at the first run that is not clean.
Failed attempts: a mail has three attempts — a failed filing into the knowledge base counts and, with one run per mail, a script error. It comes up again even if the failed run already marked it as read; after the third attempt it is skipped. Refusals caused by the configuration (account, vault, read-only) do not count. The warning block for this is described in → Tools: email

Working-folder source (desktop)

Source adapter Working folder — Inbox folder (absolute path), file glob, Max items per run (at most 25) and One run per file.

What is read: text files (e.g. .txt, .md, .csv, .json, .xml) directly in the inbox folder, oldest first — no subfolders, no files starting with a dot. A file only comes up once it is at least 10 seconds old, so no half-written file is read. Up to 32,000 characters per file (the rest is cut with a note), 120,000 per run; what no longer fits waits for the next run. Other file types stay where they are.
Files move: during a run the file sits in the hidden folder .in-arbeit, after success in erledigt, after three failed attempts in fehler (the run names it). Nothing is deleted; a file with the same name gets (2) appended. If a processed file could not be moved, the run reports “Processed, but not moved to “erledigt/” …” and processes it again next time.
Only consuming runs move files: scheduled runs and starts from the agent page. Dry run, workflow step and chat delegation read the files in place.
Loop protection: the storage target must not be the inbox folder or one of its folders erledigt, fehler, .in-arbeit; another subfolder is fine.
Desktop only: in web mode the source is missing. If an agent with this source starts there anyway (e.g. through a workflow), it fails with “The working-folder source exists only in the desktop app. …”. On network and cloud drives without atomic renames a file can be picked up twice.

Result schema: JSON instead of prose

On the Reasoning tab, field Result schema (JSON, optional), you enter a JSON Schema object, for example:

{
  "type": "object",
  "properties": {
    "title":  { "type": "string" },
    "topics": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["title"]
}

How it works: after the tool loop, the run converts its final answer into this JSON. Only valid JSON and the top-level required fields (required) are checked; further rules only reach the model as guidance. The conversion sees only the final answer — write the instruction so that it contains every value asked for.
Where the result is: in the run view under Result (JSON), with real values even if the run worked on pseudonymised data. With a working-folder target also as a file in the target folder: <file name>.json after the vault file read (a second run of the same file overwrites it), otherwise run-<run number>.json. The file is first written under a name starting with a dot and then renamed, so a working-folder source further down the chain never sees half a file. With a vault target no JSON goes into the knowledge base — the result is only on the run.
Dry run: the result is on the run; no file is written.
When it fails: if the answer does not match the schema, the run ends with “The result does not match the agent’s result schema (…). …”; the source is processed again on the next run. If the file cannot be written, the run reports “The result file ’…’ could not be written to the target folder. …”.
In a workflow a later step binds single fields with {{steps.<id>.output.result.<field>}}. → Create and run workflows

Example chain: evaluate newsletters (desktop)

Three agents, each with its own schedule:

“File newsletters” — source Mail with a sender filter, storage target Vault default, folder Newsletter, mail filing Content, tool File email in knowledge base, Run-as user set. Prompt as in recipe 1 under → Tools: email
“Evaluate newsletters” — source Vault, folder path Newsletter (the default glob **/*.md also reads subfolders such as Newsletter/A), Only new files and One run per file; storage target Working folder, e.g. /Users/name/newsletter-json; result schema as above. Every new newsletter yields exactly one JSON file.
“Collect topics” — source Working folder, inbox folder /Users/name/newsletter-json; storage target e.g. Vault default, folder Newsletter-Overviews — not below Newsletter, or agent 2 reads the overviews as new newsletters. Processed JSON files move to erledigt.

Order of setup — back to front:

Create agent 2 while the Newsletter folder is empty (or holds only old items that should not be evaluated), and click Run once — this sets the baseline and processes nothing.
Create agent 3. The working-folder source has no baseline: everything in the inbox folder at that point is processed.
Only now switch on agent 1.

Timing: the schedules of the later stages come after the earlier one (e.g. hourly at minute 0, 10 and 20). Test each stage on its own: a dry run of agent 2 processes the first new file and shows the result, but writes no file.

Instead of files: a workflow. If the stages should run in one go, a workflow connects them with agent.run steps and passes values on through {{steps.<id>.output.result.<field>}} — not through files: a workflow step advances no read state, and a file written a moment ago is not yet 10 seconds old for a directly following step and therefore invisible. → Create and run workflows

Limits

Working folder as target and as source exists only in the desktop app; scheduled agents there only run while the app is open. → Web vs. desktop
Workflow step and chat delegation start exactly one run, do not split and advance no read state.
Export/import: storage target, result schema and read state are not part of the export. An import with overwrite resets the read state: the next run only sets a new baseline, nothing is processed again. Without overwrite the existing agent stays unchanged.

The agent model
Agents (reference)
Tools: Process many files or mails one by one — one by one within one run