Intégrer Tin à votre propre produit avec l’Agent API

Tin est l’agent qui transforme des idées éparses en prochaines étapes claires. La plupart des gens parlent à Tin dans le chat endue. Ouvrez l’API, et ce même Tin peut travailler à l’intérieur de ce que vous avez construit : derrière un bouton « Transformer en plan » dans votre application de notes, dans un script qui tourne chaque matin, ou dans une automatisation qui se déclenche à chaque formulaire reçu.

Tin appelé par l’API est le même agent que celui avec qui vous discutez. Il utilise les mêmes instructions, les mêmes compétences, les mêmes connecteurs et la même mémoire, et l’utilisation est décomptée sur votre compte. Aucun serveur à héberger, aucun modèle à brancher.

Comment tout s’articule

1. Dans Studio, vous générez une clé API qui ne fonctionne que pour Tin.
2. Votre serveur envoie une requête à Tin avec cette clé. Le corps peut se limiter à une seule phrase qui dit ce dont vous avez besoin.
3. Tin renvoie sa réponse. L’échange est aussi enregistré dans votre liste de conversations endue : vous pouvez le relire plus tard sur le web.

Idéal pour

• Une fonctionnalité de votre propre application. Envoyez la note d’un utilisateur à Tin et affichez sur votre propre écran le plan qu’il renvoie. Vos utilisateurs n’ont jamais besoin de savoir qu’endue existe.
• Des tâches planifiées. Une tâche cron envoie ce qui n’a pas été terminé la veille, et Tin le ramène à trois choses à faire aujourd’hui. C’est votre code qui décide où va le résultat : une publication sur l’intranet, votre base de données, un message de chat.
• Les outils d’automatisation no-code. Tout outil capable d’envoyer une requête HTTP, comme Zapier, Make ou n8n, peut appeler Tin sans une ligne de code.

Si vous n’avez besoin du résultat que dans endue, une routine est plus simple. Passez par l’API lorsque le résultat doit arriver dans votre propre système.

Ce qu’il vous faut

• Un compte endue et un agent. Ce guide utilise Tin.
• Un endroit d’où envoyer les requêtes : un terminal, le serveur de votre produit ou un outil d’automatisation capable d’émettre des requêtes HTTP.
• Un endroit sûr pour la clé, par exemple une variable d’environnement ou un gestionnaire de secrets sur votre serveur.

Étape 1. Ouvrir l’API dans Studio

Ouvrez Tin et passez sur Studio en haut de l’écran pour afficher la configuration de l’agent. Dans la colonne « 01 Requests come in » (les requêtes arrivent) se trouve une carte API. Cliquez dessus : le panneau API s’ouvre à droite.

L’adresse POST en haut du panneau est le point de terminaison (endpoint) de Tin. L’exemple curl situé juste en dessous se copie en un clic et contient déjà l’identifiant d’agent de Tin.

Étape 2. Générer une clé pour Tin

Cliquez sur Issue key (générer une clé) et renseignez deux éléments.

• Key name (nom de la clé). Indiquez où la clé sera utilisée, par exemple « Planner app server ». Ce nom s’affiche à côté des conversations arrivées par cette clé et, lorsque vous aurez plusieurs clés, vous saurez d’un coup d’œil laquelle révoquer.
• Expiration. Choisissez entre aucune expiration, 30, 90 ou 365 jours. Une durée courte est le choix le plus sûr pendant vos tests.

Cliquez sur Issue : une clé commençant par sk_ s’affiche une seule et unique fois. Vous ne pourrez plus la voir après avoir fermé la fenêtre, alors copiez-la aussitôt en lieu sûr. Si vous la perdez, révoquez-la et générez-en une nouvelle. L’exemple de requête en haut du panneau contient désormais lui aussi la nouvelle clé : vous pouvez le copier et tester sans attendre.

Une clé créée ici est dédiée à Tin. Elle ne peut pas appeler vos autres agents. Les clés valables pour tout le compte, capables d’appeler n’importe quel agent, se génèrent à part dans Settings › Account › API Keys ; mais si un seul agent vous suffit, la clé dédiée est le choix le plus sûr.

Étape 3. Envoyer votre première requête

Vous pouvez essayer directement depuis un terminal. Gardez la clé dans une variable d’environnement au lieu de la saisir dans la commande. Pour AGENT_ID, reprenez l’adresse que vous avez copiée dans Studio.

export ENDUE_API_KEY="sk_..."   # la clé de l’étape 2

curl -X POST https://platform.endue.ai/api/public/v1/agents/AGENT_ID/invoke \
  -H "Authorization: Bearer $ENDUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Turn this into a plan for this week: I want to start a small newsletter for our cafe. I have about 5 hours this week."}'

Quand Tin a terminé, vous recevez une réponse de ce type.

{
  "success": true,
  "data": {
    "run_id": "...",
    "session_id": "cnv_...",
    "conversation_id": "cnv_...",
    "agent_id": "...",
    "status": "completed",
    "finish_reason": "final",
    "output_text": "Here's a week that gets the first issue out without eating your weekend. ...",
    "usage": { "input_tokens": 1830, "output_tokens": 264, "total_tokens": 2094 }
  }
}

Trois champs comptent plus que les autres.

