Workflows

Overview

Workflows are executable multi-step graphs attached to an agent. Each workflow has nodes (actions, branches, joins, LLM steps, approvals, and outputs) connected into a path the Apigene engine runs from start to finish. Use workflows when you need a deterministic sequence — with branching, parallel joins, human approval, and a clear final result — rather than a free-form chat turn.

Feature	Best for
Workflows	Compiled multi-step automation with run/simulate/approve
Tasks	Scheduled or on-demand saved prompts
Skills	Reusable procedures the agent loads as guidance

Where to find them

Open Agents
Select an agent
Open the Workflows tab

From there you can list workflows, open the graph, Edit it visually, run, simulate, and delete. Create or update graphs through Copilot / Design Agent (with that agent selected) or MCP Gateway tools.

View and edit the graph

Open a workflow to see the graph:

Nodes are color-coded by type (action, condition, join, LLM, approve, output, and more)
Click a node to inspect parameters and, after a traced run, the resolved step input and output
Pan, zoom, and search steps. Toggle the mini map on or off (your preference is remembered)
Open Help on the graph or a run for node types, expressions, and limits

If you have edit access, click Edit to change the graph in place:

Add steps from the palette: Action, Condition, Approval, Set values, Result, and AI step
Drag from a handle to connect steps. Backspace or Delete removes the selected step or link
Edit the workflow name and description in the header, and inspect or update the selected node in the side panel
Click Save to compile and store the draft

View leaves edit mode and discards unsaved changes. Simulation is disabled while you are editing — leave edit mode to replay a run on the graph.

The visual palette covers linear steps plus if / approve branches. Map, switch, and join nodes created from Copilot or MCP still appear on the graph and can be inspected; rewiring those loop or case handles is done from chat or MCP.

Run a workflow

Open the workflow (or use Run from the list)
Provide runtime inputs as JSON (merged over any stored defaults)
Optionally enable:
- Include step data — keep per-step traces (required for Simulate)
- Dry run — walk the graph without live API / MCP / LLM side effects (approvals auto-pass)
Click Run

When the run finishes, Copilot shows status feedback. In chat, Run Workflow tool cards show a green / yellow / red status indicator and the workflow name.

Run statuses

Status	Meaning
`succeeded`	Workflow completed; use the final `result`
`failed`	A step failed; check `failed_step_id` when present
`waiting_human`	An approve node is waiting — use the approval card or `resume_workflow`
`waiting_auth`	Credentials needed — authenticate, then run again
`rejected`	An approval was rejected (and no reject path continued)

Simulate on the graph

After a successful run with step data:

Click Simulate (or Simulate on graph from the run dialog)
Watch steps light up from Start through the run path to End
Pause to inspect any node’s details in the side panel
Resume or Reset as needed

Simulate is the best way to demo and debug a workflow path without re-hitting live systems every time — pair it with Dry run for a fully safe rehearsal.

Human approval (HITL)

Workflows can include an approve node. When the run reaches it, status becomes waiting_human and Copilot shows an approval card:

Approve or Reject
Optionally edit preview fields before approving
The run continues via resume (same user who started the run)

From MCP clients, call resume_workflow with the run_id and decision.

Create and update workflows

Ask Copilot (with the agent selected) or Design Agent Extend to create a workflow, or call MCP create_workflow from Cursor, Claude, or other clients connected to the design MCP URL. The id is derived from the name (for example Account update → account-update). Open the new graph on the agent’s Workflows tab, click Edit, add steps, then Save. MCP clients can also create or update workflows when connected to the design MCP URL (mutations are design-only):

https://app.apigene.ai/agent/{agent_name}/design/mcp

Runtime runs use https://app.apigene.ai/agent/{agent_name}/mcp (live).

MCP tools (Agent mode)

Tool	Purpose	Mode
`list_workflows`	List workflows (`detailed` optional)	Live and design
`create_workflow`	Create with `workflow_id`, `description`, `nodes`, `connections`	Design only
`get_workflow`	Fetch one workflow	Live and design
`update_workflow`	Patch name, description, nodes, connections, or inputs	Design only
`delete_workflow`	Delete by `workflow_id`	Design only
`run_workflow`	Run with `inputs`, optional `include_data`, optional `dry_run`	Live and design
`resume_workflow`	Continue after HITL with `run_id` and `decision` (`approve` \| `reject`)	Live and design

See MCP Gateway Tools for parameter details.

Example: dry run with traces

{
  "tool": "run_workflow",
  "arguments": {
    "workflow_id": "onboard-new-hire",
    "inputs": { "email": "alex@example.com" },
    "include_data": true,
    "dry_run": true
  }
}

Node types

Common apigene.* node types:

Type	Role
`action`	Call an application operation
`if` / `switch`	Branch on conditions
`join`	Wait for parallel branches
`set` / `filter` / `summarize`	Transform or aggregate data
`map`	Iterate an array — loop body per item, then done with the collected list
`llm`	Call a language model inside the graph
`generative_ui`	Render a generative UI result from the workflow
`approve`	Pause for human decision
`output`	Terminal node that defines the public `result`

Workflows should end in an output node so runners get a clear final result.

Map (loop over items)

apigene.map follows an n8n-style Loop Over Items pattern:

Loop (main[0]) — runs once per item; use $json for the current item and $index for the 0-based index
Done (main[1]) — runs after all items succeed; $json is the collected array (also available as $node.<mapId>.json.items)
If any iteration fails, the map fails and done does not run

Wire enrichment steps on the loop port; bind tables, UI, or the final output on the done port.

Expressions

Workflow expressions use ={{ ... }} with:

Arithmetic and compares (+ - * /, == != > >= < <=)
Logical operators (&&, ||) and nullish coalescing (??)
Optional paths (?., ?[)
Helpers such as find(arr, field, matchValue[, returnField]) and filter_by(arr, field, value) for nested lookups (for example Gmail headers)

Example: ={{ $json.items?.length ?? 0 }}

Tips for demos and production

Prefer Dry run + Include step data when rehearsing
Use Simulate to walk the path on the graph after the run
Keep HITL steps for irreversible actions
Store defaults in workflow inputs; pass overrides at run time

Workflow History — org-wide run log, share, and simulation replay
Agents — workflows live on an agent
Tasks — scheduled prompts (not graphs)
Skills — procedural guidance for agents
MCP Gateway Tools — full tool reference
MCP vs Agent Modes — workflows require Agent mode

Overview

Getting Started

Core Features

Monitoring & Management

MCP Gateway

Overview

Where to find them

View and edit the graph

Run a workflow

Run statuses

Simulate on the graph

Human approval (HITL)

Create and update workflows

MCP tools (Agent mode)

Example: dry run with traces

Node types

Map (loop over items)

Expressions

Tips for demos and production

​Overview

​Where to find them

​View and edit the graph

​Run a workflow

​Run statuses

​Simulate on the graph

​Human approval (HITL)

​Create and update workflows

​MCP tools (Agent mode)

​Example: dry run with traces

​Node types

​Map (loop over items)

​Expressions

​Tips for demos and production

​Related

Overview

Where to find them

View and edit the graph

Run a workflow

Run statuses

Simulate on the graph

Human approval (HITL)

Create and update workflows

MCP tools (Agent mode)

Example: dry run with traces

Node types

Map (loop over items)

Expressions

Tips for demos and production

Related