Fonctions des SDK

Exemples à copier-coller des SDK Thalovant pour le plan de contrôle, les identités, les requêtes au runtime, les événements et le contexte.

View as Markdown Open in Claude Open in ChatGPT

Consultez cette page quand vous voulez bâtir avec le SDK, pas mémoriser le nom de chaque méthode.

Commencez par l’exemple rapide, puis copiez la recette la plus proche de votre tâche. Chaque recette montre la même idée en Python, Node.js, Go et Rust, là où les SDK l’offrent. Les recettes « Démarrage rapide », « Se connecter » et « Créer une identité de client » montrent aussi Kotlin, Swift et C#. Pour l’ensemble des fonctions de ces SDK, consultez les pages des SDK Kotlin, Swift et .NET.

Trouver l’appel dont vous avez besoin

Chaque appel est montré dans chaque langage qui l’offre : vous pouvez donc comparer une opération d’un SDK à l’autre sans ouvrir cinq pages.

Si vous voulez…	Ouvrez
Obtenir un client et vous connecter	Se connecter et créer un client
Consulter ou créer des hubs	Trouver et provisionner des hubs
Émettre une identité de client	Identités de client et protocoles
Poser une question à un hub	Parler à un hub
Écouter des événements ou déboguer	Événements, contexte et diagnostics

Démarrage rapide

Cet exemple se connecte, crée une identité de client pour un hub, établit la connexion, envoie une requête et affiche la réponse.

from thalovant import ThalovantClient, ThalovantControlPlane

api = ThalovantControlPlane()
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();
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()
  api := thalovant.NewDefaultControlPlane("")

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

  result, err := api.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 api = ControlPlane::default();
    api.login("[email protected]", "password", None).await?;

    let result = api
        .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();

Les clients Kotlin, Swift et C# se connectent uniquement par WSS; ils ne prennent donc aucun argument de protocole ici. Ces exemples exigent les versions actuelles des SDK compatibles avec la v3.

Résultat attendu :

Why did the hub keep good logs? It wanted every punchline to be traceable.

Choisir la bonne recette

Plan de contrôle

Découvrez des hubs et créez des identités de client.

Identité

Chargez des identifiants enregistrés et choisissez un protocole.

Client du runtime

Connectez-vous, posez des questions, émettez des événements et envoyez des entrées structurées.

Événements et contexte

Écoutez les événements du hub et joignez des métadonnées de session.

Référence rapide

Servez-vous de ce tableau seulement quand vous connaissez déjà la tâche et qu’il vous faut le nom propre à un langage.

Plan de contrôle

