Workflow schema
A V2 workflow is a directed graph stored as JSON or YAML under .agentx/workflows/. The editor's canvas displays the same definition. Use agentx workflow validate <file> before importing a hand-written file.
| Term | Meaning |
|---|---|
| Workflow | The named automation definition |
| Node | One unit of work, such as a trigger, an agent call, or an output action |
| Edge | A connection from one node ID to another; a branch can choose a named output port |
| Run | One execution of a workflow |
| Pause / resume | Stops and later continues a run where supported |
Required structure
| Field | Meaning |
|---|---|
id | Stable lowercase ID using letters, digits, hyphens or underscores |
version | 2 |
title | Human-readable title |
nodes | Nonempty array of { id, type, config } objects |
edges | Connections such as { "from": "start", "to": "report" } |
state | Dispatch control: active, disabled, or quarantined |
status | Review metadata: draft, review, active, or deprecated |
Optional fields for follow-up workflows:
| Field | Default | Meaning |
|---|---|---|
autoStart | false | An agent that picks this workflow for a request starts it without telling you first. |
approval | the workflows.followUp.approval setting | When you approve person.message steps: start (all at once, when a run starts) or step (each before it is sent). |
followUp | — | { stallMinutes, maxNudges }: nudge timing for this workflow's agent steps, over the workflows.followUp settings. stallMinutes is at most 10080; maxNudges is 0 to 20. |
state controls execution. A workflow marked status: "draft" can still run if its state is active. Use state: "disabled" for a proposal that must not fire yet. A quarantined workflow is held because of a detected conflict; investigate that conflict before reactivating it.
A small example
Download demo-report.json. It contains three nodes: trigger.manual, agent, and end. The agent node uses config.agentId: "cx" and a fixed report prompt. Replace cx with your registered agent before using it outside the demo.
agentx workflow validate demo-report.json
agentx workflow add demo-report.jsonThe example is deliberately disabled. After reviewing it, set state to active, import the updated file, and test it:
agentx workflow run demo-report --watch
agentx workflow runs demo-reportagentx workflow run <id> starts only the workflow you name. It stops with an error, and starts nothing, when the workflow is disabled or quarantined, or when the entityId or chatId in the input already has a run of another workflow that has not finished.
The daemon must have workflows.enabled: true. These commands use http://127.0.0.1:18800 by default; pass --daemon <url> when working against another endpoint where that option is available.
Inputs and error handling
Node configuration can reference earlier outputs with templates such as {{trigger.payload.text}}. A manual run can supply JSON using --input '{"text":"Prepare a summary"}'. Each node may declare retry: { maxAttempts, backoffMs }; retrying an external write can repeat its side effect, so use it only when the action can safely be repeated.
Run files and the run API show a run's context, so AgentX removes credentials from it. A string field whose name ends in token, secret, password, passwd, apikey or authorization is dropped from trigger payloads and node outputs, and a template that reads one renders empty. Pass a credential to a step through envAllow and {{env.NAME}} instead.
An agent node needs a registered agentId. It can also set timeoutMinutes. When set, AgentX stops the step once that many minutes have passed and frees the agent's slot, and the step fails with "timed out after …s". Leave it empty for no limit. Give agent work room: a review or a code change can take 20 minutes or more. See time limits and cancel. An action.send node needs a live channel and destination. branch uses named ports to choose an edge; checkpoint pauses for review. Node configuration is validated by the corresponding handler, so passing the top-level file validator alone does not prove that credentials or destinations work.
Node types
| Type | What it does |
|---|---|
trigger.manual, trigger.channel, trigger.cron, trigger.hook, trigger.form, trigger.poll | Starts a run: by hand, from a channel message, on a schedule, on an on:* event, from a form, or for each new item a command prints |
agent | Runs an agent with a prompt and passes its answer on |
classify | Picks one label with a confidence; the port named after the label fires, or unsure |
transform | Picks or reshapes values from earlier steps |
branch | Chooses an outgoing port; edges match it with fromPort |
rule | Checks a declared rule and can stop the run early |
gateway.parallel | Waits for parallel branches to join |
action.send, action.react, action.editMessage | Sends a message, reacts to one, or edits one, through a channel |
action.createIssue, action.setLabel, action.readLabel, action.logTime | Creates an issue (GitLab or GitHub), or changes labels, reads labels or logs time on a GitLab issue or merge request |
action.callHTTP | Makes an outgoing HTTP request |
action.run, action.builtin | Runs a registered action, or a built-in one, by name |
signal.emit, signal.wait | Publishes a signal, or pauses until one arrives |
timer.boundary | Pauses until a timer runs out |
owner.notify, owner.ask | Tells you something, or asks you on a decision card |
person.message, person.wait | Sends a message to a person after your approval, or waits for a person's reply |
subProcess | Starts another workflow and waits for it to finish |
checkpoint | Pauses for review until a resume event arrives |
end | Closes the run with the given status |
Each type's config is checked by its handler in src/workflows/nodes/.
While an action.run step runs, its action gets a proof that it acts for the run's agent (the agent that started the run, or else ownerAgent): the environment variable AGENTX_STEP_PROOF for a shell action, in a header for an http action. The proof is not in the run's context, output or log, and it ends with the step. If the action prints the proof, or the address it calls sends it back, the text [step proof hidden] is saved in its place. Its one use is closing that agent's own card (Approvals). In a shell command, read it from the environment inside the script: $AGENTX_STEP_PROOF written in the command text is filled in from the daemon's environment before the command runs, so it comes out empty there. An http action gets the proof only when its url is on this machine's loopback address (127.0.0.1, localhost or ::1), and it does not follow redirects then. Cancelling the run ends the proof at once.
One limit to know: while a shell step runs, another program running under the same operating system user account as AgentX can read the step's environment, and so the proof. AgentX does not hide it from that account, because a program running under it can already read AgentX's own files. The proof stays narrow all the same: it closes that one agent's own cards, on this machine, until the step ends. Run AgentX under a user account that only it uses.
A run started by a webhook, a poll, a schedule or by hand has no starting agent, so its action.run steps act for ownerAgent. If such a workflow takes a card id from the trigger's payload, whoever can send that trigger chooses which of that agent's cards the step closes. Take the card id from the workflow's own steps, not from the payload.
A timer.boundary wait is kept on disk, so it still fires after the daemon restarts. If its due time passed while the daemon was off, the run moves on within a second of startup. As a safety net, the daemon also checks every minute, and once at startup, for runs that are still waiting on a timer more than two seconds after it was due. It moves those runs on and notes timer-recovered on the step's history and in the daemon log.
Wake a timer early
A timer.boundary can end early when someone writes on the work it waits for:
{ "id": "wait_review", "type": "timer.boundary",
"config": { "after": "PT30M",
"wake": { "on": ["note", "label"], "refs": "{{check.watch}}", "self": "{{check.wroteLabels}}", "minGapSec": 60 } } }refslists GitLab issues (group/project#12) and merge requests (group/project!3), comma-separated or as a list. It is rendered each time the run pauses here, so refs an earlier step found later join on the next pause.- A new note, or a label change, on one of them moves the pending timer to now. The timer itself is kept, so nothing changes when no event comes.
- Within
minGapSecof the last wake (default 60), the timer moves to the end of that gap instead: many notes give one tick now and one more at most. - A note edit, an AgentX status note, or a note carrying
<!-- agentx:no-wake -->posted from an account AgentX posts with does not wake. - Labels cannot carry that mark. A step that sets labels itself lists them in
self("group/project#12 +Doing, group/project#12 -To Do", rendered likerefs). When a label change from an account AgentX posts with is exactly a recorded one, it is the run's own write and does not wake (result=self); each record is used once. Any other label change wakes, even from the same bot account. - The node that receives the GitLab webhook passes the wake to its mesh peers, so the run may live on another node. Upgrade the nodes holding the runs first: an older node answers the wake with 400 and its timers run as before.
- Each wake logs
wake run=<id> node=<node> event=<note|label>:<ref> result=woke|debounced|self|stale, orresult=no-runwhen no run watches the ref.
Follow-up steps
These steps let a workflow work with you and with other people. How they are used: Let a workflow follow a request.
| Type | Config | Ports |
|---|---|---|
owner.notify | text (required) | — |
owner.ask | ask (required), recommend, draft, choices, expires, title, context | yes, no, expired |
person.message | channel, chatId, text (required), to (the person's name, shown on the card), accountId | sent, declined |
person.wait | reminds (a person.message step id) or channel and chatId; from, timeout (default one day), remindAfter, maxReminders (default 1 with remindAfter), accountId | reply, timeout |
- Ports. The first port listed is the main one: an edge without
fromPortleaves on it. A step that ends on another port with no edge for it stops the run, and the owner's summary says why. - Durations.
timeoutandremindAftertake minutes as a number,"30m","4h","2d", or ISO"PT4H","P2D". - Approval. A
person.messageis never sent without the owner's yes: on its own card, where the owner can edit the text, or on the run's start card when the workflow'sapprovalisstart. The start card covers only messages whose chat and text use nothing but the run's inputs (the values of itsstartstep); any other message, or one that reads differently when its turn comes, gets its own card. Cards always show the real channel and chat id, whatevertosays. - Replies. A
person.waitstep takes the next message in its chat, on its channel; that message is not routed to an agent. Its output hastext,from,fromName,media,channel,chatIdandat, so later steps read{{reply.text}}for a step with idreply. - Reminders. With
reminds, a reminder repeats the approved text of that step to the person, startingReminder:. Without it, the reminder goes to the owner.
Supervised agent steps. In a followed run (started with --follow, or by an agent), an agent step's prompt asks the agent to end with RESULT: done and the proof, or RESULT: blocked and a reason (failed counts as blocked; approved, skipped, ok and completed count as done). A step with neither waits; after stallMinutes the agent gets a nudge, and after maxNudges nudges the step is blocked and the owner is told once. An agent step's config can set:
| Key | Meaning |
|---|---|
supervise | false turns supervision off for this step in a followed run; true turns it on in a run that is not followed. |
stallMinutes, maxNudges | Override the workflow's and the node's values for this step. |
Event trigger filters
A trigger.hook node subscribes to an on:* event, such as on:gitlab-mr or on:github-pr. Its config.filter narrows which events start a run. Events that don't match are dropped before any agent is woken.
| Filter | Events | Fires only when |
|---|---|---|
topic | on:n8n | The topic in /webhook/n8n/<topic> is listed |
action | GitLab issue and MR events | The action, such as open, is listed |
mentions | on:gitlab-note | The comment @-mentions a listed username |
noteableType | on:gitlab-note | The comment is on a listed type: merge_request or issue |
assigneesAdded, reviewersAdded, labelsAdded | GitLab issue and MR events | The update added a listed assignee, reviewer, or label |
skipSelfAuthored | Events with an author | The author is not one of this workflow's own agents (off by default) |
ignoreAuthors | Events with an author | The author is not in the list. Leading @ and letter case are ignored |
maxFiresPerTarget | Issue, MR, PR, and note events | This workflow has fired fewer than count times for the same issue, MR, or PR within windowMinutes (default 60) |
Loop guard. With skipSelfAuthored: true, a workflow skips events written by the bot identity of any agent it runs, so a routine's own comment or label change cannot restart it. It is off by default, because label-driven lifecycle workflows react to their own agent's transitions on purpose. To find that identity, AgentX checks the GitLab adapter's username-to-agent map, the signature on AgentX comments, and each agent's gitlabUsernames or githubUsernames in agentMappings. If the identity can't be resolved, the daemon logs this once and only ignoreAuthors applies. On GitLab issue and MR events the identity comes only from the username map. When all agents share one GitLab token, they post as one user, which maps to a single agent, so a workflow run by a different agent won't see those events as self-authored. Comments avoid this because AgentX reads the signature on each comment.
This check can't catch two routines that trigger each other, such as a generator and a critic. Neither one sees its own identity. Use maxFiresPerTarget for that case:
{ "event": "on:gitlab-note",
"filter": { "noteableType": ["merge_request"], "ignoreAuthors": ["ci-bot"],
"maxFiresPerTarget": { "count": 3, "windowMinutes": 60 } } }A note and an update on the same MR count toward the same limit. Every loop-guard skip still claims the event, unless the trigger sets passthrough. That way the adapter's fallback (the project's default agent, or the legacy @-mention path) doesn't wake the agent instead. Every skip is logged as [workflows] <id> skipping <event> (<reason>). The counters are held in memory, so a daemon restart resets them.
Poll trigger
A trigger.poll node runs a registered action on an interval and starts one run for each new item it prints. Use it when the source can't call AgentX, such as a local store or an API with no webhook.
- id: trigger
type: trigger.poll
config:
actionId: wacli-new-messages
everySeconds: 60
key: msgId
filter:
- { kind: matches, params: { path: text, regex: "^\\s*@[Hh]akim\\b" } }
- { kind: equals, params: { path: fromMe, value: false } }| Key | Default | Meaning |
|---|---|---|
actionId | required | A registered action in .agentx/actions/. It takes no inputs and prints one JSON object per line |
everySeconds | 60 | Seconds between polls, from 5 to 86400. The next poll is timed from the end of the last one |
key | id | The field that identifies an item. A dotted path such as message.id works |
filter | none | Conditions of the same kinds as branch (equals, contains, matches, exists), with paths relative to the item. All must match |
maxPerPoll | 20 | The most runs one poll starts. The rest wait for the next poll |
The item becomes the trigger payload, so later steps read its fields as {{trigger.msgId}} or {{trigger.text}}. Item fields come from outside AgentX; treat them as untrusted in later steps.
AgentX keeps the seen keys in <workflows dir>/_poll/<workflow id>.json, so they survive a restart, and the action needs no state of its own: it can list the latest items each time. The rules:
- The first poll only records what is already there. It starts no runs. The same happens after you change
actionIdorkey. - A key is recorded before its run starts, so an item starts at most one run, even if the daemon stops mid-poll.
- An item the filter rejects is recorded too. Loosening the filter later does not replay old items.
- A poll with nothing new starts nothing and leaves no run record.
- If the action fails, times out, or prints more than 32 KB, the poll is logged as
[workflows] <id> poll failedand tried again at the next interval. It never starts a run. A failure that repeats with the same error is logged once, until a poll succeeds. - The action must exit non-zero when its source fails. An action that prints nothing and exits 0 on the first poll records an empty baseline, and the next good poll starts a run for every item it lists. In a shell pipe the exit code is the last command's, so check the source first:
out=$(my-source) || exit 1; printf '%s\n' "$out" | jq -c '.[]'. - Only an
activeworkflow polls. The daemon re-reads the workflow files every 30 seconds and onPOST /reload, so a saved, enabled or disabled workflow needs no restart.
examples/workflows/wacli-mention.yaml and examples/actions/wacli-new-messages.json show the full case: answer WhatsApp messages that start with a mention, read from the wacli store.
The editor's assistant can propose a workflow from a request. Apply to canvas replaces the current graph. Review the agent, input, destination, and error path before saving. The complete implementation is in src/workflows/types.ts and src/workflows/nodes/.
GitHub owner sweep example
The checkout includes examples/workflows/github-owner-sweep.yaml and its shell action, examples/actions/github-owner-sweep.json. The action runs scripts/owner-sweep.mjs to find missing ownership, review and CI follow-ups. It needs an authenticated GitHub CLI (gh). Adapt the repository, agent IDs, assignee and checkout path before using the example.
The action passes --review-ready-only. With this flag, draft pull requests still get an owner and failing CI is sent back for repair, but review requests wait until the pull request is marked ready. Without the flag, drafts can receive review requests too. Existing review labels and completed reviews are kept.
For a report that does not change GitHub, run from a checkout in a terminal without --assignee:
node scripts/owner-sweep.mjs --repo example/project --state .agentx/owner-sweep/example.json --review-ready-onlyThe script writes its local state file and prints RESULT steps=… followed by the proposed follow-ups. Adding --assignee <login> lets it assign issues and pull requests and add ownership/review labels. The workflow's agent handles the remaining proposed steps; the script does not merge pull requests.
Check it worked
- Terminal: run
agentx workflow validate <file>. It reports no errors. - Terminal: run
agentx workflow list. Your workflow is listed with its state. - Terminal: after a test run,
agentx workflow runs <id>shows the run and its result.
If something is wrong
- The workflow never fires: check
stateisactive(not onlystatus) and that the daemon hasworkflows.enabled: true. - An
agentstep fails: itsagentIdmust match an agent inagentx.json. - A poll trigger starts nothing: look for
[workflows] <id> pollinagentx daemon logs.poll baselinemeans the first poll recorded the existing items;poll failedshows the action's error;poll skippedmeans lines were not a JSON object with thekeyfield. - An event trigger doesn't fire: look for
[workflows] <id> skippinginagentx daemon logs; a filter or loop guard dropped the event. - A run stays paused on a timer after its due time: look for
timer-recoveredortimer … droppedinagentx daemon logs.droppednames the reason, such as a workflow that is not loaded. Such a run stays paused until its workflow loads again; the next check then moves it on. - A run stops partway:
agentx workflow trace <runId>shows which step failed and why. - A followed run stopped after
no,expired,declinedortimeout: the step has no edge for that port. Add one with thatfromPort.
