KI-Compliance-Agent in 30 Minuten bauen: KYC mit der handelsregister.ai API

KI-Compliance-Agent in 30 Minuten bauen: KYC mit der handelsregister.ai API

8 Min. Lesezeit

Schritt-für-Schritt: KI-Agent für KYC und Lieferanten-Screening mit handelsregister.ai als Tool – Setup, System Prompt, Agent-Loop, Audit-Trail.

Statt einen Workflow zu designen, gibst du dem Agenten ein Ziel. „Prüfe diese GmbH auf Compliance-Risiken" – und der Agent entscheidet selbst, welche Daten er holt, in welcher Reihenfolge, und wann er genug weiß. Genau dieses Muster löst gerade die starren n8n-Pipelines im KYC-Bereich ab. Die gute Nachricht: Du brauchst dafür keinen Spezialstack, kein MCP, keine Vector-DB. Ein LLM mit Tool Calling, drei Endpoints der handelsregister.ai API und ungefähr 100 Zeilen Python reichen für einen funktionsfähigen ersten Compliance-Agenten. In diesem Artikel zeige ich dir den kompletten Aufbau – inklusive System Prompt, Agent-Loop, Demo-Run und den Härtungsschritten, die du brauchst, bevor das Ding produktiv läuft.

Workflow vs. KI-Agent: der entscheidende Unterschied

Ein klassischer Workflow (etwa in n8n) besteht aus festen Schritten: Trigger → API-Call → Mapping → Entscheidung → Speichern. Du als Entwickler:in legst die Reihenfolge fest und behandelst alle Verzweigungen explizit.

Ein KI-Agent dreht das um. Du beschreibst ein Ziel und stellst dem LLM eine Reihe von Tools (Funktionen) zur Verfügung. Das LLM entscheidet bei jedem Schritt selbst: rufe ich jetzt Tool A oder Tool B auf, oder habe ich schon genug Information, um zu antworten? Statt einer fest verdrahteten Logik bekommst du eine iterative Reasoning-Schleife.

Für Compliance ist das genial – und gefährlich. Genial, weil viele Cases nicht in eine starre Pipeline passen: Manchmal reicht ein UBO-Lookup, manchmal brauchst du Personenprofile mehrerer Geschäftsführer, manchmal musst du in einer zweiten Eigentümerebene weiterfragen. Gefährlich, weil ein Agent ohne Leitplanken halluzinieren oder unnötig viele Calls verbrennen kann. Der Trick liegt im sauberen Tool-Design und einem präzisen System Prompt.

Architektur: LLM + drei Tools + REST API

Du brauchst drei Bausteine:

  • Ein LLM mit Tool Calling. OpenAI (gpt-4.1, gpt-5), Anthropic (Claude Sonnet, Claude Opus) oder lokal via Ollama – alle modernen Modelle unterstützen das Schema. Beispiele unten in Python mit dem OpenAI SDK; Anthropic funktioniert analog.
  • Drei Tools, die handelsregister.ai-Endpoints kapseln.
    • search_organization → GET /api/v1/search-organizations (Firmensuche, Filter)
    • fetch_organization → GET /api/v1/fetch-organization mit feature=ubos und feature=related_persons
    • fetch_person → GET /api/v1/fetch-person (KI-angereichertes Personenprofil)
  • Eine simple Schleife, die das LLM aufruft, Tool-Calls ausführt, Ergebnisse zurückspielt – bis das LLM keine Tools mehr aufruft, sondern eine finale Antwort liefert.

Der Agent läuft also wie ein Praktikant mit drei klaren Befugnissen: Firmen suchen, Firmenprofil mit Eigentümern abrufen, Person prüfen. Nicht mehr, nicht weniger.

Setup in fünf Minuten

pip install openai httpx pydantic
export OPENAI_API_KEY="sk-..."
export HANDELSREGISTER_API_KEY="hr_..."

Den handelsregister.ai-Key bekommst du im Dashboard. Im Header heißt er x-api-key. Mehr Konfiguration brauchst du für den ersten Run nicht.

Tool-Definitionen: drei Funktionen, drei JSON-Schemas

Tools werden dem LLM als JSON-Schema beschrieben. Das LLM bekommt damit Name, Zweck und Parameter – mehr nicht. Die eigentliche HTTP-Logik schreibst du daneben in Python:

