🧑‍💻

Agent

ai.agent

Autonomous agent that uses tools to accomplish goals.

Destructive action

An Agent enabled with high-blast-radius tools (Run Script, Write File, Apple Notes write, Apple Reminders write) decides for itself when to invoke them based on the goal and incoming payload — including indirect prompt injection through templated inputs. Enable destructive tools only when the goal genuinely requires them. Workflows that enable any destructive agent tool prompt for confirmation on every arm.

Description

The Agent node goes beyond simple prompting — it creates an autonomous agent that reasons, plans, and uses tools iteratively to accomplish complex goals. The agent loops through thinking, tool use, and observation cycles until it reaches a solution or hits its configured limits.

Use it for tasks that require multiple steps, external data gathering, or adaptive decision-making that a single prompt cannot handle.

How It Works

1
Think — The agent analyzes the goal and current context, deciding what action to take next.
2
Act — The agent calls a tool (run a script, make an API request, read a file, etc.).
3
Observe — The agent reads the tool output and incorporates it into its reasoning.
4
Repeat — Steps 1–3 continue until the goal is achieved or limits are reached.
5
Verify — If enabled, the agent reviews its own result before completing.

Ports

Inlets

Input (any)

Outlets

Result (any)

Configuration

Parameter	Type	Default	Description
`goal`	textarea	—	Task description with `{{variable}}` references to payload data.
`systemPrompt`	textarea	—	Agent persona and constraints. Optional.
`provider`	provider picker	—	AI provider to use (configured in Settings).
`model`	model picker	—	Model selection. Available models depend on the selected provider.
`temperature`	number	`0.7`	Controls response randomness.
`maxIterations`	number	`10`	Maximum number of think/act/observe reasoning iterations.
`tokenBudget`	number	`0`	Maximum total tokens across all iterations. Set to 0 for unlimited.
`verify`	boolean	`true`	When enabled, the agent verifies its result before completing.
`verificationPrompt`	textarea	—	Custom verification prompt. Visible when `verify` is enabled. Optional.
`agentFileScopeRoot`	folder picker	—	Optional File Access Scope. Pick a folder and the agent's file tools are confined to it. Leave empty for unrestricted access (the default deny-list still applies). See below.

File Access Scope

By default an Agent's file tools (Read File, List Directory, Write File) can reach anywhere on your Mac that isn't on the built-in deny-list (~/.ssh, /etc, system folders, and friends). Set a File Access Scope folder to jail the agent to a single directory — for example, lock an agent to one code repo so you never have to worry about it browsing the rest of your computer.

When a scope is set, every path the agent passes to a file tool is canonicalized (symlinks and .. fully resolved) and refused unless it lands genuinely inside the folder. A symlink inside the scope that points outward, a .. escape, and a same-name sibling folder (/work/repo vs /work/repo-evil) are all rejected. The containment is enforced in code, not by trusting the model.

Run Script is withheld while scoped. A raw shell runs with your full account permissions and can read anything regardless of the folder boundary, so it can't be confined at this layer. A scoped agent is therefore shell-free — but not powerless (see the curated repo tools below).

Web Search and Web Fetch stay available under a scope — the scope governs the filesystem, not the network.

Curated repo tools

Instead of a raw shell, a scoped agent gets folder-aware tools that are confined to the repo by construction — each is enabled per-agent in the Tools list:

Search Code — greps file contents within the scope and returns matches with scope-relative paths (no shell, never leaves the folder).
Git — status / diff / log / branch / checkout / add / commit / push, run with the working directory pinned to the scope repo. The agent supplies intent (a commit message, a branch name); the tool builds the command, so it can never be redirected to another repo.
Open PR — pushes the current feature branch and opens a pull request for the scope repo via the gh CLI. It opens a reviewable PR; it never pushes to the base branch directly.

Together these let a repo-scoped agent find a bug, fix it, commit, and open a PR — using your existing git / gh credentials, and unable to touch anything outside the folder.

Output Payload

The Agent node adds the following variables to the payload:

{
  "result": "The agent's final answer or output",
  "steps": 4,
  "tokens_used": 3842,
  "tools_called": ["run_script", "api_request"],
  "trace": [
    { "type": "think", "content": "I need to fetch the latest posts..." },
    { "type": "tool", "name": "api_request", "input": "..." },
    { "type": "observe", "content": "Got 30 posts from the API..." },
    { "type": "result", "content": "Here are the top 3 posts..." }
  ]
}

Example Workflow

A scheduled workflow that uses an agent to gather and summarize information, then saves the result to a file:

The Schedule trigger fires daily. The Agent receives the goal and autonomously fetches data, analyzes it, and produces a summary. The Write File action saves the result.

Tips

Use the systemPrompt to constrain the agent's behavior and focus its tool use on relevant actions.
Set a tokenBudget to prevent runaway costs when using cloud providers.
Keep verify enabled for important workflows — it catches cases where the agent thinks it succeeded but the result is incomplete.
The trace output is useful for debugging agent behavior and understanding its reasoning process.