HTTP API (Generisch)

Mit dem Tool HTTP API (Generisch) kann ein Assistent externe HTTP-APIs direkt aufrufen.

Das Tool ist für kontrollierte API-Integrationen gedacht, wenn es keinen spezifischen Connector gibt.

Methoden

Das Tool hat drei Methoden mit unterschiedlichem Risikolevel:

• generic_http_request_read (read)
• generic_http_request_write (write)
• generic_http_request_dangerous (dangerous)

Diese Klassifizierung steuert die Method Permissions im Assistant und in den Admin-Einstellungen.

Konfiguration im Assistant

Verbindung

• baseUrl: Basis-URL der API (z. B. https://api.example.com)
• authMode: none | bearer | apiKey | basic
• authHeaderName: Header-Name für Auth (Standard: Authorization)
• authSecret: Secret für Auth (verschlüsselt gespeichert)

Scope & Sicherheit

• allowedMethods: erlaubte HTTP-Methoden (z. B. nur GET, POST)
• allowedHostPatterns: erlaubte Hosts (z. B. api.example.com, *.example.com)
• allowedPathPrefixes: erlaubte Pfadpräfixe (z. B. /v1, /api)
• blockedPathPrefixes: explizit gesperrte Pfadpräfixe (z. B. /admin)

Request-Steuerung

• defaultHeaders (JSON): statische Header, die immer mitgeschickt werden
• requestTemplates (JSON): vordefinierte Request-Templates
• timeoutMs: Request-Timeout
• maxResponseBytes: harte Größenbegrenzung der Response
• maxResponseChars: maximale Zeichenlänge, die ans Modell zurückgegeben wird

Request-Templates

Templates helfen, wiederkehrende Requests sauber und sicher zu strukturieren.

Beispiel:

[
  {
    "name": "listUsers",
    "method": "GET",
    "path": "/v1/users"
  },
  {
    "name": "createTicket",
    "method": "POST",
    "path": "/v1/tickets",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "title": "Example"
    }
  }
]

Ein Tool-Call kann dann templateName setzen und optional Werte überschreiben (query, headers, bodyJson).

Sicherheitsverhalten

Das Tool erzwingt folgende Schutzmechanismen:

• Nur http/https URLs
• Blockiert private/interne Hosts (z. B. localhost, private IP-Ranges)
• Erzwingt Host-Allowlist und Path-Policies aus den Settings
• Erzwingt erlaubte Methoden aus allowedMethods
• Begrenzt Response-Größe und Response-Länge

Typischer Einsatz

1. API-Zugriff mit baseUrl + Auth konfigurieren
2. Host/Path-Scopes setzen
3. Wichtige Endpoints als requestTemplates hinterlegen
4. Methodenrechte im Assistant auf read/write/dangerous begrenzen

Hinweise

• Für produktive Setups sollten allowedHostPatterns und allowedPathPrefixes immer gesetzt werden.
• Nutze Templates für kritische Endpoints, statt freie Requests zu erlauben.
• Derzeit gibt es keinen eigenen Connection-Test-Button für dieses Tool.