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.Where to find them
- In the Design workspace, open Build → Agents
- Select an agent
- Open the Workflows tab
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. The inspector shows how long that node ran
- View and edit use the same Input, Logic, and Output panel
- Pan, zoom, and search steps. Toggle the mini map on or off (your preference is remembered)
- Layout switches the graph between Row, Wrapped, and a Steps list
- Open Help on the graph or a run for node types, expressions, metrics, and limits
- Add steps from the palette, including Action, Condition, Approval, Wait, Set values, Result, and AI step. Classify steps are authored from Copilot or MCP and can be inspected on the graph
- 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
The visual palette covers linear steps plus if / approve branches. Map, switch, join, and classify nodes created from Copilot or MCP still appear on the graph and can be inspected; rewiring loop or case handles is done from chat or MCP.
Publish as an API
On a workflow, open API (Configure OpenAPI) to publish it as an authenticated HTTP endpoint.- Set the description, HTTP method, and path. The URL uses the agent slug
- POST and PUT send inputs as a JSON body. GET and DELETE send them as query parameters
- View or download the OpenAPI document
- Test runs the endpoint from the dialog. curl copies that same call. Set
APIGENE_API_KEYto an API key from Settings → Organization, then run the command in a terminal. If the run pauses for approval, the panel shows the approval and lets you approve or reject - Unpublish removes the endpoint
POST /api/workflow-apis/{agent}/{slug}/runs/{run_id}/resumewithdecision(approveorreject), optionaledits, and optionalreasonGET /api/workflow-apis/{agent}/{slug}/runs/{run_id}to read the run without deciding
status is waiting_human, read approval and run_id, then POST a decision. The response uses the same fields as the first call. Another approve node later in the workflow returns waiting_human again. Any caller who can invoke the API can resume that run.
Docker service
On the agent’s Versions tab, Docker service downloads a zip of the published workflow APIs you select. The file name describes what it contains. After the download, copy the run steps: setSERVICE_API_KEY in runtime.env (callers send it as a bearer token), build and run, then open http://localhost:8080/docs and authorize with that key.
The image carries this installation’s OpenLegacy license. Workflows run while that license is valid. After it expires, starting a workflow, resuming a run, and voting on an approval return 403 and name the reason. The download is refused until an active license is uploaded under Settings → Organization → OnPrem License. A trial, an expired license, or an invalid license cannot be exported.
To renew, upload the new license and export the service again. To apply a renewed license without exporting again, mount the license file and restart. A mounted file overrides the license in the image. The bundle README has the mount command. Add it to every container of the service, including the Temporal worker.
The build uses the workflow runtime image from this installation, so a host with no internet uses the image that came with the install.
If a selected workflow has an approve node, the zip includes that workflow’s resume and status routes. Set WORKFLOW_RUN_STORE_PATH (the example uses /data/workflow-runs.json) and mount a volume on that file so an approval still resumes after a restart.
The download dialog includes an optional Temporal setup. Leave those lines blank and the graph runs in this container. A restart drops a run that is still going.
Setting local disk and a Temporal address together fails startup. For Temporal Cloud, also set the namespace,
TEMPORAL_API_KEY (the Temporal key, not SERVICE_API_KEY), and a task queue used only by this service. With that key the connection uses TLS.
Business metrics
When a selected workflow declares metrics, the service records each succeeded run and reports the newest readable value as the gaugeworkflow_metric_value. Mount a volume on WORKFLOW_METRICS_STORE_PATH (the example is /data/workflow-metrics.jsonl) on the HTTP container in every mode, including Temporal. The worker does not need that volume. The file is not pruned.
GET /workflow-metrics/{slug} with Authorization: Bearer <SERVICE_API_KEY> returns the history. from and to are optional dates. In Temporal mode the HTTP container reads finished runs about once a minute (WORKFLOW_METRICS_SWEEP_SECONDS, default 60).
The zip includes observability/workflow-metrics-dashboard.json, one panel per declared metric. Import it into Grafana and choose an Infinity data source for this service. The bundle README has the data source URL, the bearer header, the row columns, and how to alert on the gauge without a false no-data alert.
Traces
SetOTEL_EXPORTER_OTLP_ENDPOINT to send traces to your collector. Each node span stays open while the node runs. Outbound calls and the approval webhook carry W3C traceparent, and tracestate when one is present, so a service that uses OpenTelemetry continues the same trace under that node. Leave the endpoint unset and those headers are not sent. The bundle README lists the other OTEL_* settings.
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
Run statuses
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
Human approval (HITL)
Workflows can include an approve node. When the run reaches it, status becomeswaiting_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)
resume_workflow with the run_id and decision. That call stays limited to the user who started the run. A published workflow API uses the resume route under Publish as an API, and any caller who can invoke that API can resume its runs.
Leave policy empty and the stage stays that single decision. decidedBy is a string, and a dry run approves without calling a webhook.
Set policy when more than one person must vote. One approve node is one stage. Chain nodes for several levels.
Each approver is a
channel and an id. user is the sign-in subject. email is an email address. slack, or any other short channel name, is an id your own app understands. Apigene does not send Slack or email. The id may be an expression. The same person on two channels is two votes. At most 8 approvers.
When a policy is set, a signed-in person can vote only as user or email. Every other channel votes with a token. decidedBy is {channel, id}, and decisions lists the votes. Vote tokens never appear on the run result.
Notifications go to the approval webhook on the agent Setup tab. One webhook covers every workflow of that agent that has an approval step. Apigene POSTs a signed approval.requested, approval.updated, or approval.completed event. Each event includes workflowId and agentId. approval.requested includes one voteToken per approver. The HTTP response is ignored and cannot approve the run. Your app routes the notification and later calls POST /api/workflow-approvals/votes with Authorization: Bearer <voteToken>.
An exported workflow service does the same when APPROVAL_WEBHOOK_URL and APPROVAL_WEBHOOK_SECRET are set. An approve node with no policy still resumes with {"decision":"approve"} and the service API key.
Create and update workflows
Ask Copilot (with the agent selected) or Design Agent Extend to create a workflow, or call MCPcreate_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}/mcp (live).
MCP tools (Agent mode)
See MCP Gateway Tools for parameter details.
Example: dry run with traces
Node types
Commonapigene.* node types:
Workflows should end in an output node so runners get a clear final result.
Code
A Code step runs Python or JavaScript. Assignresult, and that JSON value is the next step’s data. The timeout is 1 to 30 seconds, and the default is 5.
Python can import re, json, math, and datetime, including date, datetime, and timedelta. strftime and strptime work. Any other import fails the step. open, eval, exec, getattr, compile, and globals are not available. A Python date or datetime in result comes back as an ISO-8601 string.
JavaScript provides the language and console.log.
Groovy is stored and highlighted. A run does not execute it. The step result is the source (language and code), so a later step can pass the script on.
Metrics
On a Result step, expand Metrics to chart numbers from the result over time. Each metric is a path into the JSON, such askpis.closing_rate. Choose number, percent, count, or currency, a line or bar, and an optional target. Percent means the value is already in percent (14.5, not 0.145). One metric can be the headline. A list of objects can be split into one series per item.
Period read from points at a month (2026-10), an ISO week (2026-W44), or a day (2026-10-31) in the result. Each period keeps the latest successful run. Leave it empty and every successful run is a point at the time it ran. Failed runs are ignored.
Charts appear under Monitor → Insights → Workflows. Open a workflow for its metric charts and the runs in the selected dates. Metrics need Full recording under Workflow Recording. An agent export keeps the metrics with the workflow. A downloaded workflow service reports the same declarations to your own Grafana.
On error
Each step has Advanced → On error:
Authentication failures (
waiting_auth) always stop. Sign in, then run again.
Sub-workflow
apigene.workflow runs another saved workflow on the same agent and waits.
- Workflow id — the saved workflow to call. It can be an expression.
- Inputs — values passed into that workflow. They override its stored defaults. The next step reads the called workflow’s public
resultas$json. - Success (
main[0]) runs when the call succeeds. Failure (main[1]) runs whenonErroriscontinueand the call fails. - The called workflow has to be on this agent. A cycle, a chain longer than 5 workflows, or a missing id fails the step.
- A called workflow that would pause for a person or for login fails the step. The parent does not pause with it.
- To run it once per item, put the node on a map loop port.
Map (loop over items)
apigene.map follows an n8n-style Loop Over Items pattern:
- Loop (
main[0]) — runs once per item; use$jsonfor the current item and$indexfor the 0-based index - Done (
main[1]) — runs after all items succeed;$jsonis the collected array (also available as$node.<mapId>.json.items) - If any iteration fails, the map fails and done does not run
Classify
apigene.classify sends a payload and 1–20 named questions to TypeSafe Jev and returns typed answers you can branch on.
- State — the data Jev reads (literal or expression). Send only the fields the questions need
- Questions — each question is a choice, a score, or noul (yes/no). Choice questions should include an unclear option rather than blending “unclear” into a confidence score
- Model — optional Jev model version (default
jev-1.13.0)
$json.answers.<name>, plus model and usage. Switch or If can branch on an answer. The success port is main[0]; an optional error port (main[1]) is used when onError is continue.
An admin must add a TypeSafe Jev API key under Settings → Organization → Model Settings. Classify does not use the chat model list. Dry run walks the step without calling TypeSafe.
The graph inspector shows each question and answer, including the score legend next to score answers. Ask Copilot or the design MCP to add the step; the visual palette does not author classify nodes.
Expressions
Workflow expressions use={{ ... }} with:
- Arithmetic and compares (
+ - * /,== != > >= < <=) - Logical operators (
&&,||) and nullish coalescing (??) - Optional paths (
?.,?[) - Helpers such as
find(arr, field, matchValue[, returnField])andfilter_by(arr, field, value)for nested lookups (for example Gmail headers)
={{ $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
Related
- 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