import os, httpx

HR_KEY = os.environ["HANDELSREGISTER_API_KEY"]
BASE = "https://handelsregister.ai/api/v1"
HEAD = {"x-api-key": HR_KEY}

def search_organization(q: str, postal_code: str | None = None) -> dict:
    params = {"q": q, "limit": 5}
    if postal_code:
        params["filters"] = f'{{"postal_code":"{postal_code}"}}'
    return httpx.get(f"{BASE}/search-organizations", params=params, headers=HEAD).json()

def fetch_organization(q: str) -> dict:
    params = {"q": q, "feature": ["ubos", "related_persons"], "ai_search": "on-default"}
    return httpx.get(f"{BASE}/fetch-organization", params=params, headers=HEAD).json()

def fetch_person(person_q: str, organization_q: str) -> dict:
    params = {"person_q": person_q, "organization_q": organization_q}
    return httpx.get(f"{BASE}/fetch-person", params=params, headers=HEAD).json()

Die Tool-Schemas für das LLM sehen so aus (gekürzt – nur fetch_organization):

TOOLS = [{
  "type": "function",
  "function": {
    "name": "fetch_organization",
    "description": "Vollständiges Firmenprofil inkl. UBOs und aktueller Geschäftsführung.",
    "parameters": {
      "type": "object",
      "properties": {"q": {"type": "string", "description": "Firmenname oder HR-Nummer."}},
      "required": ["q"]
    }
  }
}]  # plus search_organization und fetch_person analog

Wichtig: Beschreibe in description wann das Tool genutzt werden soll, nicht nur was es tut. Das LLM trifft seine Wahl primär anhand dieser Texte. Der UBO-Aspekt gehört da rein – siehe auch unsere UBO-Anleitung für die Schwellen-Logik.

System Prompt + Agent-Loop

Der System Prompt ist der Charakter deines Agenten. Halte ihn kurz, präzise und mit klarem Output-Schema:

SYSTEM = """Du bist ein KYC-Compliance-Agent für deutsche Unternehmen.
Aufgabe: Nutze die Tools, um eine GmbH zu prüfen, und liefere am Ende ein JSON
mit den Feldern: company, ubos (>=25%), management, risk_flags, coverage, verdict.
Regeln:
- Beginne immer mit fetch_organization. Greife auf search_organization nur zurück,
  wenn der Firmenname mehrdeutig ist.
- Wenn coverage < 80%, setze risk_flags += ["low_coverage"].
- Prüfe genau einen UBO mit fetch_person bei auffälligen Hinweisen
  (z.B. mehrere Affiliations, Auslandskontext).
- Antworte ausschließlich mit dem finalen JSON, ohne Fließtext."""

Der Agent-Loop ist 30 Zeilen Python. Pseudocode:

from openai import OpenAI
client = OpenAI()
messages = [{"role":"system","content":SYSTEM},
            {"role":"user","content":"Prüfe: Beispiel Holding GmbH"}]

while True:
    resp = client.chat.completions.create(
        model="gpt-5.5", messages=messages, tools=TOOLS)
    msg = resp.choices[0].message
    messages.append(msg)
    if not msg.tool_calls:
        print(msg.content); break
    for call in msg.tool_calls:
        result = dispatch(call.function.name, call.function.arguments)
        messages.append({"role":"tool","tool_call_id":call.id,"content":str(result)})

dispatch ist eine Mini-Routing-Funktion, die den Tool-Namen auf die passende Python-Funktion abbildet. Das war's strukturell. Anthropic-Nutzer ersetzen den Client und die Message-Struktur – die Logik bleibt identisch.

Demo-Run: was der Agent tatsächlich tut