• output_text : la réponse de Tin, la partie que vous affichez sur votre écran.
• session_id : l’identifiant de la conversation. Renvoyez-le avec votre requête suivante pour poursuivre l’échange. conversation_id porte la même valeur ; c’est le nom qu’emploie l’indication affichée dans Studio.
• status : completed signifie que Tin a répondu jusqu’au bout. incomplete signifie qu’il a épuisé ses étapes ou qu’il s’est arrêté à un point qui demandait la décision d’une personne. Réessayez avec une demande plus précise.

Étape 4. Poursuivre la conversation

Imaginons que votre utilisateur réponde « Mercredi, je ne peux pas. » Envoyez cette phrase avec le session_id de la réponse précédente, et Tin révise le plan qu’il avait déjà établi.

{
  "input": "I can't do Wednesday. Move that part to Thursday and redo the plan.",
  "session_id": "cnv_..."
}

Omettez session_id et une nouvelle conversation démarre. Pour garder une conversation par utilisateur ou par note, stockez le session_id à côté, dans votre base de données.

Étape 5. Le brancher sur votre produit

Imaginez un bouton « Transformer en plan » dans une application de notes. Une règle passe avant toutes les autres : le code qui appelle Tin vit sur votre serveur. Une clé placée dans un navigateur ou une application mobile peut être lue par quiconque prend la peine de regarder. Votre écran parle à votre serveur, et votre serveur parle à Tin.

Sur un serveur Node.js, cela donne ceci.

// Code serveur. La clé provient d’une variable d’environnement.
const TIN_URL = 'https://platform.endue.ai/api/public/v1/agents/AGENT_ID/invoke';

export async function askTin(input, sessionId) {
  const res = await fetch(TIN_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ENDUE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(sessionId ? { input, session_id: sessionId } : { input }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.error?.message ?? `HTTP ${res.status}`);
  return { plan: body.data.output_text, sessionId: body.data.session_id };
}

Un script Python pour l’exécution du matin est encore plus court.

import os
import requests

res = requests.post(
    "https://platform.endue.ai/api/public/v1/agents/AGENT_ID/invoke",
    headers={"Authorization": f"Bearer {os.environ['ENDUE_API_KEY']}"},
    json={"input": "Left over from yesterday: reply to the quote, order coffee beans, blog draft. Give me three things to do today."},
    timeout=120,
)
res.raise_for_status()
print(res.json()["data"]["output_text"])

Par défaut, l’appel attend que Tin ait terminé et renvoie tout en une fois. Une requête qui demande une vraie réflexion peut prendre plusieurs dizaines de secondes : prévoyez un délai d’expiration (timeout) généreux. Si vous voulez que le texte apparaisse à mesure qu’il s’écrit, comme dans un chat, ajoutez "stream": true à la requête. Vous recevez alors le même flux SSE que celui du chat web : run_created, puis des événements delta contenant des fragments de texte, puis done.

Chaque appel laisse une trace dans endue

Les conversations arrivées par l’API sont rassemblées dans le groupe API de la barre latérale de Tin. Le message de l’appelant porte la mention « API caller », et la clé par laquelle il est arrivé est indiquée à côté du titre. Si une réponse vous a paru étrange, c’est ici que vous voyez exactement ce qui a été demandé à Tin et ce qu’il a répondu.

Ces conversations sont en lecture seule dans endue. La seule façon d’en poursuivre une est un nouvel appel API avec le même session_id.

La vue de configuration de Studio change elle aussi. La nouvelle clé apparaît sur la carte API avec l’état Active, et une ligne la relie à Tin.

Avant de vous y fier

Personne n’est assis devant un appel API ; endue le traite donc comme une exécution sans surveillance.

• Les actions qui envoient quelque chose vers l’extérieur ou qui suppriment quelque chose, comme l’envoi d’un e-mail, sont refusées au lieu d’attendre une approbation. Les actions en lecture seule, comme une simple consultation, fonctionnent comme d’habitude.
• Si Tin a besoin de poser une question, personne n’est là pour y répondre. Donnez-lui d’emblée ce qu’il lui faut : échéances, temps disponible, format attendu en retour.

Le meilleur partage des rôles : Tin rend des brouillons et des plans, et votre propre code se charge d’envoyer et d’enregistrer.

Protéger vos clés

• Les clés restent sur le serveur. Jamais dans du code exécuté par le navigateur, une application mobile ou un dépôt git.
• Une clé par lieu d’utilisation. Avec des clés distinctes comme « Planner app server » et « Morning summary script », une fuite oblige à révoquer une seule clé, pas toutes.
• Révoquez sans tarder. Appuyez sur Revoke dans le panneau API : les requêtes utilisant cette clé sont bloquées en moins d’une minute.
• Fixez une expiration. Les clés sur le point d’expirer, ou déjà expirées, sont signalées dans le panneau et dans Studio.

Ce que disent les codes d’état

• 401 : la clé est absente, incorrecte, expirée ou révoquée.
• 403 : vous avez appelé Tin avec une clé dédiée à un autre agent.
• 404 : l’identifiant d’agent est incorrect, ou le session_id appartient à un autre agent.
• 409 : une requête précédente sur la même session est encore en cours. Renvoyez la vôtre une fois qu’elle est terminée.
• 402 : vous avez atteint la limite d’utilisation de votre forfait. Vérifiez ce qu’il vous reste sur la page Usage.

Les champs de requête et les limites sont détaillés dans la documentation de l’Agent API.