AI agent node

Run an AI agent inside a workflow. Choose Rollout's model loop or an installed Claude Code, Codex or GitHub Copilot CLI harness. The agent reads a prompt, calls its attached tools and returns text and validated structured output. The Rollout harness also supports streaming, durable memory and your own provider keys.

Status: Alpha. Node ID: rollout.ai.

Configuration

Settings are grouped under Agent, Tools and Output. Conversation and advanced controls stay within Agent.

Harness and machine

Harness chooses the agent loop. Rollout uses the app's model list and provider account. The installed CLI harnesses use the CLI's existing login on the selected machine, including its subscription when applicable. Switching harnesses retains inactive settings without granting their access or billing.

For a machine harness, Run on chooses:

• Registered device — select an available Rollout desktop device with the AI agent permission enabled. The desktop's local approval settings apply.
• Remote (SSH / Tailscale) — choose an SSH key connection, or passwordless authentication with a host and user. Attach the workflow connectivity service for Tailscale routing. The CLI runs on that destination and keeps its local authentication. An unreachable destination fails; it never runs the CLI on the application server instead.

Set the working directory and the harness's model and machine-tool permissions. Remote working directories must be absolute paths. The command timeout defaults to 300 seconds and can be set from 10 to 600 seconds, within the workflow's limits.

Claude Code offers its runtime default, model presets and a validated custom model ID. Its read-only mode restricts built-ins to Read, Glob and Grep and rejects broader allowed-tool lists. When Claude Code waits on background work (a background command, a Monitor), it answers again once that work finishes; the step keeps the last answer and fails if any answer failed. Codex offers execute/review modes and an explicit sandbox. These settings do not replace the machine account's security boundary. Attached Rollout tools remain separately governed by their capabilities.

On a registered device, a turn with no attached Rollout tools, run as a workflow step, waits for the device without holding a server once the device reports the start, so a server deploy or restart neither fails the step nor stops the CLI. The device's result resumes the run on whichever server receives it, with the same output and execution.harness_session_id as an uninterrupted turn. The command timeout still applies: a result that arrives after it fails the step with client_command_timeout, keeping the session reference so you can continue it. This needs Rollout desktop 0.1.3 or newer; an older app, an SSH target, a turn with attached Rollout tools, an App Tool call and every step of a session run keep the in-process wait and fail when their server restarts. The stored result keeps the answer and the session, not the CLI's console stream.

Machine harnesses currently accept completed prompts and working-directory files. Native live input turns, dataflow streaming, model-loop hooks and binary attachments are rejected before dispatch. Reported CLI usage is external; Rollout does not charge it as managed inference.

Continue a machine session

Pass execution.harness_session_id from a previous execution to the next agent's Harness session setting or harness_session_id input. This opaque reference binds the tenant, harness, target and directory allocation. A raw CLI UUID is insufficient. Switching harnesses requires a new session or an explicit handoff of the task and artifacts. Native memory keys remain separate.

Codex Review returns validated execution.findings and derives execution.has_issues from that list. An empty list certifies no findings; missing, inconsistent or malformed output remains an error. Start an independent review with no session reference. Resume an existing review only to continue it.

Rollout model settings

Tools section

Conversation (Rollout harness)

Models

The Model picker is driven by the platform model catalog. Gemini models are always available on the managed key; other managed models depend on your plan. Selecting a BYOK key hides the managed picker — enter any model your provider offers in the BYOK Model field instead. A model outside the catalog (or outside your plan) is rejected before any provider call.

Inputs

Outputs

Tool calling

Add tools in the Tools section. Add tool opens the same picker as adding a node, with your MCP connections beside the nodes. Any tool-capable node can be a tool, grouped by capability: Records, Gmail, Google Drive, Google Sheets, Jira, Web & messaging, Infrastructure & CI, and Workspace. Another AI agent can be added as a tool too, delegating an open-ended subtask to a sub-agent (nesting is budget-limited per run).

For each tool, every setting of the underlying node is either:

• AI — the model fills the value. You can mark it required and add a description to guide the model.
• Fixed — you set the value; the model never sees or overrides it. Useful to pin an object or query source while the model chooses the rest.

Tools that need a Connection get a Connection picker. A custom name and description per tool steer how the model understands it.

Attach each tool the agent needs. Machine harnesses receive a temporary MCP connection that exposes only those tools and preserves their fixed settings, current permissions and approvals. Attached tools can themselves run on a registered device, so one agent can combine remote execution with configured device capabilities on demand. Device consent and capacity still apply.

For a tool requiring approval, the CLI stops before Rollout records the approval handoff. Registered devices are interrupted; SSH waits for verified turn completion. Resume retrieves the stored approved or denied result without dispatching the same tool effect again. A missing stop receipt cannot advance the approval.

Ask people and wait for their answers

