n8n-nodes-opera

n8n nodes (2.30+) for the OPERA v0.1 protocol. They turn a workflow into an OPERA agent without a hand-written manifest: the manifest is built from the workflow itself, published when the workflow is activated and updated automatically when it changes.

How it works

1. Add an OPERA Agent Trigger to the agent workflow, next to the trigger it already has (Webhook, Chat, Schedule...). It holds the description, role, sector, owner team and heartbeat cadence.
2. On the agent path, use OPERA › Action › Register. It declares the capability (id, outcomes, required evidence, dimensions, max duration) and records the action, either in executing or in a terminal state. Further along, use OPERA › Action › Update to finish it (executed, failed, cancelled).
3. reported metrics are declared in the same OPERA › Metric › Send Observation node that sends them.
4. Publish the workflow. The trigger:
   • builds the manifest from the workflow n8n hands to the trigger (the published version):
     • identity: trigger fields plus the agent_id of the credential;
     • capabilities: from the Register nodes;
     • metrics: from the metric nodes;
     • means: models, tools and MCP servers of the AI nodes around each Register;
   • validates the manifest (JSON Schema and the spec's manifest rules) and publishes it;
   • sends heartbeats at the chosen cadence and republishes if the conductor answers manifest_status: missing.

The manifest version is <base version>+<content hash>, for example 1.0.0+3f9a2c1b7d4e. It changes by itself when something in the manifest actually changes (a new capability, a renamed outcome). Changes to the rest of the workflow, such as a prompt or a business node, leave the version alone. Republishing the same version is harmless (spec README §5.4). The base version, under "Advanced Options", only needs changing to mark major changes.

An invalid manifest (a capability without a failure outcome, an expression in a declaration field, the same capability declared in two ways) blocks the activation with the error message. A conductor that is down does not: the trigger retries publishing every minute.

Credentials

• OPERA Conductor API: conductor base URL (without /opera/v0), the agent's agent_id and token. A token is valid for a single agent. It is the only credential: the nodes read the workflow from n8n's own execution context, without calling the n8n API.

Execution

• Safe retry: action_id and timestamps are stable across attempts of the same node, in the same execution and for the same item. n8n's "Retry On Fail" resends exactly the same body, and the conductor answers unchanged for what it already stored, through each item's natural key (spec README §4). Enable "Retry On Fail" on the OPERA nodes to cover 429 and 5xx.
• Agent version on actions: the OPERA node publishes nothing. It builds the manifest in process from the same running workflow, only to learn the agent_version and the capability declarations. In queue mode each worker does this on its own, with no extra call.
• Conductor without the manifest: if it answers unknown_agent_version, the item fails. The trigger is the one that publishes: on activation and whenever a heartbeat answers manifest_status: missing.
• Validation: the node validates each payload against the JSON Schema before sending. Semantic rules (declared outcome, required evidence, dimensions) are left to the conductor, which rejects the item with the error code. With "Continue On Fail", the item comes out with an error field.
• Batch: the input items of a node go in a single batch (up to 100 per request).
• Automatic evidence: evidence.trace gets { id: <execution id>, source: "n8n" }. The trace key must not be repeated under Evidence, which only accepts text values.
• Cost (spec README §3): a finished action without costs and without the "No Cost" option is sent with undeclared cost, and the conductor raises an alert. With "No Cost", it is sent as declared zero cost.
• Failure: the outcome of a failed action without an explicit outcome is the one set in the capability's "Outcome On Exception" or, when unset, the first one of class failure.
• Manual execution in the editor: runs the workflow draft and, by default, only validates and shows the payloads, without sending anything. Change it in "On Manual Execution".
• Trigger test: in the editor, the test button of the OPERA Agent Trigger shows the manifest that would be published, without publishing it.

Limitations

• One workflow is one agent. An agent spread over several workflows is not supported: each workflow would publish a different manifest for the same agent_id.
• derived metrics are declared as JSON in the trigger (Advanced Options), in the manifest format (spec section 7).
• reported metrics have a scalar value (counter, gauge, ratio, score). The automatic window ("Last Complete Window") accepts days, hours and minutes, aligned to Brasilia time; for weeks, use a custom window.
• Internal n8n field. The nodes read the running workflow through the workflow field of the n8n-core context, which is not part of the public node interface. It exists in 2.30; without it the node fails with an explicit error. Run the E2E test (test/e2e/run.sh) before upgrading n8n.
• Declarations only accept fixed values. Fields that declare a capability or a metric do not accept expressions, because the manifest must be the same in every execution.

Installation (private npm)

The package has no runtime dependencies: the schema validator is bundled at build time. Two options:

• Through the UI (Settings › Community Nodes): the n8n host needs an .npmrc pointing at the private registry. In queue mode, set N8N_REINSTALL_MISSING_PACKAGES=true on the workers, or install the package in their image.
• Without a registry: copy the built package to ~/.n8n/custom/ (or to the N8N_CUSTOM_EXTENSIONS directory) on the main instance and on the workers.

A complete example workflow is in examples/support-l1.workflow.json: Webhook, Register, answer, and Update with executed (or failed through the error output).

Development

pnpm build   # n8n-node build (tsc) + esbuild bundle
pnpm lint    # official community-node lint plus the JSDoc rules
pnpm test    # vitest: manifest builder + execution against the real conductor
bash test/e2e/run.sh   # after the build: real n8n 2.30 in Docker against the development conductor

test/e2e/run.sh starts the development conductor on the host and an n8n 2.30.0 container (N8N_IMAGE overrides the image) with the package installed as a community package. test/e2e/e2e.py then creates the credential and the example workflow through the public API, publishes it, calls the webhook (success and error), changes the workflow and checks the conductor. The script removes its container on exit.