Les SDK

Utilisez un SDK quand votre code doit communiquer directement avec un hub Thalovant.

L’API Thalovant est le plan de contrôle, à https://api.thalovant.com. Elle découvre les hubs et crée les identités de client. Le SDK est le plan de données. Il envoie le trafic du runtime au hub par WSS, par HTTPS ou par MQTT sur TLS.

Le meilleur point de départ

1. Choisissez le SDK de votre environnement d’exécution. Python, Node.js, Go, Rust, Kotlin, Swift et .NET offrent le même comportement de base. Embedded C est une bibliothèque de protocole pour les appareils qui fournissent leur propre transport.
2. Utilisez l’API hébergée. Commencez avec https://api.thalovant.com.
3. Créez une identité de client par application, appareil ou agent. Conservez l’identité retournée dans un magasin de secrets ou dans un fichier de configuration SDK protégé.
4. Connectez-vous d’abord par WSS. C’est le chemin temps réel par défaut pour les clients publics, et c’est le seul protocole de plan de données des SDK Kotlin, Swift et .NET.
5. Ajoutez HTTPS, MQTT ou l’accès par origine de navigateur seulement au besoin. Créez une nouvelle identité après avoir activé un nouveau protocole sur le hub, et demandez une origine SDK approuvée avant d’appeler l’API depuis une application de navigateur qui appartient au client.

Choisir un langage

Langage	Installation	Usage idéal
Python	pip install thalovant	Agents, outils, carnets (notebooks), tests et processus de service.
Node.js	npm install @thalovant/sdk	Services TypeScript, robots, scripts, serveurs Web et applications de navigateur empaquetées.
Go	go get github.com/thalovant/thalovant-go-sdk	Passerelles, outils en ligne de commande, petits services et processus de longue durée.
Rust	cargo add thalovant	Clients stricts, travail embarqué et services axés sur la fiabilité.
Kotlin	implementation("com.thalovant:thalovant-sdk") — voir Versions prises en charge	Services JVM et applications Android.
Swift	Paquet SwiftPM tiré du dépôt GitHub	Applications iOS et macOS; Linux exige un runtime Foundation qui gère WebSocket.
C# / .NET	dotnet add package Thalovant.Sdk	Services .NET d’entreprise et applications Unity.
C	Source intégrée au projet, épinglée à une étiquette de version	Microcontrôleurs et appareils embarqués qui fournissent leur propre client MQTT ou WebSocket.

SDK PythonCommencer avec Python.

SDK Node.jsCommencer avec Node.js, TypeScript ou une application de navigateur empaquetée.

SDK GoCommencer avec Go.

SDK RustCommencer avec Rust.

SDK KotlinCommencer avec Kotlin sur la JVM ou Android.

SDK SwiftCommencer avec Swift sur iOS, macOS ou Linux.

SDK .NETCommencer avec C# sur .NET ou Unity.

Bibliothèque C embarquéeCréer un client d'appareil en C99 avec votre propre transport.

Niveaux de fonctionnalités

Les SDK ne couvrent pas encore tous les protocoles. Choisissez le niveau qui correspond aux besoins de votre environnement d’exécution.

Niveau	SDK	Plan de données	Plan de contrôle
Complet	Python, Node.js, Go, Rust	WSS, HTTPS et MQTT sur TLS	Connexion avec authentification multifacteur (AMF), connexion par appareil, authentification par jeton d’API, provisionnement et suivi typé des opérations
WSS seulement	Kotlin, Swift, .NET	WSS seulement; demander HTTPS ou MQTT lève une erreur claire de protocole non pris en charge	Connexion avec AMF, connexion par appareil, authentification par jeton d’API, provisionnement et suivi typé des opérations
Bibliothèque de protocole	Embedded C	Aucun intégré; vous fournissez le client MQTT ou WebSocket, et la bibliothèque fournit l’analyse de l’identité, les sujets, le chiffrement et le tramage réseau	Aucun

Les applications de navigateur utilisent le SDK Node derrière un empaqueteur (bundler) : le plan de contrôle et le plan de données WSS et HTTPS fonctionnent dans les paquets Web, tandis que MQTT et les utilitaires de fichier d’identité restent réservés à Node. Consultez Utilisation dans un navigateur avec le SDK Node.

Fonctionnalités communes du runtime