In a Task workflow, a Codex or Claude Code agent can ask the people on its Task a question in the middle of its work. Attach a Save to workspace tool set to Activity, type Ask. The agent fills the question, the options to pick from, the one it recommends, markdown context and a Mermaid diagram people can leave notes on. The question lands on the Task and in its owner's Inbox, and the call returns at once, so the agent keeps working on what does not depend on the answer.

When the agent's turn ends while one of its questions is still open, the step pauses instead of finishing. Each answer resumes the same CLI session with every answer so far (the picked option, the notes on diagram elements and the comment) and the questions still open; an answer that arrives while the turn is still running is passed on in a new turn as soon as it ends. The agent can replace a question an answer made moot, ask a follow-up, or end its turn again to keep waiting. Once no question is open, its last turn's answer is the step's output.

The questions have no deadline and the paused run has no suspension timeout: it waits until people answer, cancel the question, or cancel the run. Reassigning, completing or archiving the Task cancels the paused run and its open questions. A paused run still counts toward the workflow's concurrent-run limit, but it gives its device back, so other Tasks bound to the same device run while people answer. The resume needs the same device and working directory and the same node settings; a step whose settings changed while it waited fails instead of resuming. When the device is offline, busy or taken by another Task, the resume waits for it and continues once it is free.

Structured output

Declare structured fields in the Output section under Response fields. Each entry declares a field the model must generate: an ID, a type, an optional description that steers generation, and a required flag. Each entry becomes its own output port you can wire directly; the full parsed object is also available at output.structured.

When structured fields are declared, a reply that does not parse against them fails the node instead of passing bad data downstream.

Streaming replies

The deltas output streams reply tokens as the model generates them, while tools still run between requests. Wire deltas into the Reply in chat node's body input to stream the reply live into the conversation that triggered the run. Wire events into that node's thinking input to show the model's reasoning as a live collapsible section.

Memory threads

Set a Thread Key to give the agent durable memory: the full context — including tool calls and results — persists under the key and is restored on the next execution. Use it for loop iterations within a run or continuity across runs (for example, a per-customer key templated from the trigger). Use Replay Window and Replay Token Cap to bound how much history is restored, and Compaction to summarize older turns instead of dropping them.

Hooks and approvals

Wire the callback output to a handler node to supervise the agent's loop. The engine calls the handler at lifecycle points (before a turn, on tool calls) and waits for its verdict: continue, halt (stop the loop, keeping the partial result), inject (add context to the next request), mutate the request or result, retry, or suspend the run for a human decision. A suspended run resumes with the decision once a human responds. Suspension applies to batch runs; a run that is actively streaming cannot pause mid-stream.

Stop conditions

Declarative loop halts — stop after N steps, after a specific tool call, on a token budget, a timeout, or a text match — can be set on the node through the workflow API. They are not editable in the sidebar.

Limits

• Max Iterations: 1–20 tool calls per request.
• Token Budget: optional cap across all iterations; when exceeded the node returns partial results with an error.
• Node timeout: 10 minutes.

Tips

• Be specific in prompts and describe the output you want.
• Declare response fields for reliable downstream automation.
• Wire upstream values into the prompt with {{ }} templates instead of copying them by hand.
• Lower Max Iterations or set a Token Budget while testing to keep runs predictable.
• Fix tool settings you don't want the model to control by switching them to Fixed.

Troubleshooting

Empty output

• Check that the prompt is not empty.
• Check the errors output for rejected attachments.

Model errors

• "Not in the model catalog" or tier errors: pick a model from the catalog, or use a BYOK key.
• A BYOK key with no model set fails before any provider call — fill in BYOK Model.
• A BYOK key that cannot be resolved rejects the call; there is no fallback to the managed key. Check the selected Connection.

Tool calling not working

• Ensure Enable Tool Calling is on.
• Check each tool's required fields — a Fixed field needs a value from you.

Structured output fails

• The reply must parse against the declared response fields; the node fails rather than emitting unparsed data. Simplify the fields or add descriptions to guide the model.

Codex controls

Reasoning effort (codex_reasoning_effort) offers model default (blank), low, medium and high. It applies to new, resumed and review turns. Codex ignores user configuration, so your local effort preference does not apply.

Deny git push and gh (codex_deny_push_gh, default false) stages temporary PATH wrappers that reject ordinary git push and all gh calls. Commit, reading fetched refs and local tests remain available under the selected sandbox; Review always uses read-only. Ambiguous Git global options are denied. Login shells and profile loading are disabled to preserve the controlled PATH. This is a cooperating-CLI control: absolute executable paths, replacing PATH, executable aliases, explicit shells and direct API clients can bypass it. Credentials remain accessible on the machine; this setting does not isolate credentials or sandbox full access. No credentials are copied into wrappers, and denial messages never echo command arguments. The existing device/SSH transport removes temporary material after the turn.

Attached Rollout MCP tools bypass the redundant Codex approval gate through default_tools_approval_mode="approve"; Rollout still enforces their authority and server-side approvals. Verify ordinary and resumed shell behavior on your selected device before publishing workflows with denial enabled.