Tâche	Python	Node.js	Go	Rust
Créer un client d’API	`ThalovantControlPlane()`	`new ThalovantControlPlane()`	`NewDefaultControlPlane(token)`	`ControlPlane::default()`
Se connecter	`login(email, password)`	`login(email, password)`	`Login(ctx, email, password, scope)`	`login(email, password, scope)`
Se connecter avec l’authentification multifacteur (AMF)	`login(..., otp_code=..., recovery_code=...)`	`login(..., { otpCode, recoveryCode })`	`LoginWithOptions(ctx, email, password, options)`	`login_with_options(email, password, options)`
Se connecter sans mot de passe	`login_with_browser(...)`	`loginWithBrowser(options)`	`LoginWithBrowser(ctx, options)`	`login_with_browser(options)`
Utiliser un jeton d’API	`ThalovantControlPlane(access_token=...)`	`new ThalovantControlPlane(url, { accessToken })`	`NewDefaultControlPlane(token)`	`ControlPlane::with_access_token(token)`
Lister les hubs publics	`list_public_hubs(...)`	`listPublicHubs(...)`	`ListPublicHubs(ctx, limit, cursor)`	`list_public_hubs(limit, cursor)`
Obtenir un hub public	`get_public_hub(ref)`	`getPublicHub(ref)`	`GetPublicHub(ctx, ref)`	`get_public_hub(ref)`
Lister les hubs visibles	`list_hubs(...)`	`listHubs(...)`	`ListHubs(ctx, limit, cursor, ownerID)`	`list_hubs(limit, cursor, owner_id)`
Obtenir un hub	`get_hub(hub_id)`	`getHub(hubId)`	`GetHub(ctx, hubID)`	`get_hub(hub_id)`
Obtenir une opération	`get_operation(operation_id)`	`getOperation(operationId)`	`GetOperation(ctx, operationID)`	`get_operation(operation_id)`
Créer une identité	`create_client_identity(...)`	`createClientIdentity(...)`	`CreateClientIdentityForHubID(...)`	`create_client_identity_for_hub_id(...)`
Lister les compétences du hub	`list_hub_skills(hub_id)`	`listHubSkills(hubId)`	`ListHubSkills(ctx, hubID)`	`list_hub_skills(hub_id)`
Lister l’historique des compétences du hub	`list_hub_skill_history(hub_id, limit=50)`	`listHubSkillHistory(hubId, { limit: 50 })`	`ListHubSkillHistory(ctx, hubID, 50)`	`list_hub_skill_history(hub_id, 50)`
Installer une compétence sur le hub	`install_hub_skill(hub_id, skill, version=, wait=)`	`installHubSkill(hubId, skill, { version, wait })`	`InstallHubSkill(ctx, hubID, skill, version, options)`	`install_hub_skill(hub_id, skill, version, options)`
Mettre à jour une compétence du hub	`update_hub_skill(hub_id, skill, version=, wait=)`	`updateHubSkill(hubId, skill, { version, wait })`	`UpdateHubSkill(ctx, hubID, skill, version, options)`	`update_hub_skill(hub_id, skill, version, options)`
Retirer une compétence du hub	`remove_hub_skill(hub_id, skill, wait=)`	`removeHubSkill(hubId, skill, { wait })`	`RemoveHubSkill(ctx, hubID, skill, options)`	`remove_hub_skill(hub_id, skill, options)`

Les appels de compétences de hub et leur historique sont offerts dans les sept SDK gérés, aux versions actuelles. Les appels de provisionnement ont leur propre tableau de noms à la page Provisionner des hubs.

Identité

Tâche	Python	Node.js	Go	Rust
Charger l’identité depuis la configuration	`ThalovantIdentity.from_config(...)`	`ThalovantIdentity.fromConfig(...)`	`IdentityFromConfig(path, profile)`	`Identity::from_config(profile)`
Charger un fichier d’identité	`ThalovantIdentity.from_file(path)`	`ThalovantIdentity.fromFile(path)`	`IdentityFromFile(path)`	`Identity::from_file(path)`
Charger le client depuis un fichier	`ThalovantClient.from_identity_file(path)`	`ThalovantClient.fromIdentityFile(path)`	`NewClientFromFile(path)`	`Client::from_file(path)`
Charger le client depuis la configuration	`ThalovantClient.from_config(...)`	`ThalovantClient.fromConfig(...)`	`NewClientFromConfig(path, profile)`	`Client::from_config(profile)`
Charger le client depuis l’environnement	`ThalovantClient.from_env()`	`ThalovantClient.fromEnv()`	`NewClientFromEnv()`	`Client::from_env()`
Protocoles activés	`enabled_protocols()`	`enabledProtocols()`	`EnabledProtocols()`	`enabled_protocols()`
Point de terminaison d’un protocole	`endpoint_for(protocol)`	`endpointFor(protocol)`	`EndpointFor(protocol)`	`endpoint_for(protocol)`
Vérifier un protocole	`supports_protocol(protocol)`	`supportsProtocol(protocol)`	`SupportsProtocol(protocol)`	`supports_protocol(protocol)`
Identifiants MQTT	`identity.mqtt`	`identity.mqtt`	`Identity.MQTT`	`identity.mqtt`

Client du runtime

