Verbind een beheerde AI-agent met je applicatie

Wat is een AI-agent-API?

Een AI-agent-API laat een vertrouwde applicatie communiceren met een agent die al instructies, kennis, modelinstellingen, tools en gespreksgedrag heeft. Met de IMFA REST API kun je de beschikbare agent opvragen, een chatbericht sturen, een API-sessie vervolgen, opgeslagen berichten lezen en leads ophalen.

Dit is een interface naar een beheerde agent en geen direct model-endpoint. Je configureert en publiceert de agent in IMFA en je server roept hem aan met een sleutel voor die agent. Dezelfde RAG-kennis en goedgekeurde regels kunnen je app, web, WhatsApp, Telegram, Discord en geschikte voice-ervaringen bedienen.

Een productiecontract voor vertrouwde serverintegraties

De API biedt een smal, gedocumenteerd REST-oppervlak rond de gepubliceerde agent, terwijl IMFA kennis, gedrag, modellen, sessies, credits en beveiligingsgrenzen beheert.

Authenticatie met agentbereik

Genereer handmatig een REST-sleutel in de API-weergave van de agent of op het API Keys-scherm. Stuur Authorization: Bearer YOUR_API_KEY. De sleutel wordt eenmaal getoond, alleen als hash opgeslagen en verschilt van het MCP-token van het account.

Idempotente chatverzoeken

POST /v1/agents/{slug}/chat vereist een Idempotency-Key van 8 tot 128 toegestane tekens. Gebruik een nieuwe waarde voor elke afzonderlijke beurt en hergebruik die alleen voor exact hetzelfde verzoek.

Herbruikbare API-context

Laat sessionId weg om een nieuw API-gesprek te starten, bewaar de waarde uit het antwoord en gebruik die bij volgende beurten. Sessie-ID's uit website, builder en kanalen in de historie zijn alleen-lezen.

Sessies, berichten en leads

Bekijk opgeslagen sessies, lees berichten uit één sessie en haal leads op. Gepagineerde GET-routes geven standaard 20 items en accepteren een limiet van 1 tot 100 met een optionele cursor.

Duidelijke limieten en statussen

Chat vereist message, gebruikt de eerste 4.000 tekens, accepteert een sessionId tot 128 tekens en begrenst de body op 64.000 bytes. Statussen onderscheiden validatie, sleutel, credits, beschikbaarheid, pauze, grootte, rate limit en serverfouten.

Hetzelfde beheerde agentsysteem

Antwoorden gebruiken de instructies, het model, de RAG-kennis, skills, tools en beschermingsgrenzen van de gepubliceerde agent. Verzoeken gebruiken credits van de eigenaar en een geslaagd antwoord kan usage.credits bevatten.

Zo roep je een IMFA-agent aan vanaf je server

Publiceer eerst de agent, bescherm de sleutel in een servervariabele en ontwerp retries zodat idempotentie en sessiecontinuïteit intact blijven.

1. Maak en publiceer de beheerde agent

   Definieer instructies, RAG-kennis, model, skills, tools en beschermingsregels in IMFA. Test realistische vragen en publiceer bewust voordat je het REST-endpoint gebruikt.

2. Genereer en bescherm de sleutel

   Open de API-weergave of https://www.imfa.app/app/api-keys, genereer de sleutel handmatig en bewaar hem in een servervariabele zoals IMFA_API_KEY. Plaats hem nooit in browsercode, mobiele bundels, openbare repositories, logs of berichten.

3. Stuur een idempotent serververzoek

   Roep fetch('https://site.imfa.app/v1/agents/{slug}/chat') aan met POST, Authorization: Bearer plus de serversleutel, Content-Type: application/json, een unieke Idempotency-Key en JSON met message en optioneel sessionId. Bewaar reply, sessionId en usage.credits.

IMFA Agent API tegenover een model-API of eigen bouw

