Aller au contenu

Développeurs

Brancher vos applications sur votre instance Belowdecks

Une API REST documentée, un serveur MCP, des webhooks signés et une balise de script. Vos applications lancent des agents, suivent leur travail et récupèrent les résultats, avec les mêmes garde-fous que votre équipe.

Points d’entrée

Chaque système se branche par le protocole qu’il connaît déjà

Une application métier passe par l’API REST, un assistant par MCP, un site web par une balise de script. Tous arrivent dans la même instance, sous les mêmes règles.

  • API REST v1

    Lancez un agent, suivez son exécution, récupérez ses livrables. Votre instance publie la spécification OpenAPI 3.1 et une documentation à parcourir.

  • Serveur MCP

    Un assistant compatible MCP lance des agents, répond à leurs questions, appelle des fonctions, lit et alimente vos collections.

  • Webhooks signés

    Votre système est prévenu à chaque jalon, avec une signature HMAC, des nouvelles tentatives automatiques et un journal des livraisons que vous pouvez rejouer.

  • Déclencheurs par webhook

    Chaque déclencheur a sa propre adresse. Il peut vérifier la signature de l’expéditeur et filtrer les événements par en-tête ou par contenu.

  • Assistant sur votre site

    Une balise de script et la liste des adresses autorisées. Chaque client final ne voit que sa propre conversation.

  • Conversations dans votre application

    Des fils rangés par client final, un jeton d’accès limité aux fils de cette personne et les mêmes cartes de confirmation.

  • Collections

    Votre logiciel de suivi des clients ou votre PGI écrit par l’API dans les collections que vos agents relisent. Si une ligne ne respecte pas le schéma, rien n’est écrit.

  • Fonctions

    Du code nommé que vous appelez directement : la réponse revient dans la même requête, sans file d’attente ni coût de jetons d’IA.

Exemples

Ce que vous écrirez le premier jour

Remplacez hub.example.com par l’adresse de votre instance, et $BELOWDECKS_TOKEN par un jeton d’accès créé pour votre application.

La signature d’un webhook couvre l’horodatage et le corps brut de la livraison. Vérifiez-la avant tout décodage, en temps constant, et refusez une livraison trop ancienne.

La spécification OpenAPI 3.1 de votre instance décrit chaque route. Générez-en le client de votre langage, et régénérez-le quand l’API évolue, au lieu d’entretenir une couche écrite à la main.

bash
# Lancer l'agent. La réponse 202 donne task_id et les adresses de suivi.
TASK_ID=$(curl -s -X POST "https://hub.example.com/api/v1/agents/soumissions/run" \
  -H "Authorization: Bearer $BELOWDECKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"input":{"demande":"D-4821"}}' | jq -r '.task_id')

# Suivre l'exécution en direct (flux SSE).
curl -N -H "Authorization: Bearer $BELOWDECKS_TOKEN" \
  "https://hub.example.com/api/v1/runs/$TASK_ID/stream"

Suivi des exécutions

La vie d’une exécution lancée par l’API

Une exécution est asynchrone. Vous la lancez, puis vous suivez le travail par le moyen qui convient à votre système.

  1. 1

    Vous lancez

    Un POST sur l’agent, avec ses paramètres. La réponse arrive tout de suite avec l’identifiant de l’exécution et les adresses pour la suivre. Une clé d’idempotence empêche qu’une nouvelle tentative réseau lance le travail deux fois.

  2. 2

    Vous suivez, à votre façon

    Interrogation périodique avec un curseur, flux SSE, webhooks signés ou canal WebSocket : les quatre transportent les mêmes événements. Le curseur et l’identifiant SSE sont le même nombre, donc vous changez de méthode sans perdre un événement.

  3. 3

    L’agent pose une question

    Quand il ne peut pas décider seul, l’agent s’arrête et demande. La question arrive dans le flux et par webhook. Votre application recueille la réponse, par exemple celle de votre opérateur, et la transmet par l’API; l’agent reprend alors sa session.

  4. 4

    Vous récupérez le résultat

    L’exécution se termine avec un résumé, son coût, les fichiers livrés et un verdict : Livré, Partiel ou Bloqué. Les exécutions lancées par l’API travaillent dans un espace jetable, alors récupérez ce qui compte à la fin.

Accès et limites

Chaque accès a son territoire et son budget

Un accès d’API représente une application précise, comme votre portail client ou votre PGI. Votre opérateur le crée dans votre instance, ou l’équipe Belowdecks à la mise en place. Il ne voit qu’un projet et ne dépense jamais plus que ce que vous lui accordez.

  • Un seul projet par accès

    Chaque accès d’API est lié à un projet. Toute ressource hors de ce projet lui répond 404 plutôt que 403, pour que l’API ne révèle pas ce qui existe ailleurs.

  • Des plafonds de coût et de cadence

    Pour chaque accès : un plafond par exécution, un budget quotidien et un budget mensuel, un nombre maximal d’exécutions simultanées et de requêtes par minute. Le budget restant borne aussi chaque exécution.

  • Des jetons liés à un client final

    Votre serveur échange son jeton contre un jeton lié à une seule personne, en général un client final qui utilise votre application, valable une heure par défaut. Ce jeton n’atteint que les conversations de cette personne.

  • Les cartes pour les gestes qui engagent

    Ce qu’un client final écrit est transmis au modèle comme une donnée à traiter. Cette précaution réduit le risque d’une consigne cachée sans l’éliminer. Dans une conversation, une action engageante attend donc une carte. Selon le régime d’approbation, elle est confirmée par le client final lui-même pour sa propre demande, par une personne désignée de votre entreprise ou par l’opérateur.

  • Un journal de chaque appel

    Chaque requête est inscrite au journal d’audit, et la consommation se lit par agent. Vous savez qui a lancé quoi, et combien cela a coûté.

  • Deux niveaux de jeton

    Un jeton client lance des agents dans son projet et ne gère rien. Un jeton d’administration, émis depuis le profil d’un administrateur de l’instance, comme votre opérateur, pilote l’instance : projets, agents, compétences et secrets. Un secret s’écrit par l’API, mais sa valeur ne revient jamais.

  • Un interrupteur général

    Quand l’instance est en pause, chaque lancement répond 423, et rien ne démarre avant la reprise.

Salle des machines

Trois moteurs, et les outils que vous leur donnez

Les agents travaillent avec de vrais moteurs en ligne de commande. Vous leur ajoutez des outils et du savoir-faire sans toucher au logiciel.

Trois moteurs au choix

Claude Code d’Anthropic, Codex d’OpenAI ou pi, qui accepte plusieurs fournisseurs de modèles. Le moteur et le modèle se choisissent pour chaque agent.

Des serveurs MCP pour vos agents

Ajoutez un serveur MCP à un projet, et ses agents disposent de ses outils : une API interne, un navigateur, un service en ligne. Vous collez sa configuration, puis vous testez la connexion.

Des fonctions en bash, Python, Node ou PHP

Du code nommé, versionné à chaque modification et essayé sur des exemples avant d’être approuvé. Une fonction peut en appeler d’autres, réveiller un agent, lire ou écrire une collection.

Des compétences en Markdown

Le savoir-faire d’un agent s’écrit en texte simple, dans un fichier SKILL.md. L’agent le lit quand la tâche le demande.

Parlons du système que vous voulez brancher

Dites-nous ce qu’il doit envoyer et recevoir. Au diagnostic, nous voyons ensemble comment le relier à votre instance.