Localmind Agent in n8n einbinden

Sie rufen einen bestehenden Localmind-Agenten aus einem n8n-Workflow auf und verarbeiten die Antwort in nachfolgenden Nodes. Der getestete Weg ist die generische HTTP Request Node, die den OpenAI-kompatiblen Endpoint POST /v1/chat/completions Ihrer Instanz aufruft. Welcher Agent antwortet, bestimmt das model-Feld im Request-Body: Es trägt die Agent-UUID aus GET /v1/models.

Was Sie brauchen

Einen persönlichen API-Key (sk-…), die Agent-UUID (aus GET /v1/models) und die Base-URL Ihrer Instanz: https://<deine-instanz>-api.localmind.ai/v1.

Wie der Aufruf läuft

HTTP POST mit Authorization: Bearer <key> und JSON-Body im OpenAI-Chat-Completions-Schema gegen /v1/chat/completions — model = Agent-UUID.

Voraussetzungen

Persönlicher API-Key. Sie erstellen den Schlüssel unter Benutzereinstellungen → API-Schlüssel — optional auf ausgewählte Spaces gescoped. Der Key bestimmt, welche Agenten Sie über die API sehen und aufrufen können. Details siehe Persönliche API-Schlüssel.
Agent-UUID. GET /v1/models listet alle Agenten, auf die Ihr Key Zugriff hat — das Feld id jedes Eintrags ist die UUID, die Sie im Request-Body als model einsetzen. Endpoint-Details siehe OpenAI-kompatibel.
Base-URL. Localmind-Deployments folgen einem festen Subdomain-Schema. Für API-Aufrufe verwenden Sie immer den -api-Host mit /v1-Prefix: https://<deine-instanz>-api.localmind.ai/v1.
Verwenden Sie nicht den -app-Host aus dem Browser:
- <deine-instanz>-app.localmind.ai — Web-UI (Browser, NICHT für API)
- <deine-instanz>-api.localmind.ai — API-Endpoint (richtig für n8n)
- <deine-instanz>-auth.localmind.ai — Keycloak (nicht für Agent-Aufrufe)
Wenn Sie eine URL aus dem Browser kopieren, steht dort -app. Ersetzen Sie -app durch -api, bevor Sie die URL in n8n einsetzen.

Konkretes Ableitungs-Beispiel:

https://<deine-instanz>-app.localmind.ai/orgs/<org_id>/spaces/<space_id>/agents/<agent_id>/chat

https://<deine-instanz>-api.localmind.ai/v1/chat/completions

Die Agent-UUID sehen Sie auch in der Browser-URL der Agent-Detailseite (im Pfad direkt nach /agents/). Sie gehört aber nicht in die API-URL, sondern in das model-Feld des Request-Bodys. Verbindlich ermitteln Sie die UUID über GET /v1/models.

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 Chat-Completions-Endpoint Ihrer Instanz ein: https://<deine-instanz>-api.localmind.ai/v1/chat/completions.

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. Tragen Sie in model die Agent-UUID 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": "<agent_uuid>",
  "messages": [
    { "role": "user", "content": "<USER_INPUT>" }
  ],
  "stream": false
}

model-Feld: trägt die Agent-UUID aus GET /v1/models — kein Modellname wie gpt-4. Welches Sprachmodell tatsächlich antwortet, ist am Agenten in Localmind hinterlegt. Eine unbekannte UUID beantwortet der Endpoint mit 404 {"detail":"Model '…' not found"}.
stream: false ist Pflicht. Die HTTP Request Node kann Server-Sent Events (SSE) nicht verarbeiten. Bei stream: true blockiert die Node bis zum Timeout — 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 }}.
Stateless: Der Endpoint hält keinen serverseitigen Conversation-State. Für mehrstufige Konversationen senden Sie die bisherige History bei jedem Aufruf vollständig im messages-Array mit.

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": "<agent_uuid>",
  "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": "<agent_uuid>",
  "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

404 „Model not found“ trotz korrekter URL

Das model-Feld enthält einen Modellnamen (z.B. gpt-4) oder eine falsche UUID. Localmind routet nicht über Modellnamen — der Wert muss eine Agent-UUID aus GET /v1/models sein. Prüfen Sie auch, ob Ihr API-Key Zugriff auf den Space des Agenten hat: Agenten außerhalb des Key-Scopes tauchen in GET /v1/models nicht auf und sind nicht aufrufbar.

API-Aufruf gibt 404 auf die URL zurück

Häufigste Ursache: Sie haben die URL aus dem Browser kopiert und dabei -app stehen lassen. Ersetzen Sie -app durch -api. Prüfen Sie außerdem, dass der Pfad exakt /v1/chat/completions lautet (mit /v1-Prefix).

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- oder messages-Feld fehlt im Request-Body oder ist falsch formatiert. Übernehmen Sie das Body-Snippet aus diesem Artikel und tragen Sie in model die Agent-UUID ein.

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	Host `-app` statt `-api`, `/v1`-Prefix fehlt oder unbekannte Agent-UUID im `model`-Feld („Model not found“)	Base-URL prüfen; UUID gegen `GET /v1/models` abgleichen
422	Body-Schema verletzt (`model` oder `messages` fehlt)	Body-Snippet aus diesem Artikel übernehmen

Weiterführend

Persönliche API-Schlüssel — API-Key erstellen und verwalten
OpenAI-kompatibel — Referenz zu GET /v1/models und POST /v1/chat/completions
Use-Cases — weitere API-Rezepte, u.a. n8n-Automatisierung und Chatbots
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

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