Skip to main content

N8N Integration

n8n is a workflow automation tool. With the AION community node, an n8n workflow can send a question to an existing AION agent profile and use the answer in the next steps (for example: summarise an incoming email, then post the summary to a channel). This page is for administrators and integrators who build n8n workflows; it explains what to set up on the AION side and how to configure the node credentials.

The community package lives in a separate repository: n8n-nodes-aion (sibling of this monorepo). Keep packaging, npm publish, and n8n CLI tooling there; this document describes the AION-side contract and how to wire credentials.

Architecture​

n8n workflow
└─ AION Agent node (credentials: Base URL + API key)
├─ GET /profiles → profile dropdown
├─ POST /v1/chat → Ask (sync JSON)
└─ POST /v1/conversations → Create conversation (optional multi-turn)

Prefer POST /v1/chat over SSE (/v1/chat/stream). n8n HTTP nodes do not consume Server-Sent Events cleanly; the sync endpoint drains the agent pipeline until a final result (or timeout).

Prerequisites (AION)​

  1. AION API reachable from the n8n host (same Docker network, or public URL via Caddy).
  2. An API key created by the user the workflow acts as, from chat-ui → Settings → API keys (the admin must first enable API keys for that user in admin-ui → Users). See API keys:
    • Ask and profile dropdown: scope chat
    • Create conversation: also conversations:write
  3. At least one profile under config/profiles (e.g. aion_std).

Base URL tips​

DeployBase URL example
Local uvicornhttp://localhost:8001
Docker Compose + Caddyhttps://cliente.example.com/api
Dev compose (backend only)http://localhost:8001

Do not add a trailing slash.

Sync chat API​

POST /v1/chat (Requires Chat Auth / API key with scope chat)

Request:

{
"message": "Summarize yesterday's incidents",
"profile": "aion_std",
"conversation_id": null,
"message_source": "internal_trigger",
"timeout_seconds": 300
}
FieldNotes
messageRequired
profile / profile_slug / profile_nameDefault aion_std
conversation_id / session_idOmit to auto-create
message_sourceDefault internal_trigger for automation
timeout_secondsDefault 300, max 3600; returns 504 on timeout

Response:

{
"text": "…",
"conversation_id": "uuid",
"session_id": "uuid",
"profile": "aion_std",
"success": true,
"charts": []
}

Profiles for the dropdown​

GET /profiles (Requires Chat Auth / API key with scope chat) — returns the profiles allowed for the caller (same list used by chat-ui; for a key, the profiles allowed for its owner).

Install the community node​

See the package README in n8n-nodes-aion for npm / local / Docker install.

Quick local link:

cd /path/to/n8n-nodes-aion
pnpm install && pnpm build
# then N8N_CUSTOM_EXTENSIONS=/path/to/n8n-nodes-aion (or npm link into ~/.n8n/custom)

Example workflow​

  1. Create credentials AION API (Base URL + key).
  2. Add node AION Agent → Resource Agent → Operation Ask.
  3. Pick a Profile from the dropdown.
  4. Set Message (expression OK, e.g. {{ $json.body }}).
  5. Use {{ $json.text }} downstream (Slack, email, HTTP, …).

Multi-turn: Conversation → Create, then Ask with conversationId = {{ $json.id }}.

Security notes​

  • Do not use unauthenticated POST /a2a/invoke from n8n in production.
  • Prefer a dedicated API key with least privilege (only the scopes you need) and a short expiration.
  • The key acts as its owner: conversations, LTM/STM and allowed profiles are the owner's, and user_id in the body is ignored. For isolated bot memory, create the key from a dedicated user (e.g. n8n); use a person's own key when the workflow acts on their behalf.