Warum Sie Ihren KI-Agenten per API mit Ihrer App verbinden

Was ist eine KI-Agent-API?

Mit einer KI-Agent-API schickt Ihre eigene Software eine Nachricht an einen Agenten, den Sie bereits gebaut haben, und bekommt seine Antwort zurück. Der Agent behält seine Anweisungen, sein Wissen, sein Modell, seine Tools und Sicherheitsregeln. Ihre App schickt nur die Frage.

Das ist der Unterschied zu einer reinen Modell-API. Eine Modell-API liefert Textgenerierung und überlässt Ihnen den Rest: Prompts, Dokumentsuche, Gedächtnis, Rate Limits, Abrechnung. Die REST-API von IMFA gibt Ihnen einen verwalteten Agenten, der all das schon hat, hinter einem agentenbezogenen Schlüssel.

Sie erstellen den Agenten mit dem KI-Chatbot-Builder. Die API ist ein weiterer Ort, an dem er antworten kann, neben Ihrer Website, WhatsApp, Instagram, Facebook, Telegram, Discord und der Sprachleitung.

Wann sollten Sie Ihren Agenten per API verbinden?

Greifen Sie zur API, wenn das Gespräch in etwas stattfindet, das Ihnen gehört:

• Ihre App oder Ihr Kundenportal braucht einen Hilfe-Assistenten, der Ihre Richtlinien kennt, ohne einen zweiten Chatbot zu pflegen.
• Ihr Backend soll Fragen aus einem anderen System beantworten, etwa aus Bestellseiten, einem Buchungstool oder einem internen Dashboard.
• Sie wollen Ihre Leads im CRM. Die API liefert die Leads, die der Agent auf jedem Kanal erfasst hat, sodass Sie sie regelmäßig synchronisieren können.
• Sie brauchen den Gesprächsverlauf für Reporting oder Qualitätsprüfung.

Wenn Sie nur eine Chat-Blase auf einer Website brauchen, ist die einzeilige Einbettung einfacher. Die API ist für den Fall, dass Ihr Produkt die Oberfläche ist, nicht das Widget.

Wie die IMFA-Agent-API funktioniert

Die Basis-URL ist https://site.imfa.app/v1. Jeder Aufruf braucht den Schlüssel des Agenten und muss aus vertrauenswürdigem Servercode kommen, nie aus einem Browser oder einem mobilen Bundle.

1. Veröffentlichen Sie den Agenten. Legen Sie in IMFA Anweisungen, Wissen, Modell und Tools fest, testen Sie echte Fragen und veröffentlichen Sie. Die API bedient die veröffentlichte Version.
2. Erzeugen Sie den Schlüssel. Öffnen Sie die API-Ansicht des Agenten oder den Bildschirm API Keys und erzeugen Sie einen Schlüssel. Er wird einmal angezeigt und nur als Hash gespeichert. Bewahren Sie ihn in einer Server-Umgebungsvariablen wie IMFA_API_KEY auf.
3. Senden Sie eine Chat-Anfrage. POST /v1/agents/{slug}/chat mit Authorization: Bearer <key>, einem eindeutigen Idempotency-Key (8 bis 128 Zeichen) und einem JSON-Body mit message und optional sessionId. Die Antwort kommt mit einer sessionId und usage.credits zurück.
4. Setzen Sie das Gespräch fort. Lassen Sie sessionId beim ersten Zug weg und senden Sie danach die zurück, die Sie erhalten haben. Der Agent erinnert sich an den Kontext.
5. Lesen Sie nach, was passiert ist. GET /v1/agents/{slug}/sessions listet Gespräche auf, GET /v1/agents/{slug}/sessions/{sessionId}/messages liest eines, und GET /v1/agents/{slug}/leads liefert erfasste Leads. Listen liefern standardmäßig 20 Einträge, bis zu 100, mit einem Cursor. GET /v1/agents bestätigt, welchen Agenten der Schlüssel bedient.

