Vite faire, mais bien faire

Un projet récent d’un client portait sur une application mobile pour engager des conversations asynchrones : on enregistre une vidéo pour lancer une discussion, on fait défiler les vidéos déjà publiées et on répond en vidéo à toute amorce de discussion ou à toute réponse. Très bien. Sauf que son agent IA avait sans vergogne inventé un POST /medias/like, un DELETE /playlist/item, et deux ou trois paramètres qui n’ont jamais existé chez nous. Le code était propre, commenté, élégant, mais il ne pouvait pas fonctionner.

La nécessité de proposer une « skill » était criante. Autrement dit, un dossier de fichiers texte que l’assistant IA lit avant de coder, pour savoir de quoi il parle.

Parenthèse écologique, puisqu’il faut bien la faire

Vous nous connaissez, l’IA n’est pas exactement notre danseuse. On a écrit un article entier sur
l’impact carbone de l’IA et de la vidéo et la conclusion ne fait pas de nous des supporters des datacenters à 5 gigawatts.

Sauf qu’un agent qui devine notre API se trompe, relance, redevine, relance encore, et finit par sortir du code qu’un humain devra reprendre à la main. Trente allers-retours là où trois auraient suffi. À ce compte, écrire une bonne documentation était sans doute le geste le plus sobre à notre portée.

Ce qu’on a mis dedans

C’est ici, public :
github.com/Streamlike/streamlike-integration-skill

Le fichier d’entrée répond d’abord à la question qui décide de tout le reste : par quelle porte entrer. Il y en a trois. Les webservices pour lire le catalogue, faits pour ça et rapides. L’API REST pour écrire, administrer, envoyer des fichiers, et jamais, jamais depuis une application mobile ou un navigateur, parce qu’une clé d’API donne tous les droits de son propriétaire. Le SDK JavaScript quand vous voulez un lecteur de playlist qui tourne en quatre lignes.

Viennent ensuite les références, une par sujet : les quinze webservices avec leurs vrais formats de réponse, les conventions de l’API, les soixante-neuf paramètres du lecteur, la sécurité, les statistiques, les flux RSS et sitemaps.

Et puis les pièges, ceux qui ne sont écrits nulle part parce que personne ne pense à les écrire.

• le paramètre page des webservices est un décalage, pas un numéro de page. pagesize=10&page=1 vous rend les éléments 1 à 10, et vous vous demandez pourquoi la deuxième page ressemble tant à la première,
• sortorder attend up ou down. Si vous tapez desc, comme n’importe qui de sensé, vous récoltez un 404. En rédigeant la skill, on s’est aperçus qu’on ne l’avait écrit nulle part,
• les erreurs des webservices arrivent sous forme de page HTML avec un code 404. Ni JSON, ni message. Votre parseur s’étrangle et vous cherchez pendant vingt minutes.

Un agent qui a lu ça écrit du code qui marche. Un agent qui ne l’a pas lu écrit du code qui a l’air de marcher, ce qui est nettement plus pénible.

Trois recettes, de l’expression de besoin au code

Nous avons ouvert un livre de recettes qui propose déjà trois exemples et s’enrichira régulièrement :

• Une application mobile à défilement, celle du client par qui tout est arrivé : où stocker les « j’aime » et les vidéos écartées (chez vous, pas chez nous, et l’article explique pourquoi), quand mettre les lecteurs en pause, comment ne pas faire exploser le forfait data de vos utilisateurs.
• Une webTV : playlists, recherche jusque dans les transcriptions, videositemap pour le référencement, lecteur de playlist prêt à poser.
• Ingestion automatique de médias : envoyer un fichier, suivre son encodage sans le deviner, le sous-titrer, le publier…

S’y ajoute un fichier d’exemples qui tournent tels quels avec une vidéo de démonstration.

Pas besoin de disposer d’un compte pour essayer. C’est aussi le moyen le plus rapide de savoir si le problème vient de votre code ou de nous.

L’outil dont on est le plus content

Notre description OpenAPI pèse 2,5 Mo. Aucun assistant ne peut l’avaler entière, et quand il essaie, il oublie la moitié de votre projet en chemin. La skill embarque donc un petit utilitaire qui va chercher uniquement ce qu’il faut :

scripts/openapi_lookup.py show /medias --method post
scripts/openapi_lookup.py search "audio track"

Il télécharge le fichier tout seul et interroge toujours la version publiée. Nos endpoints bougent, la skill suit sans que vous ayez à la mettre à jour.

Pour finir, deux ou trois honnêtetés

Tout cela ne remplace pas notre documentation et encore moins notre support. Il vous faudra toujours un compte, un company_id et une clé d’API, que nous créons pour vous. Et votre assistant continuera de raconter n’importe quoi sur le reste du monde mais on n’y peut rien.

Sur Streamlike, en revanche, il aura lu le manuel.

Les liens, tous au même endroit :

• la skill : github.com/Streamlike/streamlike-integration-skill ⁽¹⁾,
• les SDK JavaScript et PHP : github.com/Streamlike,
• la description de l’API : api.streamlike.com/openapi.json,
• celle des webservices : cdn.streamlike.com/openapi.json.

Installez le dossier dans votre outil, décrivez votre projet, voyez ce qui sort. Et si votre agent invente encore un endpoint, dites-le nous : ça voudra dire qu’il nous manque une page.

(1) autre honnêteté : « Skill made by Madame Claude ». Oui, c’est comme ça qu’on l’appelle chez nous.