Verbinden Sie einen verwalteten KI-Agenten mit Ihrer App

Was ist eine KI-Agent-API?

Eine KI-Agent-API lässt eine vertrauenswürdige Anwendung mit einem Agenten kommunizieren, der bereits Anweisungen, Wissen, Modelleinstellungen, Tools und Gesprächsverhalten besitzt. Die IMFA REST API listet den verfügbaren Agenten, sendet Chat-Nachrichten, führt API-Sitzungen fort, liest gespeicherte Nachrichten und ruft Leads ab.

Sie ist die Schnittstelle zu einem verwalteten Agenten und kein direkter Modell-Endpunkt. Sie konfigurieren und veröffentlichen den Agenten in IMFA, danach ruft Ihr Server ihn mit einem agentenbezogenen Schlüssel auf. Dasselbe RAG-Wissen und Verhalten kann App, Web, WhatsApp, Telegram, Discord und geeignete Voice-Oberflächen bedienen.

Ein Produktionsvertrag für vertrauenswürdige Server

Die API bietet eine enge, dokumentierte REST-Oberfläche um den veröffentlichten Agenten, während IMFA Wissen, Verhalten, Modelle, Sitzungen, Credits und Schutzgrenzen verwaltet.

Authentifizierung pro Agent

Erzeugen Sie den REST-Schlüssel manuell in der API-Ansicht des Agenten oder im API-Keys-Bereich. Senden Sie Authorization: Bearer YOUR_API_KEY. Der Schlüssel wird einmal angezeigt, nur als Hash gespeichert und unterscheidet sich vom MCP-Token des Kontos.

Idempotente Chat-Anfragen

POST /v1/agents/{slug}/chat verlangt einen Idempotency-Key mit 8 bis 128 erlaubten Zeichen. Nutzen Sie für jede neue Gesprächsrunde einen neuen Wert und wiederholen Sie ihn nur für exakt dieselbe Anfrage.

Wiederverwendbarer API-Kontext

Lassen Sie sessionId für ein neues API-Gespräch weg, speichern Sie den zurückgegebenen Wert und verwenden Sie ihn später erneut. Sitzungs-IDs aus Website, Builder und Kanälen im Verlauf sind schreibgeschützt.

Sitzungen, Nachrichten und Leads

Listen Sie gespeicherte Sitzungen auf, lesen Sie Nachrichten einer Sitzung und rufen Sie Leads ab. Paginierte GET-Routen liefern standardmäßig 20 Einträge und akzeptieren ein Limit von 1 bis 100 sowie einen optionalen Cursor.

Klare Grenzen und Statuscodes

Chat verlangt message, nutzt die ersten 4.000 Zeichen, erlaubt eine sessionId bis 128 Zeichen und begrenzt den Body auf 64.000 Bytes. Statuscodes unterscheiden Validierung, Schlüssel, Credits, Verfügbarkeit, Pause, Größe, Rate Limit und Serverfehler.

Dasselbe verwaltete Agentensystem

Antworten nutzen Anweisungen, Modell, RAG-Wissen, Skills, Tools und Schutzgrenzen des veröffentlichten Agenten. Anfragen verbrauchen Credits des Eigentümers und erfolgreiche Antworten können usage.credits enthalten.

So rufen Sie einen IMFA-Agenten vom Server auf

Veröffentlichen Sie zuerst den Agenten, schützen Sie den Schlüssel in einer Servervariable und entwerfen Sie Wiederholungen mit korrekter Idempotenz und Sitzungskontinuität.

1. Verwalteten Agenten erstellen und veröffentlichen

   Definieren Sie Anweisungen, RAG-Wissen, Modell, Skills, Tools und Schutzregeln in IMFA. Testen Sie realistische Fragen und veröffentlichen Sie bewusst, bevor Sie den REST-Endpunkt nutzen.

2. Begrenzten Schlüssel erzeugen und schützen

   Öffnen Sie die API-Ansicht oder https://www.imfa.app/app/api-keys, erzeugen Sie den Schlüssel manuell und speichern Sie ihn in einer Servervariable wie IMFA_API_KEY. Legen Sie ihn nie in Browsercode, mobilen Bundles, öffentlichen Repositories, Logs oder Nachrichten ab.

3. Idempotente Serveranfrage senden

   Rufen Sie fetch('https://site.imfa.app/v1/agents/{slug}/chat') per POST mit Authorization: Bearer plus Serverschlüssel, Content-Type: application/json, eindeutigem Idempotency-Key und JSON mit message sowie optionaler sessionId auf. Speichern Sie reply, sessionId und usage.credits.