Die Grenzen sind klar: Die ersten 4.000 Zeichen einer Nachricht werden genutzt, Bodies sind auf 64.000 Bytes begrenzt, und Fehler sind typisiert (Validierung, Authentifizierung, Credits, Rate Limit, Server). Ein 429 kommt mit Retry-After, ein 402 bedeutet, dass die Credits des Inhabers aufgebraucht sind.

Warum die Agent-API statt einer Eigenentwicklung

Sie sparen Monate an Infrastruktur. Dokumentsuche, Sitzungen, Rate Limits, Wiederholungen, Credit-Abrechnung und Regeln gegen Prompt Injection laufen bereits. Ihr Team schreibt einen HTTP-Aufruf.

Ein Agent, ein Verhalten. Die Antwort in Ihrer App ist dieselbe wie auf Ihrer Website und in WhatsApp, weil es derselbe Agent ist. Aktualisieren Sie ihn einmal in IMFA, und jede Oberfläche folgt.

Wiederholungen sind sicher. Durch den Idempotency-Key liefert eine Wiederholung nach einem Netzwerkfehler die ursprüngliche Antwort, statt einen zweiten Zug zu berechnen.

Leads leben nicht mehr in Silos. Holen Sie jeden erfassten Lead über einen Endpunkt, egal über welchen Kanal er kam.

Eine komplett eigene Lösung bleibt möglich. Wenn Sie jede Schicht selbst besitzen müssen, gibt Ihnen eine reine Modell-API diese Kontrolle, zum Preis, alles selbst zu bauen und zu betreiben. Coding-Agenten wie Codex und Claude Code können IMFA-Agenten auch über MCP verwalten, während Ihr Server mit dem REST-Schlüssel Kunden bedient.

Häufige Fragen zur KI-Agent-API

Kann ich die KI-Agent-API direkt aus einem Browser aufrufen?

Nein. Der Schlüssel verbraucht die Credits des Inhabers und muss auf einem vertrauenswürdigen Server bleiben. Die API öffnet keinen breiten Browserzugriff. Lassen Sie Ihren Browser einen eigenen geschützten Endpunkt aufrufen, der dann IMFA aufruft.

Wie authentifiziere ich eine Anfrage an die IMFA-Agent-API?

Erzeugen Sie in der API-Ansicht des Agenten oder im Bildschirm API Keys einen agentenbezogenen Schlüssel und senden Sie Authorization: Bearer YOUR_API_KEY aus Servercode. Ein MCP-Token ist ein anderer Zugang und funktioniert hier nicht.

Wie setze ich dasselbe API-Gespräch fort?

Lassen Sie sessionId bei der ersten Chat-Anfrage weg, speichern Sie die sessionId, die die API zurückgibt, und senden Sie sie mit der nächsten Nachricht. Sitzungs-IDs aus Website- oder Kanalgesprächen sind nur lesbar und können kein API-Gespräch fortsetzen.

Warum ist für den Chat ein Idempotency-Key nötig?

Er macht Wiederholungen sicher. Eine exakte Wiederholung mit demselben Schlüssel liefert dasselbe Ergebnis, statt einen neuen Zug zu erzeugen. Nutzen Sie für jede neue Nachricht einen neuen Schlüssel.

Nutzt die Agent-API mein Wissen und meine Tools?

Ja. Sie ruft den veröffentlichten Agenten mit seinen Anweisungen, seinem Modell, Wissen, Skills, Tools und Sicherheitsregeln auf. Die Antworten hängen weiterhin von der veröffentlichten Konfiguration, Ihren Credits und den aktuellen Servicegrenzen ab.

Was passiert bei einem Rate Limit oder ohne Credits?

Bei einem Rate Limit erhalten Sie einen 429 mit einem Retry-After-Header, und einen 402, wenn die Credits des Inhabers aufgebraucht sind. Behandeln Sie in Ihrer Integration jeden dokumentierten Statuscode.