> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localmind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Localmind Agent in n8n einbinden

> Localmind-Agenten via HTTP Request Node aus n8n-Workflows aufrufen — OpenAI-kompatibler Chat-Completions-Endpoint mit Bearer-Auth.

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.

<CardGroup cols={2}>
  <Card title="Was Sie brauchen" icon="key">
    Einen Localmind-API-Schlüssel, die Agent-ID (UUID) und den korrekten API-Host Ihres Deployments.
  </Card>

  <Card title="Wie der Aufruf läuft" icon="bolt">
    HTTP POST mit `Authorization: Bearer <key>` und JSON-Body im OpenAI-Chat-Completions-Schema gegen `/v1/agents/<agent_id>/chat/completions`.
  </Card>
</CardGroup>

## Voraussetzungen

* **Localmind-API-Schlüssel.** Sie erzeugen den Schlüssel in den Space-Einstellungen im Bereich „API-Schlüssel". Details siehe [Space-Einstellungen](/navigation/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.

  <Warning>
    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.
  </Warning>

**Konkretes Ableitungs-Beispiel:**

<CodeGroup>
  ```text Browser (UI) theme={null}
  https://<deployment>-app.<domain>/orgs/<org_id>/spaces/<space_id>/agents/<agent_id>/chat
  ```

  ```text API-Endpoint theme={null}
  https://<deployment>-api.<domain>/v1/agents/<agent_id>/chat/completions
  ```
</CodeGroup>

## HTTP Request Node konfigurieren

<Steps>
  <Step title="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.
  </Step>

  <Step title="Authentication als Header Auth anlegen">
    1. Setzen Sie **Authentication** auf `Generic Credential Type`.
    2. Wählen Sie darunter `Header Auth`.
    3. Legen Sie eine neue Credential vom Typ **Header Auth** an mit:
       * **Name:** `Authorization`
       * **Value:** `Bearer <LOCALMIND_API_KEY>`

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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](#request-body) ein. n8n setzt den `Content-Type: application/json`-Header in der Regel automatisch.
  </Step>

  <Step title="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.

    <Check>
      Statuscode 200 und im Output-JSON ein `choices`-Array mit mindestens einem Eintrag — dann ist die Konfiguration korrekt.
    </Check>
  </Step>
</Steps>

## Request-Body

<CodeGroup>
  ```json Body (n8n) theme={null}
  {
    "model": "<beliebig>",
    "messages": [
      { "role": "user", "content": "<USER_INPUT>" }
    ],
    "stream": false
  }
  ```
</CodeGroup>

<Note>
  * **`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 }}`.
</Note>

## Response-Format

<CodeGroup>
  ```json Response (200 OK) theme={null}
  {
    "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
    }
  }
  ```
</CodeGroup>

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.

<Tabs>
  <Tab title="Single-Turn">
    Ein einzelner User-Turn — die Nachricht kommt per Expression aus dem Trigger-Input:

    <CodeGroup>
      ```json Body theme={null}
      {
        "model": "localmind",
        "messages": [
          { "role": "user", "content": "{{ $json.userMessage }}" }
        ],
        "stream": false
      }
      ```
    </CodeGroup>

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

  <Tab title="Multi-Turn mit Konversations-History">
    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.

    <CodeGroup>
      ```json Body mit History theme={null}
      {
        "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
      }
      ```
    </CodeGroup>

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

## Stolperfallen

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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/`).
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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"`.
  </Accordion>
</AccordionGroup>

## 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](/navigation/Space-Einstellungen) — API-Schlüssel erzeugen und verwalten
* [API-Key funktioniert nicht](/troubleshooting/API-Key-Funktioniert-Nicht) — Troubleshooting bei Auth-Problemen
* [Security in Automate](/automate/security) — Credentials in n8n sicher verwalten
* [Debugging in Automate](/automate/debugging) — allgemeine Workflow-Fehlersuche