n8n-nodes-hesperan

An n8n community node for Hesperan, a hosted API for calibrated decisions.

A Hesperan decision profile is one decision (for example "which team handles this ticket?") calibrated on
your own past cases, with a precision target you choose. Every answer comes back with a calibrated confidence and
an action: auto, act on it, or review, a person decides. This node turns that into two outputs, so a
workflow automates only the cases the profile clears and sends the rest to a person.

Installation · Credentials · Operations ·
Errors and retries · Templates · Compatibility ·
Development · n8n requirements · Resources

Installation

Follow the community nodes installation guide:
in n8n, open Settings → Community Nodes → Install, enter n8n-nodes-hesperan and confirm. Once n8n has
verified the node, it can also be found and installed from the nodes panel.

Credentials

Create an API key in the Hesperan console (it starts with hsp_) and add a Hesperan API credential:

Test calls GET /v1/me, which checks the key without calling the model and is not charged. A rejected key
shows "Hesperan rejected the API key"; a wrong base URL shows "No Hesperan API was found at this base URL".

Operations

Decision → Decide

Decides with a calibrated profile (POST /v1/decide/{profile}) and sends each item to one of two outputs:

• Auto: the calibrated confidence reached the profile's threshold; act on decision.
• Review: everything else, including any action other than auto; a person decides.

The item keeps its own fields and gains the result, for example:

{
	"id": 4812,
	"subject": "Charged twice",
	"hesperan": {
		"decision": "billing",
		"confidence": 0.9931,
		"action": "auto",
		"decision_id": "0f6c…",
		"probabilities": { "billing": 0.9931, "shipping": 0.0041, "technical": 0.0028 },
		"profile": "ticket-routing",
		"replayed": false
	}
}

Everything sent as state is read by the model and billed by tokens; leave out fields that do not matter. Profiles
are created and calibrated in the Hesperan console; see Decision profiles.

Decision → Report Outcome

Reports the answer that was right for an earlier decision (POST /v1/outcomes, free), for example the team
that finally handled the ticket. Hesperan uses outcomes to show the live precision of automated decisions.

Each decision takes one outcome. Reporting the same answer again is accepted (duplicate: true); a different
answer is refused (409). Report all outcomes or a random sample, not only corrections.

Question → Ask

Asks one or more typed questions about a state without a profile (POST /v1/systemone) and returns the answers
with probabilities under hesperan.answers.

Questions can also be given as the JSON questions object of the API (Questions Input → JSON).

Route by First Answer gives the node one output per option of the first question (Choice) or a Yes and a
No output (Yes/No; Yes when the probability is at least 0.5). The options must be plain text, not an
expression, because n8n draws the outputs from them. Ask answers are raw model probabilities; for calibrated,
automatable decisions use a profile and Decide.

Use as an AI Agent tool

The node is usable as a tool of n8n's AI Agent (usableAsTool). As a tool it has a single output, so all
items are returned there; the action field still says auto or review.

Errors and retries

Messages say what happened and what to do; nothing is charged for any of these.

With Retry Temporary Errors on (default), the node retries up to 3 times and waits at most 60 seconds per
attempt; the retried failures were not charged, so a retry never charges twice.

Hesperan 1 runs on serverless GPUs. The first request after a quiet period starts the model and can take about 2–3
minutes, or come back as 503 "model is starting" with Retry-After, which the node retries; later requests skip that
wait while the model is warm.

With the node setting On Error → Continue, a failed Decide item goes to Review with its own fields and
hesperan.error, hesperan.status and hesperan.description, so a person can take over. With Continue (using
error output) failed items go to n8n's separate error output instead.

Templates

Importable workflows in templates/ (in n8n: Workflows → Import from File). Each has sticky
notes with the setup steps.

The Zammad templates assume the profile's answers are your Zammad group names. Both were run end to end in
n8n 2.40.6 against local stand-ins for Hesperan and Zammad; the mailbox templates were checked against n8n's
node definitions only.

Compatibility

• Built with @n8n/node-cli 0.49.1 and n8n-workflow 2.40 (n8nNodesApiVersion 1, strict mode, no runtime
  dependencies).
• Tested in n8n 2.40.6 (Docker image n8nio/n8n:2.40.6): node and credential loading, the credential test,
  Auto/Review routing, routing by answer, Report Outcome, both "continue on fail" modes, and the two Zammad
  templates.
• Requires a Hesperan API key (the free plan includes 1M input tokens a month). The first request after a quiet
  period can take about 2–3 minutes while the serverless model starts.

Development

npm install
npm run build      # n8n-node build
npm run lint       # n8n-node lint (n8n's ESLint rules for community nodes, strict mode)
npm test           # vitest: the node against a fake HTTP layer
npm run dev        # n8n with this node loaded, http://localhost:5678

Releases are published to npm by .github/workflows/publish.yml with npm
provenance; see PUBLISHING.md.

n8n requirements followed

Checked on 24 September 2026 against n8n's current documentation:

• Scaffolding and tooling from npm create @n8n/node / the n8n-node CLI (build, lint, release, strict mode):
  Submit community nodes,
  n8n-nodes-starter.
• Publishing from GitHub Actions with a provenance statement, required for verification from 1 May 2026, with
  @n8n/node-cli ≥ 0.23.0: Submit community nodes → Publishing to npm,
  npm provenance, npm trusted publishing.
• Verification guidelines:
  one service per package, MIT license, no runtime dependencies, no environment variables or file access,
  English only, documentation, npx @n8n/scan-community-package must pass.
• UX guidelines: password
  fields for keys, resource locator defaulting to From list, Simplify for responses with more than ten fields,
  operation names and actions, error messages with a description of what to do.
• Linter: @n8n/eslint-plugin-community-nodes
  via n8n-node lint (passes with no warnings).

The static checks of @n8n/scan-community-package pass on the packed tarball and the source; its provenance
check can only run after the first release.

Resources

• Hesperan documentation: decision profiles,
  errors and limits, API reference
• n8n community nodes

License

MIT