Les sept SDK de haut niveau offrent ces fonctionnalités dans les transports qu’ils prennent en charge. Embedded C expose les primitives correspondantes de construction et d’analyse des trames réseau; l’application gère la connexion, l’ordonnancement, la collecte et l’annulation.

Fonctionnalité	Python, Node.js, Go, Rust	Kotlin, Swift, .NET	Embedded C
Connexion, AMF, connexion par appareil, jetons, provisionnement, suivi des opérations	Pris en charge	Pris en charge	L’application fournit le plan de contrôle
Gestion des compétences et historique adressés au hub	Pris en charge; touche le groupe de runtime partagé rattaché	Pris en charge; touche le groupe de runtime partagé rattaché	L’application fournit le plan de contrôle
Ask, réponses query/cascade à portée limitée, événements bruts, entrées d’action et de code	Pris en charge	Pris en charge par WSS	Constructeurs de trames et classement des réponses
Conversations, attentes et flux d’événements	Pris en charge; les flux Node utilisent des abonnements par rappel	Pris en charge; les flux mettent au plus 64 événements en mémoire tampon	L’application gère la collecte et l’état de session
Liste des intentions, descriptions et repli sur les noms seulement	Pris en charge	Pris en charge	Constructeurs de requêtes et lecteurs de réponses
Gestionnaires de repli et disponibilité prudente des langues	Champs d’inventaire en Python/Node; enveloppe de capacité additive en Go/Rust	Champs d’inventaire avec mayAnswer en Kotlin/Swift et MayAnswer en .NET	Trames de repli et classement des réponses; l’application calcule la disponibilité
Langue reconnue, pipeline ordonné et indices d’emplacement de la requête	Options et utilitaires de requête natifs	Utilitaires de requête natifs	Constructeurs de charge utile et de trames avec indices, et constructeur d’emplacement
Audio de compétence intégré et langue signalée	Parole et audio ordonnés, limites de 4 Mio par extrait et de 16 Mio par réponse	Mêmes limites et médias ordonnés dans les réponses WSS	Décodeur sensible à la corrélation; budget et collecte gérés par l’appelant
Exemples d’intentions prononçables	Rendu facultatif et classement par priorité de source	Rendu facultatif et classement par priorité de source	Moteur de rendu de motifs; l’application classe et dédoublonne
Fusion protégée de la configuration du runtime	GET/PUT avec révision; au plus trois tentatives, seules les réponses 412 sont réessayées	Même fusion protégée et remplacement explicite	L’application fournit le plan de contrôle
Information de connexion, santé et diagnostics	Pris en charge; les détails varient selon le SDK	État local du transport authentifié	L’application fournit les diagnostics
Clés enregistrées et reconnexion	Gérées par le SDK, stockage configurable	Gérées par le SDK, stockage configurable	Stockage et tampons gérés par l’appelant

Une intention non reconnue peut précéder une parole retardée. Par défaut, Ask démarre une fenêtre de stabilisation fixe de 250 ms à la première parole non vide, ou une attente vide fixe de cinq secondes au premier événement « handled » ou « soft-miss » sans parole. L’appelant peut modifier ces durées. Les fragments suivants ne relancent pas la stabilisation. Les deux fenêtres sont bornées par l’échéance d’origine de la requête; la parole collectée est retournée à son expiration. Un collecteur de requête attend hive.query.complete ou son échéance. Un refus par politique ou un délai d’expiration explicite de la requête fige immédiatement toute réponse partielle, y compris pendant le retrait d’un envoi. Une reconnexion ne rejoue jamais automatiquement une requête de l’application. Consultez les recettes du runtime et la découverte des intentions.

Limites des plateformes

Chaque SDK est testé sur les environnements d’exécution listés sous Versions prises en charge. Cela n’inclut pas les appareils Android ou Unity, ni toutes les versions Linux de Foundation : Swift sur Linux exige un runtime Foundation qui gère WebSocket, comme le décrit la page Swift. Un résultat local de healthcheck ou de doctor décrit la connexion; il n’indique pas si chaque compétence derrière le hub est en bonne santé.

Sécurité des identifiants d’API