Eingabe: „Prüfe: Beispielwerk Analytics GmbH aus München". Ein typischer Trace sieht so aus:

  1. Tool: fetch_organization mit q="Beispielwerk Analytics GmbH München". Antwort: Firma gefunden, zwei aufgelöste UBOs (eine Person 60 %, eine Holding mit nicht aufgelöstem Anteil 40 %), zwei Geschäftsführer:innen, Coverage 60 %.
  2. Reasoning des LLM: „Coverage unter 80 %, also low_coverage flag. Die 60 %-Person ist ein klarer UBO – kein zusätzlicher Personen-Lookup nötig. Die nicht aufgelöste Holding ist Eskalations-Trigger, kein automatisches Profiling."
  3. Tool-Call entfällt, der Agent geht direkt zur Ausgabe.
  4. Final-Output (JSON):
{
  "company": {"name": "Beispielwerk Analytics GmbH", "register": "HRB 254891 München"},
  "ubos": [{"name": "Max Mustermann", "share": 60, "source": "shareholders_list"}],
  "management": ["Max Mustermann", "Erika Beispiel"],
  "risk_flags": ["low_coverage", "unresolved_holding_40_percent"],
  "coverage": 0.6,
  "verdict": "needs_enhanced_due_diligence"
}

Das ist der Wert: nicht nur Rohdaten, sondern eine strukturierte Bewertung mit Begründung – und für jeden Schritt einen vollständigen Trace, den du archivieren kannst.

Vom Prototyp zur Produktion: fünf Härtungs-Themen

Ein lauffähiger Agent ist nicht automatisch ein produktionsreifer. Bevor du den auf echte Onboarding-Cases loslässt, brauchst du:

  • Audit-Trail. Jeder Tool-Call (Eingabe + Ergebnis), jede LLM-Nachricht und der finale Verdikt gehören mit Zeitstempel und Run-ID in eine Tabelle. Das ist nicht „nice to have" – das ist GwG-Pflicht.
  • Idempotenz und Caching. Ein Agent, der bei der zweiten Anfrage zur selben Firma erneut alle Tools feuert, verbrennt unnötig Credits. Hash-Cache auf der Eingabe (Firmenname + Datum) und ein TTL von z. B. 24h reichen für die meisten Workflows.
  • Rate Limits + Retries. Die handelsregister.ai API erlaubt 60 Calls/min (bzw. 5/min auf Dokument-Endpoints). Pack einen exponentiellen Backoff auf 429-Antworten und limitiere maximale Tool-Calls pro Run (z. B. 8) – sonst läuft der Agent in Loops.
  • Cost Control. Setze ein Hard-Limit auf Tokens und Tool-Calls pro Run, sonst explodiert die Rechnung bei einem Edge Case. Empfehlung: max. 8 Tool-Calls und 4.000 Output-Tokens. Mehr ist fast immer ein Bug.
  • Halluzinations-Schutz. Ein LLM kann Felder „erfinden", die in der API-Antwort nicht stehen. Validiere den finalen JSON gegen ein striktes Pydantic-Schema. Fehlt ein Feld oder taucht ein erfundener Wert auf, lehne den Run ab und logge ihn als Trainings-Case.

Wenn du diese fünf Themen sauber abhakst, bist du kein Prototyp-Bastler mehr, sondern hast ein Compliance-Tool, das Audits aushält.

Bonus: Multi-Agent statt Mono-Agent

Sobald die Aufgaben komplexer werden (z. B. „prüfe diese 50 Firmen pro Tag"), lohnt sich ein Researcher-Reviewer-Pattern: Ein Agent recherchiert (darf alle Tools nutzen), ein zweiter prüft den ersten Output gegen das JSON-Schema und gibt entweder grünes Licht oder schickt zurück. Das doppelt zwar die Token-Kosten, halbiert aber Halluzinations-Raten in der Praxis – und ist immer noch deutlich günstiger als ein Mensch.

Recap

Mit drei API-Tools, einem präzisen System Prompt und ungefähr 100 Zeilen Python hast du in einem Nachmittag einen funktionierenden KI-Compliance-Agenten. Die handelsregister.ai API ist dafür gut geeignet, weil ihre Antworten bereits strukturiert sind – das LLM muss nicht parsen, sondern nur entscheiden. Das nächste Level (Caching, Multi-Agent, RAG-Pipeline) baust du oben drauf, ohne den Kern umzuwerfen.

Wenn du tiefer in die KYC-Mechanik einsteigen willst: Die UBO-Schwelle und Eigentümerketten erklären wir an anderer Stelle ausführlich, und der Vergleich von Visual-Workflows (n8n + handelsregister.ai) hilft dir bei der Frage, welcher Ansatz wann der richtige ist.