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)
- AION API reachable from the n8n host (same Docker network, or public URL via Caddy).
- 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
- Ask and profile dropdown: scope
- At least one profile under
config/profiles(e.g.aion_std).
Base URL tips
| Deploy | Base URL example |
|---|---|
| Local uvicorn | http://localhost:8001 |
| Docker Compose + Caddy | https://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
}
| Field | Notes |
|---|---|
message | Required |
profile / profile_slug / profile_name | Default aion_std |
conversation_id / session_id | Omit to auto-create |
message_source | Default internal_trigger for automation |
timeout_seconds | Default 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
- Create credentials AION API (Base URL + key).
- Add node AION Agent → Resource Agent → Operation Ask.
- Pick a Profile from the dropdown.
- Set Message (expression OK, e.g.
{{ $json.body }}). - 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/invokefrom 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_idin 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.
Related
- REST API — full chat/stream reference
- SDK and Web Widget — other external clients
- Profiles — authoring agent profiles