Configurez l’URL finale de l’API : les requêtes du plan de contrôle du SDK refusent les redirections, y compris celles qui renverraient un mot de passe de connexion. Les requêtes authentifiées et les corps de requête exigent HTTPS. Ces appels ne peuvent utiliser HTTP que sur les points de terminaison de développement explicites localhost, 127.0.0.1 et [::1]; un nom d’hôte qui se résout simplement vers une adresse privée ne compte pas. Les URL d’API ne peuvent pas contenir d’information d’utilisateur (userinfo). La connexion par appareil valide les deux URL de vérification avant d’afficher une invite, d’appeler un rappel de navigateur ou d’interroger l’API. Les URL doivent utiliser HTTP(S), inclure un hôte et ne contenir ni userinfo, ni espace brut, ni caractère de contrôle.

Le correctif de sécurité .NET change l’intégration HTTP personnalisée : les appels qui portent des identifiants ne peuvent pas utiliser un HttpClient injecté arbitraire. Utilisez le client géré par le SDK ou l’injection de gestionnaire prise en charge, décrite dans le guide .NET. Conservez les paramètres d’autorité de certification privée quand vous configurez un transport personnalisé.

Comment la connexion est sécurisée

Chaque SDK ouvre une session chiffrée et authentifiée avec le hub avant d’envoyer quoi que ce soit, à l’aide du mot de passe déjà présent dans l’identité de client. Rien de plus n’a besoin d’être provisionné. Une connexion qui ne peut pas être authentifiée est fermée; il n’y a aucun repli non chiffré, et les anciennes versions des SDK ne peuvent pas se connecter aux hubs actuels.

Au premier contact, le SDK enregistre l’identité du hub et la vérifie à chaque connexion suivante; un hub modifié produit donc une erreur plutôt qu’une redirection silencieuse. Gardez les clés enregistrées par le SDK dans un emplacement privé et persistant, et réutilisez-les après un redémarrage; chaque page de SDK nomme l’option. Utilisez une identité de client distincte pour chaque processus client qui s’exécute en même temps. Si un hub signale une identité modifiée, confirmez-la avec la personne propriétaire du hub avant de l’accepter.

Utilisez de nouveaux ID de requête et de query pour chaque opération; un ID de session peut être réutilisé pour une conversation.

Versions prises en charge

Voici les versions actuelles. Les anciennes versions ne peuvent pas se connecter aux hubs actuels : mettez d’abord à jour.

Consommateur	Version de paquet prise en charge	Registre et environnement d’exécution
SDK Python	thalovant 0.9.7	PyPI; Python 3.10 ou plus récent
SDK Node.js	@thalovant/sdk 0.9.9	npm; Node.js 20 ou plus récent, ou un paquet de navigateur pris en charge
SDK Go	github.com/thalovant/thalovant-go-sdk v0.13.0	Module Go public; Go 1.26 ou plus récent
SDK Rust	thalovant 0.15.0	crates.io; Rust 1.88 ou plus récent
SDK Kotlin	com.thalovant:thalovant-sdk 0.9.0	Maven Central; JVM 17 ou une chaîne d’outils Android compatible
SDK Swift	thalovant-swift-sdk 0.11.0	Swift Package Manager; Swift 5.10 ou plus récent; voir l’exigence d’environnement Linux
SDK .NET	Thalovant.Sdk 0.9.5	NuGet; net8.0 et netstandard2.1; Unity exige un magasin d’état privé explicite
Bibliothèque C embarquée	thalovant-embedded-c v0.8.0	Étiquette Git immuable et archives de version; C99, transport et tampons gérés par l’appelant
Serveur MCP	@thalovant/mcp-server 0.6.3	npm, GHCR et le registre MCP; bâti sur le SDK Node 0.9.1

Les outils runtime de MCP ouvrent les connexions aux hubs au moyen du SDK Node, par WSS, par HTTPS ou par MQTT sur TLS. Les options stdio et Streamable HTTP du serveur MCP décrivent comment un agent appelle les outils MCP; elles sont distinctes du protocole de hub choisi.

Tous les appels au plan de contrôle passent par la frontière rétrocompatible /api/v1. Les champs ajoutés côté serveur sont sans danger pour les anciens SDK, parce que les clients ignorent les champs qu’ils ne comprennent pas. Un client qui a besoin d’une fonctionnalité nouvellement ajoutée doit utiliser la version minimale indiquée dans la note de version de cette fonctionnalité.

