Een agent maken via de API

Technische referentie voor het programmatisch bouwen van agents. Wat je in de velden schrijft, staat hier niet, en de regels zijn hetzelfde, hoe de agent ook wordt gebouwd. Zie Zo bouw je je AI-telefoonagent.

Basis-URL: https://api.kollie.ai. De Swagger-interface staat op hetzelfde adres.

Authenticatie

Maak je eigen API-sleutel aan op het platform onder API Keys in het linkermenu. Die sleutel authenticeert elk verzoek. Er is geen stap om een token op te halen en verder niets nodig.

Een agent bouwen: twee stappen

Stap 1: de agent aanmaken

POST /api/v1/agents

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

Geeft de aangemaakte agent terug, inclusief zijn id, die je nodig hebt voor stap 2.

Alles over de agent staat in config.

De drie tekstvelden:

Deze drie bevatten alle lopende tekst, en daarvoor gelden de regels uit Zo bouw je je AI-telefoonagent. Niets daarvan wordt soepeler omdat de configuratie als JSON binnenkomt in plaats van via een formulier.

Al het andere in config is een instelling. Stel die in; beschrijf ze nooit in de tekstvelden.

Stap 2: elke skill koppelen

POST /api/v1/agents/{agent_id}/skills, één keer per skill. Hetzelfde endpoint werkt ook de configuratie van een bestaande skill bij.

{
  "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."
  }
}

Een skill die bestaat maar niet enabled is, doet niets.

Skilltypes

Gecontroleerd op een live agent die ze allemaal gebruikt.

Vier dingen die deze tabel duidelijk maakt:

• Voor en na het gesprek zijn één type, api, alleen onderscheiden door exec_order. Geen twee skills.
• external_action is de modus "tijdens het gesprek" en een echt apart type, met de extra velden die die modus nodig heeft: een actie-name die de agent aanroept, een description waarmee hij bepaalt wanneer, params[] voor het verzoek en results[] voor het antwoord.
• Contact ophalen op attribuut heeft geen eigen type. Het is een external_action die naar het zoek-endpoint voor contacten wijst. Alleen de stille opzoeking op telefoonnummer heeft een eigen type.
• exec_order betekent alleen iets bij api en external_action, waar het bepaalt wanneer het verzoek wordt verstuurd. Bij de andere types wordt het opgeslagen maar zegt het niets over timing: een call_transfer met post_call betekent niets.

Welke types een beschrijving hebben die de agent leest: call_transfer, external_action en elk veld binnen extract_information. Daarvoor gelden de schrijfregels. De rest zijn endpoints en integratie-ID's die de agent niet interpreteert.

Vaktermen zijn geen skill. Ze zijn stt_keyterms in de agentconfiguratie.

Andere endpoints

Volgorde

1. POST /api/v1/agents met name, organization_id en een volledige config.
2. Neem de id uit het antwoord over.
3. POST /api/v1/agents/{id}/skills één keer per skill, elk met enabled: true.
4. GET /api/v1/agents/{id} en controleer of wat terugkomt overeenkomt met wat je hebt verstuurd.
5. Doe een testgesprek.

Stuur je dit aan met een script of een LLM? De inhoudsregels uit Zo bouw je je AI-telefoonagent gelden ongewijzigd, en de automatische controle voor het opslaan is zo geschreven dat hij als validatiestap vóór stap 1 kan draaien.

Beveiliging

Je API-sleutel is geheim. Bewaar hem in een omgevingsvariabele of een secrets manager: nooit in versiebeheer, nooit in een ticket, nooit in een gedeeld document. Is een sleutel in een gesprek aan een model getoond, beschouw hem dan als gelekt en vervang hem. Dat is hier extra belangrijk: als een LLM je script aanstuurt, moet het het script aansturen, niet de sleutel kennen.

Zet nooit inloggegevens in business_info, main_objective of een skill-description. Dat is promptinhoud. Alles daarin leest de agent bij elk gesprek, en wat de agent heeft gelezen, kan hij worden overgehaald uit te spreken.

Inloggegevens die een skill echt nodig heeft, horen in de configuratie van die skill: bij een external_action in het header-object met name en value. Dat is de juiste plek, en de enige.

Maar weet wat dat betekent: skill-inloggegevens zijn leesbaar. GET /api/v1/agents/{agent_id} geeft de volledige configuratie van elke skill terug, inclusief headerwaarden in platte tekst. Wie een agent via de API kan lezen of zijn JSON kan exporteren, kan de sleutels erin lezen. Daarom:

• Geef elke skill de kleinst mogelijke sleutel, nooit een gedeelde of een met beheerdersrechten.
• Behandel elke geëxporteerde agent-JSON als geheim.
• Verwijder headerwaarden voordat je een configuratie in een ticket, chat, document of model plakt.

Let op results[] bij external_action. Laat je het leeg, dan krijgt de agent het hele API-antwoord: elk veld dat het endpoint teruggeeft, inclusief interne ID's en debug-uitvoer. Filteren is optioneel. Koppel alleen de velden die je echt nodig hebt en houd de lijst kort: het kost één regel configuratie en voorkomt dat door aanvallers beïnvloedbare vrije tekst in ongebruikte velden als inhoud bij de agent belandt.

{{ placeholder }}-tokens zijn geen inloggegevens. Het zijn invulplekken om een opgeslagen sjabloon voor een andere klant te hergebruiken. Vervang ze nooit door een echte sleutel.