Localmind Agent in n8n einbinden

Sie rufen einen bestehenden Localmind-Agenten aus einem n8n-Workflow auf und verarbeiten die Antwort in nachfolgenden Nodes. Die naheliegende OpenAI Chat Model-Node erwartet einen /v1/models-Discovery-Endpoint, den der agent-spezifische Localmind-Pfad nicht bereitstellt — der Connection-Test schlägt deshalb fehl. Der getestete Weg ist die generische HTTP Request Node, die direkt den OpenAI-kompatiblen Chat-Completions-Endpoint des Agenten aufruft.

Was Sie brauchen

Einen Localmind-API-Schlüssel, die Agent-ID (UUID) und den korrekten API-Host Ihres Deployments.

Wie der Aufruf läuft

HTTP POST mit Authorization: Bearer <key> und JSON-Body im OpenAI-Chat-Completions-Schema gegen /v1/agents/<agent_id>/chat/completions.

Voraussetzungen

Localmind-API-Schlüssel. Sie erzeugen den Schlüssel in den Space-Einstellungen im Bereich „API-Schlüssel”. Details siehe Space-Einstellungen.
Agent-ID. Die UUID des Agenten ist in der Browser-URL der Agent-Detailseite sichtbar — im Pfad direkt nach /agents/.
API-Host. Localmind-Deployments folgen einem festen Subdomain-Schema. Für API-Aufrufe verwenden Sie immer den -api-Host.
Verwenden Sie nicht den -app-Host aus dem Browser:
- <deployment>-app.<domain> — Web-UI (Browser, NICHT für API)
- <deployment>-api.<domain> — API-Endpoint (richtig für n8n)
- <deployment>-auth.<domain> — Keycloak (nicht für Agent-Aufrufe)
Wenn Sie die Agent-URL aus dem Browser kopieren, steht dort -app. Ersetzen Sie -app durch -api, bevor Sie die URL in n8n einsetzen.

Konkretes Ableitungs-Beispiel:

https://<deployment>-app.<domain>/orgs/<org_id>/spaces/<space_id>/agents/<agent_id>/chat

HTTP Request Node konfigurieren

HTTP Request Node einfügen

Platzieren Sie in Ihrem n8n-Workflow eine neue HTTP Request Node. Setzen Sie die Method auf POST und tragen Sie als URL den abgeleiteten API-Endpoint aus dem Beispiel oben ein — mit dem -api-Host und der korrekten Agent-UUID.

Authentication als Header Auth anlegen

Setzen Sie Authentication auf Generic Credential Type.
Wählen Sie darunter Header Auth.
Legen Sie eine neue Credential vom Typ Header Auth an mit:
- Name: Authorization
- Value: Bearer <LOCALMIND_API_KEY>

Legen Sie API-Schlüssel NIE direkt im Workflow-JSON ab — immer als n8n-Credential. So werden sie verschlüsselt gespeichert und in geteilten Workflows nicht sichtbar.

Request-Body konfigurieren

Aktivieren Sie Send Body, wählen Sie als Body Content Type JSON und fügen Sie das Body-Snippet aus dem Abschnitt Request-Body ein. n8n setzt den Content-Type: application/json-Header in der Regel automatisch.

Test-Lauf ausführen

Klicken Sie auf Execute Node und warten Sie auf den grünen Status. Im Output sehen Sie das Feld choices[0].message.content mit der Agent-Antwort.

Statuscode 200 und im Output-JSON ein choices-Array mit mindestens einem Eintrag — dann ist die Konfiguration korrekt.

Request-Body

{
  "model": "<beliebig>",
  "messages": [
    { "role": "user", "content": "<USER_INPUT>" }
  ],
  "stream": false
}

model-Feld: Wird vom Endpoint ignoriert — der Agent nutzt das in Localmind konfigurierte Modell. Das Feld muss laut Schema aber vorhanden sein, sonst gibt der Endpoint einen Validation-Error (422) zurück. Ein beliebiger String genügt.
stream: false ist Pflicht. Die HTTP Request Node kann Server-Sent Events (SSE) nicht verarbeiten. Bei stream: true blockiert die Node bis zum Timeout. Die OpenAPI-Spec erlaubt zwar stream: true, aber nicht in dieser Node — wer Streaming braucht, muss die Antwort per Code-Node selbst parsen.
messages folgt dem OpenAI-Standard-Format: eine Liste von {role, content}-Objekten mit role aus "user", "assistant" oder "system". <USER_INPUT> ist in n8n typischerweise eine Expression wie {{ $json.userMessage }}.

Response-Format

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "agent-model",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Antwort des Agenten"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

In Folge-Nodes greifen Sie auf die relevanten Felder per Expression zu:

