Workflows

Overview

A workflow is a multi-step process you can call from a routine, an automation, or a script. Each step is a node; nodes can branch, retry, wait for approval, or hand off to other workflows. Use one when "do X" turns into "do X, then if Y, do Z, then ask a human."

The split with routines:

• A routine decides when the work happens.
• A workflow describes how it happens, step by step.

Good fits for a workflow:

• conditional branching ("if amount > $500, route to manager")
• approvals ("wait for a human reply before continuing")
• retries with backoff
• longer business processes that need to survive restarts
• handoffs between agents or between agents and people

---

A concrete example

Imagine a support agent that handles refund requests.

The routine might react when a new message looks like a refund issue. The workflow could then:

1. classify the request
2. check account details
3. ask for human approval if the amount is large
4. send the final response
5. write the outcome back to the thread

• the routine notices the moment
• the workflow runs the process

---

Building a workflow

File-backed workflow configs

Use the CLI or your coding agent to create and manage workflows as config-backed files:

archagent list configkinds
archagent describe configsamples workflow --to-file ./tmp/workflow.sample.yaml
archagent validate configs -k workflow -f ./tmp/workflow.sample.yaml

After you have a workflow shape you want to keep:

archagent sync configs
archagent deploy configs

This is the primary path for workflows. They belong in source control where your team can review and iterate on them.

When you save a workflow, the platform runs semantic validation in addition to schema validation. It checks that node references resolve, that data flowing between nodes has compatible shapes, and that conditional branches reach a terminal node. Errors are surfaced before the workflow is allowed to deploy, so broken graphs don't reach the runtime.

Portal editor

ArchAgents Portal also provides a visual workflow builder for reviewing and editing workflows:

1. Open Workflows in the portal.
2. Click New Workflow and enter a name.
3. Add nodes to the canvas.
4. Connect nodes to define execution order.
5. Save and test the flow.

The editor includes:

• Run as User selector so you can choose who the workflow runs as
• Debug mode for inspecting workflow inputs and outputs
• Auto-versioning for safe iteration and rollback

Use the portal editor when you want a visual overview of the flow or need to quickly test whether a sequence makes sense.

Workflow execution

Workflows can be triggered three ways:

1. Agent routines: attach a workflow to an agent behavior
2. Automations: run a workflow on a schedule or important event
3. Direct run: test a workflow from the portal while you build it

When a workflow starts, it receives the data from whatever triggered it.

That makes workflows reusable. You can test one from the CLI or portal, then attach it to a routine or automation once the flow is clear.

---

Node types

Workflows are built from nodes. Each node does one job in the flow.

Node	What it does
ScriptNode	Run an ArchAgents script for custom logic or data transformation
HttpNode	Make an HTTP request to an external API
ChatCompletionNode	Call an LLM to generate text or make a decision
SwitchNode	Branch the flow based on a condition
LoopNode	Iterate over items and run a subflow for each
DelayNode	Wait for a specified duration before continuing
EmailNode	Send an email
WebhookNode	Wait for an incoming webhook callback
TemplateNode	Render a Liquid template into structured output
DataNode	Transform or reshape data between steps
EntryNode	The starting point of the workflow

Most workflows use a small subset of these. A typical flow might be: EntryNode -> HttpNode -> ScriptNode -> SwitchNode -> EmailNode.

Workflow configs are YAML files. Use archagent describe configsamples workflow to see the full structure. The portal editor provides a visual view for reviewing and editing workflows.

---

Scripts and expressions inside workflows

Workflows support three ways to compute a value at a node input:

• Scripts for custom logic and multi-step data handling
• Expressions for simple conditions and field access
• Dynamic fields for inline {{expression}} interpolation in otherwise-static values

This gives you a practical mix: visual structure for the overall flow, and code only where it adds real value.

Aim for workflows where the high-level process stays visible and code shows up only where it earns its place.

Dynamic fields

A dynamic field is a static value with {{expression}} placeholders that get evaluated at runtime. Use it when you want a literal-shaped input (a string, a URL, a header value) that needs to interpolate one or two pieces of upstream data without writing a script node.

url: "https://api.example.com/orders/{{ steps.parse_input.order_id }}"
headers:
 Authorization: "Bearer {{ env.API_TOKEN }}"

The portal property panel exposes dynamic fields as a value kind alongside literal, expression, and script. Reach for dynamic when you need string concatenation or simple substitution; use expression when you need a single typed value; use script when the logic needs more than one step.

Attaching a workflow to an agent routine

Once the workflow exists as a config, a routine can point at it by config id:

archagent update agentroutine <routine_id> \
 --handler-type workflow_graph \
 --config-id <workflow_config_id>

That split is the part many teams miss:

• the workflow holds the process definition
• the routine decides when that process should run

A workflow can also be a single step inside a chain routine (handler_type: chain). When it runs as a chain step, its input is wrapped as {trigger: <event>, inputs: {<step_name>: <output>,...}}, so ScriptNodes inside the workflow address the trigger via $.trigger.<field> and upstream chain-step outputs via $.inputs.<step_name>. Workflows run directly from a routine (not as a chain step) see the raw event payload at $ as usual. See Scripts → Chain-step input shape.

---

When to use workflows vs routines

Scenario	Use
Single event → single action	Routine
Multi-step orchestration	Workflow
Conditional branching	Workflow
Data transformation pipeline	Workflow
Scheduled batch processing	Automation → workflow
Human approval gate	Workflow

Routines decide when work should run. Workflows define what should happen once execution begins.

If you are unsure which one you need, ask the simpler question:

• "Do I just need the agent to react?" Use a routine.
• "Do I need a visible process with several steps?" Use a workflow.

---

Debugging workflow runs

When a workflow fails, the run record carries structured diagnostics that point at the exact node and operation that broke. Use the CLI to inspect:

archagent list automationruns --automation <id> --status failed
archagent describe automationrun <run_id>

Each failed step in the run reports:

• the node that failed
• the operation it was performing
• the original error message from the script, HTTP call, or LLM provider
• the input shape the node received

Script failures inside ScriptNode propagate the underlying script error rather than collapsing it into a generic "node failed" message. That makes it possible to fix a workflow without re-running it locally to reproduce the issue.

The same diagnostics show up in the activity feed for each routine or automation run that touched the workflow.

---

Where to go next

1. Use archagent describe configsamples workflow to see the full YAML structure.
2. Read Scripts for the custom logic you can embed inside workflow nodes.
3. Read Automations for scheduled and event-triggered workflows.
4. Read Agents for how routines connect workflows to agent behavior.
5. Read Activity Feed for inspecting workflow runs.