Démarrage rapide

Un premier échange complet avec le SDK, depuis votre backend. Pour un hôte comme Claude Desktop ou Cursor, suivez plutôt Connecter le MCP.

1. Préparer votre domaine

Vous avez besoin d’un domaine publié et d’une clé API avec la permission runtime. Si vous les avez déjà, passez directement à l’installation.

Gardez la clé côté serveur. Ne la placez jamais dans le navigateur, une application mobile, un dépôt public ou un prompt.

2. Installer et exécuter

Choisissez votre langage. Le programme affiche la première question, attend votre réponse, puis affiche la décision suivante et l’état des dimensions. Pour cet essai en terminal, saisissez du texte pour une question ouverte, ou un libellé exact pour un choix.

Python
TypeScript

Python 3.11 ou supérieur. Avec uv, placez-vous dans votre projet ; s’il n’est pas encore initialisé, lancez uv init --python 3.11. Si vous préférez pip, utilisez un environnement virtuel activé.

uv add zelinqa

python -m pip install zelinqa

Configurez ensuite la clé dans votre terminal :

export ZELINQA_API_KEY="VOTRE_CLE_RUNTIME"

Enregistrez ce code dans demo.py, puis lancez uv run python demo.py (ou python demo.py avec pip, dans l’environnement activé). Le client Python lit automatiquement la variable d’environnement.

from zelinqa import ZelinqaClient

with ZelinqaClient() as client:
    session = client.start_session(client_reference="demo-001")
    decision = session.next()

    if decision.action == "ask":
        question = decision.candidates[0]
        print(question.text)
        for choice in question.choices:
            print(f"- {choice.label}")

        reply = input("> ")
        if not reply.strip():
            decision = session.answer(outcome="asked_no_answer")
        elif question.choices:
            decision = session.answer(choice_labels=[reply])
        else:
            decision = session.answer(reply)

        print(decision.action, decision.warnings)
        for dimension in decision.progress.dimensions:
            print(dimension.id, dimension.effective_status)
        if decision.action == "ask":
            print(decision.candidates[0].text)

Node.js 22 ou supérieur. Installez le paquet et configurez la clé dans votre terminal :

npm install @zelinqa/sdk
export ZELINQA_API_KEY="VOTRE_CLE_RUNTIME"

Ce code est aussi du JavaScript exécutable : enregistrez-le dans demo.mjs, puis lancez node demo.mjs. Le client TypeScript reçoit explicitement la clé dans son constructeur.

import { createInterface } from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { ZelinqaClient } from "@zelinqa/sdk";

const client = new ZelinqaClient({ apiKey: process.env.ZELINQA_API_KEY ?? "" });
const session = await client.startSession({ client_reference: "demo-001" });
let decision = await session.next();
const question = decision.candidates[0];

if (decision.action === "ask" && question !== undefined) {
  console.log(question.text);
  for (const choice of question.choices) {
    console.log(`- ${choice.label}`);
  }

  const input = createInterface({ input: stdin, output: stdout });
  try {
    const reply = await input.question("> ");
    if (!reply.trim()) {
      decision = await session.answer({ outcome: "asked_no_answer" });
    } else if (question.choices.length > 0) {
      decision = await session.answer({ choiceLabels: [reply] });
    } else {
      decision = await session.answer({ userText: reply });
    }
    console.log(decision.action, decision.warnings);
    for (const dimension of decision.progress.dimensions) {
      console.log(dimension.id, dimension.effective_status);
    }
    if (decision.action === "ask") {
      console.log(decision.candidates[0]?.text);
    }
  } finally {
    input.close();
  }
}

3. Comprendre le résultat

La première question vient de votre domaine publié : son texte dépend de votre configuration.
answer(...) enregistre la réponse et renvoie déjà la prochaine décision. Ne rappelez pas next() pour obtenir cette même suite.
progress.dimensions indique l’état de chaque dimension, par exemple in_progress ou covered.
warnings peut signaler une limite de tours atteinte ou une qualification réussie. Votre application décide de continuer ou non.
action: "stop" signifie qu’aucune question n’est disponible. N’accédez alors pas à la première candidate.

Le SDK gère les identifiants de question, de décision et la version d’état. Votre code métier n’a pas à les construire. Conservez seulement session.id côté backend pour pouvoir reprendre après un redémarrage.

Et ensuite ?

Une conversation complète

Un chatbot en terminal, les choix, la progression et le relais à votre agent.

Réponses et contexte

Choix multiples, réponse semi-ouverte, refus et données déjà connues.

Progression et qualification

Comprendre les dimensions et les niveaux Essentiel, Équilibré et Approfondi.

Référence SDK

Clients, permissions, méthodes et configuration avancée.

Commencer

Guides

Références

Ressources

Démarrage rapide

1. Préparer votre domaine

2. Installer et exécuter

3. Comprendre le résultat

Et ensuite ?

Une conversation complète

Réponses et contexte

Progression et qualification

Référence SDK

​1. Préparer votre domaine

​2. Installer et exécuter

​3. Comprendre le résultat

​Et ensuite ?

Une conversation complète

Réponses et contexte

Progression et qualification

Référence SDK

1. Préparer votre domaine

2. Installer et exécuter

3. Comprendre le résultat

Et ensuite ?