Le serveur MCP est bâti sur le SDK Node. Il est publié après la version du SDK dont il a besoin, avec des métadonnées npm, OCI et du registre MCP alignées. Le tableau ci-dessus donne la paire actuelle.

Les SDK dotés d’un plan de contrôle permettent de se connecter sans mot de passe au moyen de login_with_browser et de ses équivalents natifs dans chaque langage. Chaque guide de langage documente aussi l’authentification directe par jeton d’API. Consultez Se connecter sans mot de passe.

Les SDK dotés d’un plan de contrôle peuvent aussi créer des hubs, des groupes de runtime et des installations de compétences depuis le code. Chaque SDK doté d’un plan de contrôle offre la même surface de provisionnement et de découverte des compétences, et le serveur MCP l’expose sous forme d’outils. Consultez Provisionner des hubs.

L’inventaire des intentions du hub, qui liste ce qu’on peut demander au hub par la propre session du client, se trouve dans chaque SDK publié. Le tableau ci-dessous indique la première version pour chaque SDK. Consultez Que peut-on demander à mon hub?.

SDK	Première version avec l’inventaire
Python	thalovant 0.4.36
Node.js	@thalovant/sdk 0.2.38
Go	github.com/thalovant/thalovant-go-sdk v0.3.13
Rust	thalovant 0.3.0
Kotlin	com.thalovant:thalovant-sdk 0.1.8
Swift	thalovant-swift-sdk 0.1.8
.NET	Thalovant.Sdk 0.1.12
Embedded C	thalovant-embedded-c v0.2.0

Dans la première version de plusieurs portages, un hub qui acceptait la liste et y répondait par une erreur était lu comme un hub vide. Les premières versions qui signalent plutôt une erreur sont : Python 0.4.40, Node.js 0.2.39, Go v0.3.14, Rust 0.3.1, Kotlin 0.1.8, Swift 0.1.9, .NET 0.1.13 et C embarqué v0.3.0.

Attention

Les artefacts de paquet et les étiquettes Git sont immuables. Si une version est retirée, utilisez la version de remplacement indiquée dans les notes de version au lieu d’épingler un artefact dépublié ou réécrit.

Comment fonctionne l’accès par SDK

1. Découvrez un hub. La découverte des hubs publics fonctionne avant la connexion.
2. Connectez-vous pour les actions privées de l’API. La création d’identités de client exige l’accès à l’API sur l’espace de travail. Utilisez une connexion par mot de passe, une connexion par appareil approuvée dans le navigateur ou un jeton d’API à portée limitée.
3. Créez une identité de client. Le SDK conserve l’identité retournée localement ou dans votre magasin de secrets.
4. Connectez-vous au hub. Le trafic du runtime va directement au point de terminaison du hub.
5. Envoyez une requête. Commencez par un appel ask, puis ajoutez des sessions, du contexte, des actions ou une sortie enrichie.

Origines de navigateur

Les applications de navigateur hébergées sur des domaines qui appartiennent au client ont besoin d’une origine SDK approuvée avant que leurs appels inter-origines au SDK ou à l’API soient acceptés.

L’approbation porte sur l’origine exacte et ne transmet aucun identifiant. Elle permet les requêtes d’une origine examinée, mais elle ne permet pas d’exposer dans les paquets de navigateur les témoins (cookies) du tableau de bord, les en-têtes de rafraîchissement de session, les liens de configuration ni les identités de client de longue durée.

Protocoles

Protocole	Utilisez-le quand	Remarques
WSS	Vous voulez le chemin temps réel public par défaut.	Meilleur premier choix pour les agents et les clients qui peuvent écouter des événements. Pris en charge par tous les SDK clients; le C embarqué exige votre transport.
HTTPS	Vous voulez des appels requête-réponse, des vérifications de santé, des outils en ligne de commande ou des tâches.	Doit être activé sur le hub avant que les clients publics puissent l’utiliser. Python, Node.js, Go et Rust seulement.
MQTT sur TLS	Vous voulez du trafic d’appareil ou de périphérie qui passe par un courtier (broker).	Exige des identifiants de courtier propres à chaque client et l’accès aux sujets (topics). Python, Node.js, Go et Rust seulement; Node.js le prend en charge hors des navigateurs.

Astuce

Commencez par WSS. N’ajoutez HTTPS ou MQTT que si le client a une vraie raison d’utiliser ce chemin.

Ce qui doit rester secret

