Documentation pour développeurs

Créez une compétence vocale, ou connectez votre application à un hub Thalovant avec un SDK.

View as Markdown Open in Claude Open in ChatGPT

Vous pouvez bâtir deux choses ici, et ce sont deux métiers différents.

Une compétence tourne sur le hub et répond à un type de demande précis : c’est le code derrière « quel temps fait-il? ». Un SDK est une bibliothèque que votre propre application utilise pour envoyer des demandes à un hub et lire les réponses.

Apprenez-lui quelque chose de nouveauCréez Pocket Quiz, un petit jeu parlé en anglais et en français. Il tourne sur votre ordinateur, sans hub.

Parlez-lui à partir de votre codeChoisissez un langage, installez le SDK et faites votre première requête.

Votre première requête Nouveau

Choisissez l’onglet de votre langage. Chaque SDK fait les quatre mêmes choses : se connecter, créer une identité de client sur un hub, ouvrir une connexion WSS, demander. Le texte de la réponse est ce que le hub aurait dit à voix haute.

from thalovant import ThalovantClient, ThalovantControlPlane

api = ThalovantControlPlane()

hub = api.list_public_hubs(limit=1)["data"][0]
print(hub["title"], hub["slug"])

api.login("[email protected]", "password")

result = api.create_client_identity(
    hub["id"],
    name="python-demo-client",
    preferred_protocols=("wss", "https", "mqtt"),
)

with ThalovantClient(result.identity, protocol="wss") as client:
    reply = client.ask("Tell me a short clean joke.")
    print(reply.text)

import { ThalovantClient, ThalovantControlPlane } from "@thalovant/sdk";

const api = new ThalovantControlPlane();

const publicHubs = await api.listPublicHubs({ limit: 1 });
const [hub] = publicHubs.data as Array<{ id: string; slug: string; title: string }>;
console.log(hub.title, hub.slug);

await api.login("[email protected]", "password");

const result = await api.createClientIdentity(hub.id, {
  name: "node-demo-client",
  preferredProtocols: ["wss", "https", "mqtt"],
});

const client = new ThalovantClient(result.identity, { protocol: "wss" });
try {
  const reply = await client.ask("Tell me a short clean joke.");
  console.log(reply.text);
} finally {
  await client.close();
}

package main

import (
  "context"
  "fmt"
  "log"

  thalovant "github.com/thalovant/thalovant-go-sdk"
)

func main() {
  ctx := context.Background()
  control := thalovant.NewDefaultControlPlane("")

  _, err := control.Login(ctx, "[email protected]", "password", "")
  if err != nil {
    log.Fatal(err)
  }

  result, err := control.CreateClientIdentityForHubID(ctx, "hub-id", thalovant.BootstrapIdentityOptions{
    Name: "go-demo-client",
    PreferredProtocols: []thalovant.HubProtocol{
      thalovant.ProtocolWSS,
      thalovant.ProtocolHTTPS,
      thalovant.ProtocolMQTT,
    },
  })
  if err != nil {
    log.Fatal(err)
  }

  client, err := thalovant.NewClientWithOptions(result.Identity, thalovant.ClientOptions{
    Protocol: thalovant.ProtocolWSS,
  })
  if err != nil {
    log.Fatal(err)
  }
  defer client.Close(ctx)

  reply, err := client.Ask(ctx, "Tell me a short clean joke.", thalovant.RequestOptions{})
  if err != nil {
    log.Fatal(err)
  }

  fmt.Println(reply.Text)
}

use thalovant::{
    BootstrapIdentityOptions, Client, ControlPlane, HubProtocol, RequestOptions,
};

#[tokio::main]
async fn main() -> thalovant::Result<()> {
    let mut control = ControlPlane::default();

    control.login("[email protected]", "password", None).await?;

    let result = control
        .create_client_identity_for_hub_id(
            "hub-id",
            BootstrapIdentityOptions {
                name: "rust-demo-client".into(),
                preferred_protocols: vec![HubProtocol::Wss, HubProtocol::Https, HubProtocol::Mqtt],
                ..Default::default()
            },
        )
        .await?;

    let client = Client::with_protocol(result.identity.clone(), HubProtocol::Wss)?;
    let reply = client
        .ask("Tell me a short clean joke.", RequestOptions::default())
        .await;
    let closed = client.close().await;
    let reply = reply?;
    closed?;
    println!("{}", reply.text);

    Ok(())
}

import com.thalovant.sdk.CreateClientIdentityOptions
import com.thalovant.sdk.ThalovantClient
import com.thalovant.sdk.ThalovantControlPlane
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val api = ThalovantControlPlane()

    api.login("[email protected]", "password")

    val result = api.createClientIdentity(
        "hub-id",
        CreateClientIdentityOptions(name = "kotlin-demo-client"),
    )

    val client = ThalovantClient(result.identity)
    try {
        val reply = client.ask("Tell me a short clean joke.")
        println(reply.text)
    } finally {
        client.close()
    }
}

import ThalovantSDK

let api = ThalovantControlPlane()

try await api.login(email: "[email protected]", password: "password")

