Skip to main content
Les SDK officiels appellent la même API REST. Ils gèrent les identifiants de décision et la version d’état pendant une conversation. Votre application conserve seulement l’identifiant de session si elle veut reprendre après un redémarrage.

Démarrage rapide — Python et TypeScript

Installez le SDK et réalisez votre premier échange dans le langage de votre choix.

​
Mise à jour et versions

Les SDK installés ne se mettent pas à jour automatiquement. Exécutez les commandes depuis votre projet, puis redémarrez ou redéployez votre application.
Dans un projet uv qui utilise déjà zelinqa, mettez à jour le verrouillage et l’environnement, puis affichez la version installée :
La mise à jour respecte la contrainte de pyproject.toml. Si elle fixe une version exacte, changez-la explicitement. Par exemple, pour choisir 1.0.1 :
Si vous utilisez pip plutôt que uv, dans l’environnement virtuel de votre application :
Avec pip, mettez aussi à jour votre fichier de dépendances ou votre verrouillage selon votre outil : cette commande ne les réécrit pas.

​
Vérifier avant de déployer

  1. Lisez le changelog et les changements du SDK.
  2. Testez une conversation complète sur un domaine de démonstration : démarrage, réponse libre ou choix selon votre usage, progression et arrêt. Testez aussi la reprise et les erreurs que votre application gère.
  3. Versionnez le manifeste et le verrouillage (pyproject.toml + uv.lock, ou package.json + package-lock.json) pour déployer les mêmes dépendances que celles testées. En production, évitez une mise à jour non contrôlée vers la dernière version.
Les commandes de version ci-dessus n’appellent pas l’API Zelinqa ; une conversation de test utilise votre clé et vos quotas. Mettre à jour le SDK ne republie pas votre domaine et ne change pas la version de configuration attachée à une session existante. Le MCP a son propre environnement et sa propre mise à jour.

​
Clés et permissions

Créez une clé dans Zelinqa Studio pour un domaine publié. Une clé est liée à ce domaine et à des permissions : La clé runtime ne donne pas accès à la configuration. Vous pouvez créer plusieurs clés pour un même domaine, avec les seules permissions utiles à chaque service. Pour plusieurs domaines, utilisez une clé par domaine.
Ces clients s’exécutent côté serveur. Ne placez jamais une clé API dans un navigateur, une application mobile, un dépôt public ou une conversation avec un modèle.
En Python, ZelinqaClient() lit ZELINQA_API_KEY. Pour la configuration, ZelinqaConfigurationClient() cherche d’abord ZELINQA_CONFIGURATION_API_KEY, puis ZELINQA_API_KEY. En TypeScript, fournissez explicitement apiKey au constructeur. L’URL par défaut est https://api.zelinqa.ai ; une URL HTTP locale peut être passée pour le développement, pas pour une clé réelle sur un réseau non fiable.

​
Cycle d’une conversation

  1. start_session / startSession crée une session sur la version publiée active.
  2. session.next() renvoie la première décision, sans réponse précédente.
  3. Votre application affiche candidates[0].text et recueille la réponse réelle.
  4. session.answer(...) rattache cette réponse à la décision en attente et renvoie la décision suivante. Ne rappelez pas next() juste pour obtenir cette question.
  5. session.refresh() relit l’état ; session.submit_feedback(...) enregistre un résultat métier réellement observé.
Pour une question ouverte, envoyez les mots de la personne (user_text / userText). Pour une question fermée ou semi-ouverte, choice_labels / choiceLabels accepte les libellés exacts affichés ; les identifiants des choix sont résolus localement. Une semi-ouverte peut ajouter free_text / freeText. Pour une absence de réponse ou un refus réels, utilisez asked_no_answer ou refused sans texte. Les choix seuls et ces deux issues ne nécessitent pas d’analyse par modèle ; le texte libre peut en nécessiter une. Le handle conserve state_version. Utilisez-le séquentiellement : deux mutations concurrentes de la même session peuvent produire un conflit. Après une interruption ou un ZelinqaStateVersionConflictError, relisez l’état et réconciliez la réponse avant de réessayer ; ne la rejouez pas à l’aveugle. Une session déjà ouverte reste attachée à sa version publiée même après une nouvelle publication.

​
Autres opérations

Une publication est asynchrone : vérifiez le statut terminal de compilation avant de considérer la nouvelle version active. Les erreurs HTTP ont des classes typées, notamment pour l’authentification, les permissions, les données invalides, les conflits et la limitation de débit. Les SDK réessaient les erreurs transitoires avec une clé d’idempotence stable par appel logique ; un conflit métier n’est pas masqué. Pour les options, les modèles de réponse et les exemples de configuration, consultez les guides Python et TypeScript, ou la référence API.