IMFA Agent API, rohe Modell-API oder Eigenentwicklung

Die Wahl hängt davon ab, welche Schicht Ihr Team besitzen will. IMFA stellt einen verwalteten Kundenagenten bereit, eine Modell-API dagegen niedrigere Generierungsbausteine.

Eine Modell-API bietet maximale Kontrolle

Wählen Sie einen Anbieter direkt, wenn Sie Prompts, RAG-Aufnahme und Retrieval, Sitzungen, Tool-Richtlinien, Authentifizierung, Limits, Kanäle, Observability, Abrechnung, Deployment, Sicherheit und Wartung selbst betreiben möchten.

Coding-Agenten bauen individuelle Software

Codex und Claude Code können Anwendungen und Integrationen erstellen. Über MCP können sie auch IMFA verwalten, während der Produktionsserver den separaten REST-Schlüssel des Agenten für Kundenanfragen nutzt.

IMFA verwaltet den Agentenlebenszyklus

Wählen Sie IMFA, wenn Ihre App einen Agenten aufrufen soll, dessen Wissen, Regeln, Kanäle, Sitzungen, Leads, Modelle, Schutz, Veröffentlichung und Nutzung in einer Oberfläche verwaltet werden.

Fünf REST-Endpunkte für einen veröffentlichten Agenten

Die Basis-URL lautet https://site.imfa.app/v1. Jede Anfrage braucht den agentenbezogenen Bearer-Schlüssel und Chat muss aus vertrauenswürdiger Serverinfrastruktur kommen.

Verfügbaren Agenten auflisten

GET /v1/agents liefert den für den Schlüssel verfügbaren Agenten und bestätigt das veröffentlichte Integrationsziel.

Mit dem Agenten chatten

POST /v1/agents/{slug}/chat sendet eine Nachricht und liefert reply, eine wiederverwendbare sessionId, usage.credits und gegebenenfalls Replay-Informationen.

Gespräche lesen

GET /v1/agents/{slug}/sessions listet Gespräche und GET /v1/agents/{slug}/sessions/{sessionId}/messages liest die Nachrichten einer Sitzung.

Erfasste Leads abrufen

GET /v1/agents/{slug}/leads liefert erfasste Leads mit demselben Cursor-basierten Paginierungsvertrag.

Häufige Fragen zur KI-Agent-API

Genaue Antworten zu Authentifizierung, Servereinsatz, Idempotenz, Sitzungen, RAG, Credits und Rate Limits.

Kann ich die Agent API direkt im Browser aufrufen?

Nein. Der REST-Schlüssel verbraucht Credits des Eigentümers und muss in einer vertrauenswürdigen Serverumgebung bleiben. Die API ist nicht für direkten Browserzugriff gedacht und bietet kein breites öffentliches CORS. Der Browser sollte Ihren eigenen geschützten Serverendpunkt aufrufen.

Wie authentifiziere ich eine IMFA API-Anfrage?

Erzeugen Sie manuell einen agentenbezogenen REST-Schlüssel in der API-Ansicht oder im Schlüsselbereich und senden Sie Authorization: Bearer YOUR_API_KEY vom Server. Ein MCP-Token ist ein anderer Zugang und ersetzt den REST-Schlüssel nicht.

Wie führe ich dasselbe API-Gespräch fort?

Lassen Sie sessionId beim ersten Chat weg, speichern Sie den Rückgabewert und senden Sie ihn im nächsten Body. Nur eine ID aus dem API-Chat führt diesen Kontext fort; Website- und Kanalsitzungen sind schreibgeschützt.

Warum ist Idempotency-Key erforderlich?

Damit lässt sich exakt dieselbe Anfrage sicher wiederholen, ohne aus einem Netzwerk-Retry eine neue Runde zu machen. Nutzen Sie pro neuer Nachricht einen Schlüssel mit 8 bis 128 Zeichen und wiederholen Sie ihn nur für diese Anfrage.

Nutzt die API mein RAG-Wissen und meine Tools?

Ja. Sie ruft den veröffentlichten Agenten mit Anweisungen, Modell, RAG-Wissen, Skills, Tools und Schutzgrenzen auf. Das Ergebnis hängt weiterhin von veröffentlichter Konfiguration, Credits und aktuellen Servicegrenzen ab.

Was passiert bei Rate Limits oder fehlenden Credits?

Die API kann 402 bei leeren Credits oder 429 bei Rate Limiting liefern. Warten Sie bei 429 die Retry-After-Dauer. Behandeln Sie alle Statuscodes und beachten Sie, dass ein interner Generierungsfehler noch eine sessionId liefern kann.