De keuze hangt af van welke laag je team zelf wil bezitten. IMFA ontsluit een al beheerde klantagent, terwijl een model-API lagere generatiebouwstenen levert.

Een model-API geeft maximale controle

Kies een provider direct als je prompts, RAG-inname en retrieval, sessieopslag, toolbeleid, authenticatie, limieten, kanalen, observability, facturatie, deployment, beveiliging en onderhoud zelf wilt beheren.

Code-agents bouwen aangepaste software

Codex en Claude Code kunnen applicaties en integraties bouwen. Ze kunnen IMFA ook beheren via MCP, terwijl je productieserver de aparte REST-sleutel met agentbereik gebruikt voor klantverzoeken.

IMFA beheert de agentlevenscyclus

Kies IMFA als je app een agent moet aanroepen waarvan kennis, gedrag, kanalen, sessies, leads, modellen, beschermingsregels, publicatiestatus en gebruik in één interface worden beheerd.

Vijf REST-endpoints voor één gepubliceerde agent

De basis-URL is https://site.imfa.app/v1. Elk verzoek vereist de Bearer-sleutel met agentbereik en chat moet uit vertrouwde serverinfrastructuur komen.

Vraag de beschikbare agent op

GET /v1/agents geeft de agent terug die voor de sleutel beschikbaar is, zodat de server het gepubliceerde integratiedoel kan bevestigen.

Chat met de agent

POST /v1/agents/{slug}/chat stuurt een bericht en retourneert reply, een herbruikbare sessionId, usage.credits en replay-informatie indien van toepassing.

Lees gesprekken

GET /v1/agents/{slug}/sessions geeft gesprekken en GET /v1/agents/{slug}/sessions/{sessionId}/messages leest berichten uit één sessie.

Haal leads op

GET /v1/agents/{slug}/leads retourneert vastgelegde leads met hetzelfde cursor-gebaseerde paginatiecontract.

Veelgestelde vragen over de AI-agent-API

Precieze antwoorden over authenticatie, servergebruik, idempotentie, sessies, RAG, credits en rate limits.

Kan ik de Agent API direct vanuit een browser aanroepen?

Nee. De REST-sleutel gebruikt credits van de eigenaar en moet in een vertrouwde serveromgeving blijven. De API is niet voor direct browsergebruik en biedt geen brede openbare CORS. Laat de browser je eigen beveiligde serverendpoint aanroepen.

Hoe authenticeer ik een IMFA API-verzoek?

Genereer handmatig een REST-sleutel met agentbereik in de API-weergave of op het sleutelscherm en stuur Authorization: Bearer YOUR_API_KEY vanaf je server. Een MCP-token is een ander credential en vervangt de REST-sleutel niet.

Hoe vervolg ik hetzelfde API-gesprek?

Laat sessionId weg bij de eerste chat, bewaar de geretourneerde waarde en voeg die toe aan de volgende body. Alleen een ID uit API-chat kan deze context vervolgen; website- en kanaalsessies zijn alleen-lezen.

Waarom is Idempotency-Key verplicht?

Daarmee kun je exact hetzelfde verzoek veilig herhalen zonder van een netwerkretry een nieuwe beurt te maken. Gebruik een nieuwe sleutel van 8 tot 128 tekens per apart bericht en hergebruik hem alleen voor dat verzoek.

Gebruikt de API mijn RAG-kennis en tools?

Ja. De API roept de gepubliceerde agent aan met instructies, model, RAG-kennis, skills, tools en beschermingsgrenzen. Het resultaat blijft afhankelijk van de gepubliceerde configuratie, credits en actuele servicelimieten.

Wat gebeurt er bij rate limiting of lege credits?

De API kan 402 geven als de credits op zijn of 429 bij rate limiting. Wacht bij 429 de Retry-After-duur. Verwerk alle statussen en houd er rekening mee dat een interne generatiefout nog een sessionId kan teruggeven.