At a glance
- Does
- A tool loop — map a repo, read and edit code, run git, open a PR, or any tool-driven goal
- Emits
- result, steps, tokens_used, tools_called, trace
- Needs
- A provider configured in Settings, plus the tools you switch on
Set it up
Write the Goal, pick a provider and model, and switch on the tools it actually needs in the inspector's Tools section. The agent then loops — think, call a tool, observe, repeat — until it answers or a budget stops it. With Verify Before Finishing on it reviews its own result first.
Goal, System Prompt and Verification each open in the Workbench, where a run exercises the real tool loop under the node's budgets with nothing downstream firing. Result carries the answer; Failure carries error and errorType, so a stalled run can take a recovery path instead of ending the flow.
Tools
Every tool is off until you switch it on. The count in the header is what the agent can reach; the greyed rows need a File Access Scope first. Destructive tools (Run Script, Write File, Apple Notes, Apple Reminders) light the red banner at the top of the inspector while armed.
File Access Scope
Unscoped, the file tools reach anywhere not on the built-in deny-list (~/Library, ~/.ssh, /etc, system folders). Set File Access Scope to a folder and every path is canonicalised — symlinks and .. fully resolved — and refused unless it lands genuinely inside. A symlink pointing out, a .. escape and a same-name sibling (/work/repo against /work/repo-evil) are rejected in code, not by asking the model nicely.
Run Script is withheld while scoped, because a shell runs with your full account permissions. In its place a scoped agent gets Search Code, Git (status, diff, log, branch, checkout, add, commit, push, pinned to the folder) and Open PR — enough to find a bug, fix it and open a reviewable pull request. Web Search and Web Fetch stay available: the scope governs the filesystem, not the network.
An agent behind a Chat node also borrows that chat's tools for each message's run, while its own scope still governs its file tools.
Configure
| Field | Default | What it does |
|---|---|---|
| Goal | — | What the agent should accomplish. Supports {{variable}}. |
| System Prompt | — | Persona and constraints. Optional. |
| Provider | — | One of the providers configured in Settings. |
| Model | — | Models depend on the provider; large catalogues group by vendor. |
| Temperature | 0.7 | Slider, 0 to 2. Lower is more deterministic. |
| Max Iterations | 25 | How many think/act/observe laps before it is made to answer. |
| Token Budget | 0 | Total tokens across all laps. 0 is unlimited. |
| Verify Before Finishing | On | The agent reviews its own result before completing. |
| Verification Prompt | — | Replaces the built-in verification message. Optional. |
| File Access Scope | — | Confine the file tools to this folder. Empty is unrestricted. |
| Linear Account | — | Which connected workspace the Linear tools act against, when several are connected. |
Output
Every key is available downstream as {{key}}.
| Key | Type | Value |
|---|---|---|
result | String | The agent's final answer |
steps | Number | Tool-use iterations it took |
tokens_used | Number | Total tokens across all turns |
tools_called | Array | Names of the tools it invoked |
trace | Array | The step-by-step execution trace |
budget_exceeded | Boolean | Present only when a Token Budget was set and hit |
iterations_exceeded | Boolean | Present only when Max Iterations forced the answer |
native_tool_calls_blocked | Boolean | Present only on a Claude or ChatGPT Subscription provider that rejected direct tool calls and recovered |
error | String | Failure outlet only: the human-readable message |
errorType | String | Failure outlet only: apiError, noProvider, agentStalled, agentToolContractBroken, … |
Example: a nightly repo report
Schedule fires at 7 AM. The Agent, scoped to one repo, is asked what changed yesterday. Write File saves the summary.
Paste this into the Flow Builder to get the same flow:
Every morning at 7, have an agent scoped to ~/Projects/site summarise yesterday's commits and write the summary to ~/Documents/repo-report.md.
Good to know
A destructive tool is a decision you delegate. Run Script, Write File, Apple Notes and Apple Reminders let the agent act on its own reading of the goal and the payload — including text that arrived from outside. Grant them only when the goal needs them; a flow that does asks for confirmation every time it is armed.
iterations_exceeded means the answer may be half-done. It appears only when Max Iterations ran out and the agent was made to answer. Branch on it rather than trusting result blindly.
Set a Token Budget on cloud providers. A loop that keeps finding more to do is how an agent gets expensive; the budget forces a final answer and sets budget_exceeded.