Einen Agenten über die API erstellen

Technische Referenz zum programmatischen Erstellen von Agenten. Was in die Felder gehört, wird hier nicht behandelt, und die Regeln sind gleich, egal wie der Agent erstellt wird. Siehe So bauen Sie Ihren KI-Telefonagenten.

Basis-URL: https://api.kollie.ai. Die Swagger-Oberfläche finden Sie unter derselben Adresse.

Authentifizierung

Erzeugen Sie Ihren eigenen API-Schlüssel auf der Plattform unter API Keys im linken Menü. Dieser Schlüssel authentifiziert jede Anfrage. Es gibt keinen Schritt zur Token-Ausgabe und nichts weiter zu beschaffen.

Einen Agenten bauen: zwei Schritte

Schritt 1: den Agenten anlegen

POST /api/v1/agents

{
  "name": "SALES-EN-DEMOBOOKING",
  "organization_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "config": { }
}

Gibt den angelegten Agenten zurück, inklusive seiner id, die Sie für Schritt 2 brauchen.

Alles über den Agenten steht in config.

Die drei Textfelder:

Diese drei enthalten den gesamten Fließtext, und für alles darin gelten die Regeln aus So bauen Sie Ihren KI-Telefonagenten. Nichts davon wird lockerer, nur weil die Konfiguration als JSON statt über ein Formular kommt.

Alles andere in config ist eine Einstellung. Legen Sie diese fest; beschreiben Sie sie nie in den Textfeldern.

Schritt 2: jeden Skill anhängen

POST /api/v1/agents/{agent_id}/skills, einmal pro Skill. Derselbe Endpunkt aktualisiert auch die Konfiguration eines bestehenden Skills.

{
  "type": "call_transfer",
  "enabled": true,
  "config": {
    "toPhone": "+3120XXXXX01",
    "description": "Sales team, showroom floor. Use this number when the caller is asking about getting a vehicle: availability, delivery times, a price or lease quote, trade-in value, financing, or booking a test drive."
  }
}

Ein Skill, der existiert, aber nicht enabled ist, bewirkt nichts.

Skill-Typen

Geprüft an einem Live-Agenten, der alle Typen nutzt.

Vier Dinge, die diese Tabelle klärt:

• „Vor dem Anruf" und „Nach dem Anruf" sind ein Typ, api, nur durch exec_order unterschieden. Nicht zwei Skills.
• external_action ist der Modus „während des Anrufs" und ein eigenständiger Typ mit den Feldern, die dieser Modus braucht: einem Aktions-name, den der Agent aufruft, einer description, anhand derer er entscheidet, wann, params[] für die Anfrage und results[] für die Antwort.
• „Kontakt nach Attribut abrufen" hat keinen eigenen Typ. Es ist eine external_action, die auf den Suchendpunkt für Kontakte zeigt. Nur die stille Abfrage per Telefonnummer hat einen eigenen Typ.
• exec_order hat nur bei api und external_action eine Bedeutung, dort bestimmt es, wann die Anfrage ausgelöst wird. Bei den anderen Typen wird es gespeichert, hat aber keine zeitliche Bedeutung: Ein call_transfer mit post_call sagt nichts aus.

Welche Typen eine Beschreibung haben, die der Agent liest: call_transfer, external_action und jedes Feld in extract_information. Für diese gelten die Schreibregeln. Die übrigen sind Endpunkte und Integrations-IDs, die der Agent nicht interpretiert.

Fachbegriffe sind kein Skill. Sie sind stt_keyterms in der Agentenkonfiguration.

Weitere Endpunkte

Reihenfolge

1. POST /api/v1/agents mit name, organization_id und einer vollständigen config.
2. Die id aus der Antwort übernehmen.
3. POST /api/v1/agents/{id}/skills einmal pro Skill, jeweils mit enabled: true.
4. GET /api/v1/agents/{id} und prüfen, ob das Zurückgegebene dem Gesendeten entspricht.
5. Einen Testanruf machen.

Sie steuern das über ein Skript oder ein LLM? Die Inhaltsregeln aus So bauen Sie Ihren KI-Telefonagenten gelten unverändert, und die automatische Prüfung vor dem Speichern ist so geschrieben, dass sie als Validierungsschritt vor Schritt 1 laufen kann.

Sicherheit

Ihr API-Schlüssel ist geheim. Bewahren Sie ihn in einer Umgebungsvariable oder einem Secrets-Manager auf: nie in der Versionsverwaltung, nie in einem Ticket, nie in einem geteilten Dokument. Wurde ein Schlüssel einem Modell in einer Unterhaltung gezeigt, gilt er als offengelegt und muss ersetzt werden. Das ist hier besonders wichtig: Steuert ein LLM Ihr Skript, soll es das Skript steuern, nicht den Schlüssel kennen.

Schreiben Sie nie Zugangsdaten in business_info, main_objective oder eine Skill-description. Das sind Prompt-Inhalte. Alles darin liest der Agent bei jedem Anruf, und was der Agent gelesen hat, kann man ihn dazu bringen auszusprechen.

Zugangsdaten, die ein Skill wirklich braucht, gehören in die Konfiguration dieses Skills: bei einer external_action in das header-Objekt mit name und value. Das ist der richtige Ort, und der einzige.

Aber bedenken Sie: Skill-Zugangsdaten sind lesbar. GET /api/v1/agents/{agent_id} gibt die vollständige Konfiguration jedes Skills zurück, Header-Werte im Klartext eingeschlossen. Wer einen Agenten über die API lesen oder sein JSON exportieren kann, kann die Schlüssel darin lesen. Deshalb:

• Geben Sie jedem Skill den kleinstmöglichen Schlüssel, nie einen geteilten oder einen mit Admin-Rechten.
• Behandeln Sie jedes exportierte Agenten-JSON als geheim.
• Entfernen Sie Header-Werte, bevor Sie eine Konfiguration in ein Ticket, einen Chat, ein Dokument oder ein Modell einfügen.

Achten Sie auf results[] bei external_action. Bleibt es leer, erhält der Agent die gesamte API-Antwort: jedes Feld, das der Endpunkt zurückgibt, inklusive interner IDs und Debug-Ausgaben. Filtern ist optional. Ordnen Sie nur die Felder zu, die Sie wirklich brauchen, und halten Sie die Liste kurz: Das kostet eine Zeile Konfiguration und verhindert, dass von Angreifern steuerbarer Freitext in nicht benötigten Feldern als Inhalt beim Agenten ankommt.

{{ platzhalter }}-Tokens sind keine Zugangsdaten. Sie sind Lückentexte, damit eine gespeicherte Vorlage für einen anderen Kunden wiederverwendet werden kann. Setzen Sie nie einen echten Schlüssel dafür ein.