Waarom je je AI-agent via een API aan je app koppelt

Wat is een AI-agent-API?

Met een AI-agent-API stuurt je eigen software een bericht naar een agent die je al hebt gebouwd en krijgt het zijn antwoord terug. De agent houdt zijn instructies, kennis, model, tools en veiligheidsregels. Je app stuurt alleen de vraag.

Dat is het verschil met een kale model-API. Een model-API geeft je tekstgeneratie en laat de rest aan jou over: prompts, zoeken in documenten, geheugen, rate limits, facturatie. De REST API van IMFA geeft je een beheerde agent die dat allemaal al heeft, achter één sleutel per agent.

Je bouwt de agent met de AI-chatbotbouwer. De API is nog een plek waar hij kan antwoorden, naast je website, WhatsApp, Instagram, Facebook, Telegram, Discord en de spraaklijn.

Wanneer koppel je je agent via een API?

Kies de API als het gesprek plaatsvindt in iets dat van jou is:

• Je app of klantportaal heeft een hulpassistent nodig die je voorwaarden kent, zonder een tweede chatbot om te onderhouden.
• Je backend moet vragen uit een ander systeem beantwoorden, zoals bestelpagina's, een boekingstool of een intern dashboard.
• Je wilt je leads in je CRM. De API geeft de leads terug die de agent op elk kanaal heeft vastgelegd, zodat je ze volgens een schema kunt synchroniseren.
• Je hebt de gespreksgeschiedenis nodig voor rapportage of kwaliteitscontrole.

Heb je alleen een chatbubbel op een website nodig, dan is de insluitregel van één regel eenvoudiger. De API is voor wanneer je product de interface is, niet de widget.

Hoe de IMFA-agent-API werkt

De basis-URL is https://site.imfa.app/v1. Elke aanroep heeft de sleutel van de agent nodig en moet komen van vertrouwde servercode, nooit van een browser of een mobiele bundel.

1. Publiceer de agent. Stel zijn instructies, kennis, model en tools in IMFA in, test echte vragen en publiceer. De API bedient de gepubliceerde versie.
2. Genereer de sleutel. Open de API-weergave van de agent of het scherm API Keys en genereer een sleutel. Die wordt één keer getoond en alleen als hash opgeslagen. Bewaar hem in een omgevingsvariabele op de server, zoals IMFA_API_KEY.
3. Stuur een chatverzoek. POST /v1/agents/{slug}/chat met Authorization: Bearer <key>, een unieke Idempotency-Key (8 tot 128 tekens) en een JSON-body met message en een optionele sessionId. Het antwoord komt terug met een sessionId en usage.credits.
4. Zet het gesprek voort. Laat sessionId weg bij de eerste beurt en stuur daarna de waarde mee die je hebt ontvangen. De agent onthoudt de context.
5. Lees wat er is gebeurd. GET /v1/agents/{slug}/sessions toont de gesprekken, GET /v1/agents/{slug}/sessions/{sessionId}/messages leest er één, en GET /v1/agents/{slug}/leads geeft de vastgelegde leads terug. Lijsten geven standaard 20 items terug, tot 100, met een cursor. GET /v1/agents bevestigt welke agent de sleutel bedient.

De grenzen zijn expliciet: de eerste 4.000 tekens van een bericht worden gebruikt, bodies zijn begrensd op 64.000 bytes en fouten hebben een type (validatie, authenticatie, credits, rate limit, server). Een 429 komt met Retry-After; een 402 betekent dat de credits van de eigenaar op zijn.

Waarom de agent-API gebruiken in plaats van zelf te bouwen

Je slaat maanden aan infrastructuur over. Zoeken in documenten, sessies, rate limits, nieuwe pogingen, creditadministratie en regels tegen prompt injection draaien al. Je team schrijft één HTTP-aanroep.

Eén agent, één gedrag. Het antwoord dat je app toont, is hetzelfde als op je website en in WhatsApp, omdat het dezelfde agent is. Werk hem één keer bij in IMFA en elk kanaal volgt.

Nieuwe pogingen zijn veilig. Dankzij de idempotency key geeft een nieuwe poging na een netwerkfout het oorspronkelijke antwoord terug, in plaats van een tweede beurt te rekenen.

Leads zitten niet meer in losse eilandjes. Haal elke vastgelegde lead op via één endpoint, via welk kanaal hij ook binnenkwam.

Volledig maatwerk blijft mogelijk. Wil je elke laag zelf in handen hebben, dan geeft een kale model-API je die controle, ten koste van het zelf bouwen en draaien. Coding agents zoals Codex en Claude Code kunnen IMFA-agents ook beheren via MCP, terwijl je server de REST-sleutel gebruikt om klanten te bedienen.

Veelgestelde vragen over de AI-agent-API

Kan ik de AI-agent-API rechtstreeks vanuit een browser aanroepen?

Nee. De sleutel verbruikt de credits van de eigenaar en moet op een vertrouwde server blijven. De API staat geen brede browsertoegang toe. Laat je browser je eigen beveiligde endpoint aanroepen, dat vervolgens IMFA aanroept.

Hoe authenticeer ik een verzoek aan de IMFA-agent-API?

Genereer een sleutel voor de agent in de API-weergave van de agent of het scherm API Keys en stuur vanuit servercode Authorization: Bearer YOUR_API_KEY mee. Een MCP-token is een andere referentie en werkt hier niet.

Hoe zet ik hetzelfde API-gesprek voort?

Laat sessionId weg bij het eerste chatverzoek, bewaar de sessionId die de API teruggeeft en stuur die mee met het volgende bericht. Sessie-ID's uit gesprekken op de website of andere kanalen zijn alleen-lezen en kunnen geen API-gesprek voortzetten.

Waarom is een Idempotency-Key verplicht voor chat?

Die maakt nieuwe pogingen veilig. Een exacte herhaling met dezelfde sleutel geeft hetzelfde resultaat terug in plaats van een nieuwe beurt te maken. Gebruik voor elk nieuw bericht een nieuwe sleutel.

Gebruikt de agent-API mijn kennis en tools?

Ja. Hij roept de gepubliceerde agent aan met zijn instructies, model, kennis, skills, tools en veiligheidsregels. Antwoorden blijven afhankelijk van de gepubliceerde configuratie, je credits en de huidige limieten van de dienst. Bij een rate limit krijg je een 429 met een Retry-After-header, en een 402 als de credits van de eigenaar op zijn.