Tâche	Python	Node.js	Go	Rust
Créer un client pour un protocole	`ThalovantClient(identity, protocol="wss")`	`new ThalovantClient(identity, { protocol })`	`NewClientWithOptions(identity, ClientOptions{Protocol: ...})`	`Client::with_protocol(identity, protocol)`
Se connecter	`connect()`	`connect()`	`Connect(ctx)`	`connect()`
Fermer	`close()`	`close()`	`Close(ctx)`	`close()`
État de santé	`healthcheck()`	`healthcheck()`	`Healthcheck()`	`healthcheck()`
Poser une question	`ask(text, ...)`	`ask(text, options)`	`Ask(ctx, text, options)`	`ask(text, options)`
Émettre un événement brut	`emit(event, data, context)`	`emit(event, data, context)`	`Emit(ctx, event, data, context)`	`emit(event, data, context)`
Envoyer un énoncé	`send_utterance(text, ...)`	`sendUtterance(text, options)`	`SendUtterance(ctx, text, options)`	`send_utterance(text, options)`
Envoyer une action	`send_action(payload, ...)`	`sendAction(payload, options)`	`SendAction(ctx, payload, options)`	`send_action(payload, options)`
Envoyer un code	`send_code(value, ...)`	`sendCode(value, options)`	`SendCode(ctx, value, options)`	`send_code(value, options)`
Conversation	`conversation(...)`	`conversation(options)`	`Conversation(options)`	`conversation(options)`
Inventaire des intentions	`intents(languages, ...)`	`intents(languages)`	`Intents(ctx, languages, options)`	`intents(languages, options)`
Lister les intentions	`list_intents(lang, ...)`	`listIntents(lang)`	`ListIntents(ctx, lang, options)`	`list_intents(lang, options)`
Décrire une intention	`describe_intent(skill_id, intent_name, lang, ...)`	`describeIntent(skillId, intentName, lang)`	`DescribeIntent(ctx, skillID, intentName, lang, options)`	`describe_intent(skill_id, intent_name, lang, options)`
Refus de politique	`ThalovantPolicyDeniedError`	`ThalovantPolicyDeniedError`	`PolicyDeniedError`	`ThalovantError::PolicyDenied`

Les rangées sur les intentions sont publiées dans chaque SDK. La page des SDK indique la version dans laquelle chacun les a livrées, et les graphies Kotlin, Swift, .NET et C embarqué se trouvent sur leurs propres pages de SDK.

Événements, contexte et sortie

Tâche	Python	Node.js	Go	Rust
Attendre un événement	`wait_for_event(name, ...)`	`waitForEvent(name, options)`	`WaitForEvent(ctx, name, options)`	`wait_for_event(name, options)`
Diffuser des événements en flux	`listen(name, ...)`	`on(name, handler, options)`	`Listen(ctx, name, options)`	`listen(name, options)`
Diagnostics	`doctor()`	`healthcheck()`	`Healthcheck()`	`healthcheck()`
Construire le contexte	`build_client_context(...)`	`buildClientContext(...)`	`BuildClientContext(...)`	`build_client_context(...)`
Texte de la réponse	`reply.text`	`reply.text`	`reply.Text`	`reply.text`
Éléments d’affichage	`reply.display_items(...)`	`reply.displayItems(...)`	`reply.DisplayItems(...)`	`reply.display_items(...)`
Texte de l’événement	`event.text`	`event.text`	`event.Text()`	`event.text()`

Pages connexes

Les SDKInstallez un SDK et faites la première requête.

Provisionner des hubsPortées, restrictions de forfait, etags et erreurs de provisionnement.

Sessions et contexteTransmettez des métadonnées stables d'une requête à l'autre.

Événements et sortieRéponses, éléments d'affichage et flux d'événements.

ActionsBoutons, lectures optiques, codes et commandes structurées.

MQTTIdentifiants du courtier (broker), TLS et sujets (topics).

Les fonctions d’aide pour les compétences adressées à un hub sont maintenant offertes dans les sept SDK gérés, y compris l’historique et l’attente facultative des opérations. Elles agissent sur le groupe de runtime rattaché : chaque hub qui le partage est touché. Consultez la référence de chaque SDK pour les noms de ses méthodes. Le C embarqué n’a pas de client HTTP de provisionnement.