> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelinqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Démarrage rapide

> Obtenez une question, envoyez une réponse et suivez vos dimensions avec Python ou TypeScript.

**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](/fr/quickstart/mcp).

## 1. Préparer votre domaine

Vous avez besoin d'un [domaine publié](/fr/quickstart/configure-domain) et d'une [clé API avec la permission runtime](/fr/quickstart/generate-api-key). Si vous les avez déjà, passez directement à l'installation.

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

## 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.

<Tabs>
  <Tab title="Python">
    Python 3.11 ou supérieur. Avec [uv](https://docs.astral.sh/uv/guides/projects/), 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é.

    <CodeGroup>
      ```bash uv theme={null}
      uv add zelinqa
      ```

      ```bash pip theme={null}
      python -m pip install zelinqa
      ```
    </CodeGroup>

    Configurez ensuite la clé dans votre terminal :

    ```bash theme={null}
    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.

    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="TypeScript">
    Node.js 22 ou supérieur. Installez le paquet et configurez la clé dans votre terminal :

    ```bash theme={null}
    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.

    ```ts theme={null}
    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();
      }
    }
    ```
  </Tab>
</Tabs>

## 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 ?

<CardGroup cols={2}>
  <Card title="Une conversation complète" icon="comments" href="/fr/guides/complete-conversation">Un chatbot en terminal, les choix, la progression et le relais à votre agent.</Card>
  <Card title="Réponses et contexte" icon="message" href="/fr/guides/answers-context">Choix multiples, réponse semi-ouverte, refus et données déjà connues.</Card>
  <Card title="Progression et qualification" icon="chart-line" href="/fr/concepts/qualification">Comprendre les dimensions et les niveaux Essentiel, Équilibré et Approfondi.</Card>
  <Card title="Référence SDK" icon="code" href="/fr/integrations/sdk">Clients, permissions, méthodes et configuration avancée.</Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.