The workflow graph
A workflow is a directed graph of typed nodes joined by edges. It has three parts:- The workflow — its stable identity, owner, description and tags.
- Published versions — immutable snapshots. Each publish creates a new version with the next version number; at most one version is active at a time.
- The draft — the editable workspace. The Console graph editor, the HTTP API and the Workflow Architect all edit the draft; publishing copies the draft’s nodes and edges into a new version.
Node types
Edges
After a node completes, each outgoing edge is evaluated:- Unconditional edges are always active; the downstream node becomes eligible.
- Conditional edges are evaluated against the completed node’s output, for example
output.score > 0.8. Routers are their main users. - Error edges activate only when the upstream node fails, so you can route failure handling.
Example: a code review pipeline
- analyze-code — Agent node assigned to an AI agent.
- severity-check — Router: high severity goes to human review, low to auto-fix.
- Parallel branches: human-review (Agent node assigned to a person, prompted in Slack) and auto-fix (Agent node assigned to a Factory Worker).
- merge-results — Join, waiting for all branches.
- post-summary — Publish to a webhook.
Concurrency
Before an AI-assigned Agent node is dispatched, it takes a concurrency slot for its agent. The agent definition’s maximum concurrency (default1) caps how many dispatches of that agent can run at once; slots are taken and released atomically.
Execution phases
Start a run
A production run pins an immutable published workflow version. A test run references its selected draft. Launch validates declared workflow inputs before execution; a rejected launch does not become a running workflow. Scheduled triggers are live. The evaluator claims due work, and the fire path re-reads the trigger before launching. Paused, changed, or no-longer-authorized triggers must still pass their current checks. Use Schedules to inspect the trigger and the resulting run; the existence of a schedule alone does not prove a run launched. Launch authorization and node dispatch authorization are separate boundaries. Permission to start a workflow does not grant every downstream tool or credential.Walk the graph
Readiness is evaluated from graph state rather than a fixed list of precomputed layers. Conditions select reachable branches, joins coordinate their declared inputs, and error edges route failure handling. A node that is waiting on an approval, human answer, or detached result is still owned work; waiting does not imply the graph is finished. The orchestrator resolves declared inputs from upstream outputs before dispatch. File inputs use recorded file bindings. Connection and capability resolution checks the authority for the current dispatch rather than accepting a credential identifier emitted by an agent.Govern and wait
An approved hold authorizes its specific continuation. The resumed owner still performs the operation and records its result. Approval does not prove that an external effect occurred. See Governance pipeline and Approval lifecycle.
Execute agents and procedures
Agent configuration combines the selected definition, pinned workflow constraints, allowed tools, skills, and current dispatch facts. The turn records its thread so Console can display messages and tool activity. For a structured agent turn:- Stream text with the output contract and the allowed tool set.
- Parse the final text and validate it against the declared schema.
- If parsing or validation fails, request structured repair from the same conversation context.
- Accept only a valid result, then record its output and usage, including repair usage when present.
file_put to write and bind the file, then returns the recorded file identifier in its structured output. A filename mentioned in prose is not a workflow file binding.
Inline and detached agents run the same turn logic. The transports own message delivery, tool callbacks, cancellation, and execution placement. See Data flow end to end.
On validation failure, a person-assigned step re-opens its task. An inline AI agent on a workflow
that uses outcome routing is re-prompted with the validation feedback, at most 5 times per run
attempt, and only when its rejected turn called no tool; otherwise the node fails with a validation
error. A detached agent’s rejected output always fails the node. Error edges can route the recovery.
See Let an agent correct a rejected output.
Agent memory on workflow nodes
An AI agent on an Agent node remembers across runs when its agent definition turns memory on (memory.type set to session, persistent or vector; absent or none is off). The same rule applies to inline nodes, detached nodes and debug attempts.
- Recall. Before the turn, Forge retrieves up to 5 of the agent’s long-term memories (from the run’s project, plus memories with no project) and up to 3 facts, and puts them in front of the node prompt under a
## Your memoryheading, within 8,000 characters. When the budget is exceeded, long-term memories are dropped first, then facts. If retrieval fails, the node runs without memory. - Proven cases. An AI-assigned Agent node can set
autoInjectCasesfrom 0 to 5 (absent or 0 is off). Recall then also searches the knowledge the agent can read for active cases gradedproven, and adds that many under a## Proven casesheading, each with its[ref:k…]citation ref. A case the agent cites earns a use and an outcome, like a cited search hit. Cases share the 8,000-character budget and are dropped last. The setting lives on the node, so one agent can use cases in one step and not another. An out-of-range value is refused when the node is saved, and blocks publish withAUTO_INJECT_CASES_OUT_OF_RANGE. - What was recalled. A production run records each recalled memory, fact and case per node, so the run inspector shows what the agent saw. Debug attempts recall but record nothing.
- Record. When the step completes, Forge extracts the noteworthy facts, decisions and actions from the node’s prompt and output (each cut to 4,000 characters) and stores them as the agent’s memory. A failed step records one failure episode instead. Person-completed steps, non-Agent nodes and debug attempts record nothing. On a factory run, the factory manager’s step memory is recorded too.
Trusted knowledge inputs
A procedure input may declaretrustedKnowledgeContext: true with exactly one upstream object
source. This tells dispatch to replace the upstream agent’s claimed knowledge context with evidence
recorded by that source node’s knowledge_search call. The agent’s refs, excerpts, scores, and
terminal status are not treated as authority.
For each workflow search, Forge records a server-owned retrieval marker and the exact bounded native
excerpts that were displayed. At dispatch, the resolver selects the newest marker from the source
node’s effective, non-superseded completion lineage. The result is one of:
A partial restart downstream of retrieval keeps the surviving source completion, so it reuses that
completion’s recorded terminal and excerpts. Restarting from the retrieval node supersedes the old
completion and requires the new search marker; a new empty, denied, invalid, or relevant terminal
wins. Late or legacy rows cannot revive evidence from a retired attempt.
Relevant context remains fail closed at use time. Forge rechecks the retrieving agent’s current
knowledge:read authority, run-scoped namespaces, source restrictions, and each case’s active grade.
It recomputes native citation refs and rejects the whole context if rows are missing, mixed,
malformed, over the eight-hit limit, moved, retired, deleted, newly restricted, or otherwise
unresolvable. The recorded excerpt remains immutable when source text later changes because it
captures what the retrieval agent actually saw. Federated results stay external and do not become
trusted native context.
For the Freshservice triage workflow, trusted knowledge supplies evidence to the
routing and field-selection procedures. The Freshservice records of the declared Knowledge source
supply allowed values and relationships; they do not supply narrative policy. A separate narrative agent writes the private
summary. The apply procedure then revalidates proposed fields against the same records and
issues at most one combined ticket PUT with single_attempt; notes and requester replies are
reported as separate effects.
Operators publish this graph only through the governed draft authoring flow after reviewing the
source-owned release graph and confirming the Knowledge source and the Knowledge grants. Repository
fixtures contain no production workflow, source, credential, draft, or version identifiers, and
building or merging them does not install a Freshservice workflow or perform a live ticket write.
Completion and recovery
Read both run status and handling evidence. On the current execution-evidence contract, a fully covered graph with a handled failure can finish ascompleted with handlingSummary.disposition: "failure_handled". An unresolved failure yields failed; cancellation is recorded separately. Older runs without this evidence can retain legacy status semantics. The failed node’s details remain useful even when a handler completed successfully.
Do not infer that a provider write failed solely because the observer timed out. Read the recorded attempt, completion, and effect evidence before retrying. Detached execution has its own completion and deadline paths; watchdogs provide recovery for lost or stalled ownership rather than a promise of immediate completion.
Data flow end to end
Every agent dispatch — not only workflow nodes — follows the same path from trigger to recorded result.1. Trigger and dispatch site
Agents are prepared per dispatch, not kept as long-lived instances, so each turn uses the agent’s current prompt, skills, tools and constraints. A change to an agent definition takes effect on its next dispatch.
2. Composition
The dispatch site composes the agent’s configuration from its definition:- Load the agent definition. Only
executionModel: "native"(or no value) composes. - Resolve the prompt, including a prompt-library reference when the definition has one, plus any per-call extension.
- Resolve skills: the agent’s permitted skills, intersected with any skills the workflow node requests, within the skill token budget: the node’s
maxSkillTokenshint, else the agent’sconstraints.maxSkillTokens, else 32,000 tokens. Analwaysskill’s content goes into the system prompt; anon_demandskill appears in a menu and is loaded with theload_skilltool. - Merge the agent’s permitted tool sets into one tool set. If an active skill declares allowed tools, any other tool call returns a refusal the model can see and adapt to;
load_skillis always allowed. - Build the language model from the agent’s routing tier, or a per-call override.
- Attach usage recording, so every turn’s tokens are attributed to the agent and, for workflows, to the run and step.
agent_dispatch_composed audit event with the resolved skills, tool sets, model and warnings. For workflow nodes, the governance decision records the same capability summary instead.
3. Governance on every dispatch
Every dispatch surface runs the Trust Fabric gate sequence before the agent executes — see the Governance pipeline for the gates. The sequence is fail-fast: oneblock stops execution, hold waits for a person, pass continues. When a gate blocks, the remaining gates are recorded as skipped rather than omitted, and a gate that does not apply to the dispatch is recorded as not applicable. An agent with no definition is itself a block (agent_not_found). Each decision records its disposition, per-gate results, scope constraints and the capabilities composed for the dispatch.
4. Agent turn and tool calls
The turn runs in a durable thread — one per workflow node, or one per chat session — and every prompt, tool call, tool result and response is saved for audit. A step cap bounds each turn: 10 model steps for an inline turn, and for a detached turn the agent’sconstraints.maxToolCalls, which defaults to 10. Token deltas stream to the Console as the agent writes.
Each tool call is logged with its status: started, completed, failed, blocked or refused_by_skill_constraint. A sandbox is a tool, not a layer: only dispatches given sandbox_action can reach one. See Configure a sandbox.