Antwort-Text: {{ $json.choices[0].message.content }}
Token-Verbrauch für Logging oder Limits: {{ $json.usage.total_tokens }}
Das model-Feld in der Response zeigt das tatsächlich vom Agent verwendete Modell, nicht den Wert aus Ihrem Request.

Beispiel-Workflow

Ein typischer 3-Node-Workflow sieht so aus:

Trigger (Webhook oder Manual) → HTTP Request Node (Localmind Agent) → Set/Code-Node (Antwort extrahieren)

Der nachgelagerte Set- oder Code-Node liest choices[0].message.content aus und stellt es als sauberes Feld für weitere Schritte bereit.

Single-Turn
Multi-Turn mit Konversations-History

Ein einzelner User-Turn — die Nachricht kommt per Expression aus dem Trigger-Input:

{
  "model": "localmind",
  "messages": [
    { "role": "user", "content": "{{ $json.userMessage }}" }
  ],
  "stream": false
}

Im Trigger erwartet der Workflow ein Feld userMessage — beispielsweise aus einem Webhook-Payload oder einem manuellen Test-Input.

Für mehrstufige Konversationen schicken Sie die bisherige History im messages-Array mit. n8n hat keinen automatischen Session-State — Sie müssen die History entweder im Trigger-Input mitliefern oder via Static Data Node persistieren.

{
  "model": "localmind",
  "messages": [
    { "role": "system", "content": "Du bist ein hilfreicher Assistent." },
    { "role": "user", "content": "Wie hoch ist der Eiffelturm?" },
    { "role": "assistant", "content": "Der Eiffelturm ist 330 Meter hoch." },
    { "role": "user", "content": "Und wann wurde er gebaut?" }
  ],
  "stream": false
}

Jeder neue User-Turn hängt einen weiteren { "role": "user", ... }-Eintrag ans Ende, die letzte Assistant-Antwort wandert als { "role": "assistant", ... } davor.

Stolperfallen

Connection-Test der „OpenAI Chat Model“-Node schlägt fehl

Die OpenAI Chat Model-Node führt beim Konfigurieren einen Discovery-Call gegen /v1/models aus, um verfügbare Modelle aufzulisten. Dieser Endpoint existiert unter dem agent-spezifischen Localmind-Pfad nicht — deshalb meldet die Node „Couldn’t connect” oder einen 404. Verwenden Sie stattdessen die generische HTTP Request Node wie in dieser Anleitung beschrieben.

API-Aufruf gibt 404 zurück

Häufigste Ursache: Sie haben die URL aus dem Browser kopiert und dabei <deployment>-app.<domain> stehen lassen. Ersetzen Sie -app durch -api. Zweithäufigste Ursache: falsche Agent-ID — prüfen Sie die UUID gegen die Browser-URL der Agent-Detailseite (Pfad nach /agents/).

Workflow hängt nach dem Request

stream ist versehentlich auf true gesetzt. Die HTTP Request Node erwartet eine einzelne JSON-Response und hängt bei Server-Sent Events bis zum Timeout. Setzen Sie stream explizit auf false.

422 Validation Error

Das model-Feld fehlt im Request-Body. Auch wenn der Wert vom Agent ignoriert wird, validiert das Schema gegen seine Anwesenheit. Tragen Sie irgendeinen String ein, z.B. "localmind".

Fehlerbilder

Status	Ursache	Fix
401	Ungültiger oder fehlender API-Schlüssel	Credential in n8n prüfen, `Bearer` -Präfix vor dem Schlüssel nicht vergessen
404	Agent-ID falsch oder Host `-app` statt `-api`	UUID aus Browser-URL kopieren, Host-Konvention prüfen
422	Body-Schema verletzt (`model` oder `messages` fehlt)	Body-Snippet aus diesem Artikel übernehmen

Weiterführend

Space-Einstellungen — API-Schlüssel erzeugen und verwalten
API-Key funktioniert nicht — Troubleshooting bei Auth-Problemen
Security in Automate — Credentials in n8n sicher verwalten
Debugging in Automate — allgemeine Workflow-Fehlersuche

Grundlagen

Localmind anbinden

Workflows

Erweitert

Betrieb

Localmind Agent in n8n einbinden

Was Sie brauchen

Wie der Aufruf läuft

Voraussetzungen

HTTP Request Node konfigurieren

Request-Body

Response-Format

Beispiel-Workflow

Stolperfallen

Fehlerbilder

Weiterführend

Grundlagen

Localmind anbinden

Workflows

Erweitert

Betrieb

Documentation Index

Was Sie brauchen

Wie der Aufruf läuft

​Voraussetzungen

​HTTP Request Node konfigurieren

​Request-Body

​Response-Format

​Beispiel-Workflow

​Stolperfallen

​Fehlerbilder

​Weiterführend

Voraussetzungen

HTTP Request Node konfigurieren

Request-Body

Response-Format

Beispiel-Workflow

Stolperfallen

Fehlerbilder

Weiterführend