Chaque identité de client est secrète. Conservez-la comme un mot de passe.

Ne mettez pas de fichiers d’identité, de clés d’accès, de mots de passe, de mots de passe de courtier, de liens de configuration ni de clés cryptographiques dans des paquets de navigateur, des dépôts publics, des captures d’écran, des journaux ou des billets de soutien.

Liste de vérification pour la production

Vérification	Bon choix par défaut
URL de base de l’API	https://api.thalovant.com
Premier protocole du runtime	WSS
Utilisation dans un navigateur	Utilisez les origines SDK pour les domaines de navigateur examinés. Gardez les secrets sur un serveur.
Stockage de l’identité	Utilisez un gestionnaire de secrets, un secret de CI, un fichier secret monté ou ~/.config/thalovant/config.yaml avec le mode 600.
MQTT	Utilisez mqtts://, des identifiants propres à chaque client et des sujets gérés par le SDK.
Clés enregistrées	Gardez les clés enregistrées par le SDK dans un emplacement privé et persistant d’un redémarrage à l’autre. Utilisez une identité distincte pour chaque processus client qui s’exécute en même temps.
Rotation	Si un hub signale une identité modifiée, confirmez-la avec la personne propriétaire du hub avant de l’accepter. Remplacez les identifiants d’un client en provisionnant une nouvelle identité.
Journaux	Masquez le JSON d’identité, les mots de passe de courtier, les jetons d’API et les clés cryptographiques.

Couverture de la gestion des compétences

Python, Node, Go, Rust, Kotlin, .NET et Swift offrent, adressées au hub, la liste, l’historique, l’installation, la mise à jour et le retrait des compétences, en plus des utilitaires existants d’ajout et de retrait de compétences dans un groupe de runtime et des utilitaires de configuration et de publication du hub et du runtime. MCP expose les outils correspondants. Embedded C reste une bibliothèque de protocole sans client de provisionnement.

Les appels de compétences adressés au hub modifient le groupe de runtime rattaché et touchent donc tous les hubs qui le partagent. Consultez la page du langage pour l’attente et la reprise des opérations.

Sessions gérées et inventaires présentables

Python, Node, Go, Rust, Kotlin, .NET et Swift offrent des sessions de hub gérées, des inventaires de compétences et d’intentions présentables, et des caches privés facultatifs. Les sessions conservent les abonnements quand la connexion est remplacée et ne rejouent jamais automatiquement une action acceptée. Le code de l’application gère les budgets de la fabrique de connexions et l’ordonnancement des sondes. Le guide Python et chaque guide de langage expliquent l’API et les détails de migration.

MCP expose le modèle de présentation dans son outil d’inventaire, tout en gardant séparé le bail d’identité de chaque appel. Embedded C conserve son noyau indépendant du transport, à tampons fournis par l’appelant; les sessions gérées, les caches sur disque et les bases de données de paramètres régionaux relèvent de l’application hôte. La prise en charge des transports reste celle décrite plus haut.

Métadonnées de revendication des réponses

Les versions actuelles des SDK exposent les ID ordonnés de pipeline et de compétence, ainsi qu’un résultat de revendication indicatif. Les clients peuvent ainsi distinguer une réponse de repli seulement d’une intention reconnue, sans rejeter la réponse. Les anciens hubs qui répondent avec succès sans estampilles restent compatibles. Consultez la section sur les revendications de réponse de chaque SDK pour son API idiomatique; le C embarqué garde un stockage géré par l’appelant, et MCP expose les champs dans son résumé du runtime.

Listes de phrases adaptées aux paramètres régionaux

Les listes de phrases adaptées aux paramètres régionaux se trouvent dans chaque SDK géré et dans MCP; Python a besoin de son extra listing. Tous embarquent les mêmes règles linguistiques. Les exemples bruts restent le comportement par défaut, et le rendu en phrases y ajoute des échantillons régionaux, les majuscules et la ponctuation. Embedded C conserve son utilitaire de motifs à tampon fourni par l’appelant et n’embarque ni données régionales ni tables de correspondance régionale.

Et ensuite

Si vous connaissez déjà votre langage, ouvrez la page de son SDK.

Utilisez Fonctions des SDK quand vous avez besoin des noms de méthodes dans les différents langages. Utilisez Connexion MQTT quand le client se connecte par le courtier.