let result = try await api.createClientIdentity(
    hubId: "hub-id",
    options: CreateClientIdentityOptions(name: "swift-demo-client")
)

let client = try ThalovantClient(identity: result.identity)
do {
    try await client.connect()
    let reply = try await client.ask("Tell me a short clean joke.")
    print(reply.text)
    await client.close()
} catch {
    await client.close()
    throw error
}

using Thalovant;

var api = new ThalovantControlPlane();

await api.LoginAsync("[email protected]", "password");

var result = await api.CreateClientIdentityAsync(
    "hub-id",
    new CreateClientIdentityOptions("dotnet-demo-client"));

using var client = new ThalovantClient(result.Identity);
await client.ConnectAsync();
var reply = await client.AskAsync("Tell me a short clean joke.");
Console.WriteLine(reply.Text);
await client.CloseAsync();

Chaque page de SDK explique les morceaux : où l’identité est conservée, quels protocoles le hub accepte, quoi passer comme contexte et comment écouter les événements.

Créer une compétence

Commencez par le tutoriel Pocket Quiz. Vous pouvez tout écrire et tout tester sur votre ordinateur avant même d’avoir un hub. Il explique à quoi sert chaque fichier et vous dit ce que vous devriez voir après chaque étape.

Quand ses vérifications passent, Ajouter votre propre compétence l’installe sur un hub de test. Posez-lui ensuite une question à voix haute, essayez une question de suivi et vérifiez que « stop » met fin à la partie.

Écrire une compétence est la référence que vous ouvrirez ensuite : fonctions utilitaires, règles de conversation, tests, empaquetage. Garder votre compétence réactive traite de la mise en cache, des appels de service bornés et du rafraîchissement en arrière-plan.

Connecter votre application

Thalovant crée l’identité du client et sa règle d’accès; votre SDK utilise cette identité pour se connecter directement au hub.

Choisissez un hub. Un hub public est ce qu’il y a de plus simple pour tester.
Créez une identité de client. Il faut pour cela un accès à l’API dans l’espace de travail.
Installez un SDK. Prenez le langage dans lequel votre application est déjà écrite.
Connectez-vous en WSS. C’est le transport par défaut, et tous les SDK le prennent en charge.
N’ajoutez HTTPS ou MQTT que si vous en avez besoin. Python, Node.js, Go et Rust prennent en charge les deux une fois que le hub les active. Kotlin, Swift et .NET ne font que du WSS; le C embarqué utilise le transport que votre micrologiciel a déjà.
Demandez une origine SDK si vous êtes dans un navigateur. Un domaine qui vous appartient doit être approuvé avant que les appels d’une origine à une autre soient acceptés.
Ajoutez le contexte en dernier. Les métadonnées d’utilisateur, d’appareil, de session et de trace valent la peine une fois que la première requête simple fonctionne.

PythonAgents, outils, services, carnets et tests.

Node.jsServeurs, scripts, robots et agents TypeScript.

GoServices, passerelles, outils en ligne de commande et petits agents.

RustClients stricts, travail embarqué et services fiables.

KotlinServices JVM et clients Android.

SwiftApplications Apple et clients Linux compatibles.

.NETServices C#, applications de bureau et clients Unity.

C embarquéMicrologiciel dont l'application gère le transport et le stockage.

À propos de l’API REST

Tout ici passe par un SDK, et c’est voulu. Les SDK sont la surface prise en charge : ils s’occupent de la session chiffrée et authentifiée, des clés enregistrées dont une reconnexion a besoin, de la corrélation des requêtes, et des nouvelles tentatives et annulations qu’un client HTTP fait maison doit réussir tout seul.

Il n’y a pas de référence REST publiée. Si vous en cherchez une, voilà pourquoi : ce n’est pas un oubli. Prenez le SDK le plus proche de votre langage, même le C embarqué, qui apporte son propre transport et vous laisse les sockets.

Connecter un agent

Le serveur MCP expose les hubs à Claude, Codex, Cursor et d’autres agents sous forme d’outils. Un agent peut ainsi poser une question à un hub ou gérer des compétences sans que vous ayez à écrire de client.

Tout le reste

Fonctions des SDKChaque appel, nommé dans chaque langage.

Que peut-on demander à mon hub?Lister les intentions d'un hub et leurs phrases.

Sessions et contexteUtilisateurs, appareils, flux et traces.

Événements et sortieTexte, parole, éléments d'affichage et flux d'événements.

ActionsBoutons, lectures, codes et commandes structurées.

Points de terminaison du hubWSS, HTTPS et MQTT sur TLS.

Fichiers d'identitéIdentifiants, points de terminaison et réglages du courtier.

MQTTIdentifiants du courtier, TLS, sujets et utilisation des SDK.

Origines SDKDomaines de navigateur approuvés pour les appels SDK d'une origine à une autre.

Provisionner des hubsCréer des hubs et des groupes de runtime à partir du code.

OpérationsSuivre une commande, d'acceptée à prête.

Flux d'étatReprendre des événements d'état ordonnés à partir d'un curseur.