Skip to content
Flow Docs
Flow home Back to the main Flow site

Agentic and monitor

This page covers the AI-side mechanics of the agentic lifecycle. For the user-facing walkthrough, see agentic and autonomous runs.

One AI node, one decision

Section titled “One AI node, one decision”

An earlier design carried a separate cloud-AI node kind alongside the local one. In practice the two carried near-identical inspectors and execution paths, so they were merged. ai is the single generative node, and provider is the only setting that decides where inference runs.

  • provider: "local" (default) is an on-device LLM that runs through the managed server with zero egress.
  • Any other provider is a cloud frontier model. It is gated by the cloud-AI setting and a provider API key.

The egress boundary is kept at the setting level and the execution gate, not as a separate node kind. Legacy cloud-node flows are a clean break. Re-author them as ai nodes with a cloud provider.

Agentic mode

Section titled “Agentic mode”

When an ai node (local or cloud) is toggled into agentic mode, it turns its input workflow request into a flow graph on Run. That graph is previewed in a review modal before it merges onto the canvas. The node then flips into a monitor role. Generation runs against the node’s chosen provider and model. Everything else (review, monitor, interception, and fix) is the shared lifecycle.

In agentic mode the node carries a workspace (the folder generated nodes anchor their cwd / workspaceRoot to at run time) and uses input as the natural-language request.

The monitor role

Section titled “The monitor role”

A monitoring node is excluded from the executed graph. It watches instead. On an unhandled failure, it pauses the run and proposes a fix. A failure counts as unhandled when there is no explicit .fail edge, because always and pass edges do not count as handling.

  • Context-aware re-planning. The fix prompt carries the serialized current flow along with the failure observations, so the model corrects what actually ran rather than regenerating from the original request.
  • Surgical patches. A failed node is serialized on its own, and the model is asked to correct only that step. Single-node proposals are applied in place, which keeps the node’s id and edges. Multi-node proposals land as a grouped, retryable sub-flow.
  • Monitors are scoped. A failure inside a sub-flow is handled by that sub-flow’s monitor, which falls back to the main-flow monitor.

Expect assertions

Section titled “Expect assertions”

An ai node can carry an expect assertion. After it generates, the node self-evaluates its output against the expectation. This is a constrained PASS/FAIL call to the same provider and model, and the node fails when the expectation is unmet. That engages the monitor and fix path on output that is semantically wrong but did not error. A flaky evaluation call defaults to pass. Set it through the inspector’s Expected output field or the DSL.

Structured output

Section titled “Structured output”

A structured task takes the node’s output schema and prompts the model for matching JSON. It parses the result leniently, tolerating code fences and surrounding prose, then spreads the fields into the node output so each is branchable as {{node.<field>}}. On OpenAI-compatible providers, the schema also rides along as a native response_format: json_schema constraint. Other providers keep the prompt constraint.

The tool loop

Section titled “The tool loop”

With adapters bound as tools, the model calls them in a bounded in-node loop. Each call is dispatched through the real, workspace-confined adapter, and each one emits a live tool-call event line. The iteration cap is configurable per node through maxToolIters.

The tool loop is an opt-in capability for governance reasons. The node must set allowToolLoop: true and the org setting allow_agent_tool_loop must be on. Otherwise the loop is refused at run time and flagged before the run. The model can never grant itself tools.

Working memory

Section titled “Working memory”

set-variable writes {{memory.<key>}} values that persist across sessions and restarts. It is a durable key-value store that is reloaded on boot and can be cleared on demand. This state is owned by the orchestrator, which keeps it consistent with stateless models.

Section titled “Related”