Aller au contenu principal

Guide de développement de prompt

English version: ../../en/guides/prompt-development.md

Ce guide montre comment écrire, vérifier, publier, rendre et versionner un prompt du Prompt Registry. Publier demande le rôle tenant_admin ou developer ; tout principal du tenant peut lister et rendre.

Concept​

Un prompt est un gabarit nommé avec des marqueurs {{variable}} et des variables typées. Chaque publication avec un gabarit ou des variables différents devient une nouvelle version immuable, numérotée à partir de 1, avec une empreinte sha256: ; une publication identique n'est pas dupliquée. Le rendu vérifie chaque valeur selon les variables déclarées avant de produire le texte, si bien qu'un agent n'envoie jamais un prompt à moitié rempli à un modèle.

Champs du prompt​

Le corps de POST /v1/prompts :

ChampTypeDéfautDescription
namechaîneobligatoireMinuscules, chiffres, ., _ et -, de 1 à 128 caractères.
templatechaîneobligatoireTexte avec des marqueurs {{ name }} ; les accolades doivent être équilibrées.
descriptionchaîne""À quoi sert le prompt.
variablestableaudéduitVariables déclarées ; sans elles, chaque marqueur devient une string obligatoire.
model_hintchaîneaucunModèle pour lequel le prompt a été écrit.

Chaque variable :

ChampTypeDéfautDescription
namechaîneobligatoireIdentifiant (^[A-Za-z_][A-Za-z0-9_]*$).
typechaînestringstring, integer, number, boolean, array ou object.
requiredbooléentrueUne valeur obligatoire absente et sans default est refusée.
defaultquelconqueaucunValeur utilisée quand l'appelant n'en envoie pas.
descriptionchaîne""Aide pour l'appelant.
max_lengthentieraucunLongueur maximale d'une valeur chaîne.
enumtableauaucunValeurs autorisées.

Créer un prompt​

enterprise-ai create prompt écrit prompts/<nom>.yaml avec un gabarit et des variables typées ; les règles sont celles du registre (POST /v1/prompts) : variables déclarées, accolades équilibrées, types string, integer, number, boolean, array ou object.

enterprise-ai create prompt invoice-extract

Étapes​

  1. Créer le fichier du prompt. La commande écrit prompts/invoice-extract.yaml avec deux variables typées et le vérifie avec les règles du registre. Dans le portail : Studio développeur > Studio de prompts > Nouveau.

    enterprise-ai create prompt invoice-extract

    Résultat attendu : le fichier est listé et déclaré valide selon prompt.

    En cas d'échec : code de sortie 1 avec « exists » ; ajoutez --force.

  2. Écrire le gabarit et déclarer les variables. Chaque marqueur doit être une variable déclarée ; typez-les toutes et bornez les chaînes avec max_length ou enum. Traitez chaque valeur comme une donnée : une variable ne doit jamais porter des instructions que le gabarit n'encadre pas.

    Résultat attendu : l'éditeur du Studio de prompts ne signale aucun problème.

    En cas d'échec : « unbalanced or invalid placeholder » ou « undeclared variables » nomme la partie fautive.

  3. Publier. POST /v1/prompts crée le prompt en version 1, ou publie la version suivante. Dans le portail : Enregistrer comme nouvelle version.

    import yaml
    doc = yaml.safe_load(open("prompts/invoice-extract.yaml"))
    client.prompts.create(doc["name"], doc["template"], description=doc["description"], variables=doc["variables"])

    Résultat attendu : la réponse donne latest_version et la version avec son digest.

    En cas d'échec : 422 template_error, 400 invalid_request (nom), 403 forbidden (rôle).

  4. Tester le rendu. POST /v1/prompts/{name}/render rend la dernière version, ou la version indiquée, avec strict à vrai par défaut (les variables inconnues sont refusées). Dans le portail : Studio de prompts > Rendre la dernière version.

    Résultat attendu : text, chars et estimated_tokens.

    En cas d'échec : 422 missing_variables liste chaque variable avec son erreur (missing, type, enum, max_length, unknown).

  5. L'utiliser depuis un agent. Rendez le prompt par son nom et fixez la version dans le code de production, pour qu'une nouvelle publication ne change pas un agent en service.

    Résultat attendu : l'agent envoie le texte rendu par la passerelle.

    En cas d'échec : 404 not_found avec prompt_version signifie que la version fixée n'existe pas.

  6. Publier une nouvelle version. Modifiez le gabarit ou les variables et publiez de nouveau. GET /v1/prompts/{name}/versions liste les versions, de la plus récente à la plus ancienne.

    Résultat attendu : latest_version augmente de un ; les versions précédentes restent utilisables pour le rendu.

    En cas d'échec : un gabarit et des variables identiques renvoient la version existante, sans nouveau numéro.

  7. Retirer une version. Le registre n'a pas de route de suppression : les versions restent pour l'audit. Faites passer les appelants sur une autre version et publiez-en une nouvelle qui remplace le texte retiré.

    Résultat attendu : plus aucun appelant ne rend la version retirée.

    En cas d'échec : cherchez dans le code le numéro de version fixé.

Versions et rendu​

GET /v1/prompts/{name}/versions liste les versions, POST /v1/prompts/{name}/render rend une version avec ses variables.

client.prompts.render("invoice-extract", version="3", variables={"lang": "fr"})

Dépannage​

SymptômeCauseCorrection
422 template_error avec reasonMarqueur déséquilibré ou invalide.Écrivez chaque marqueur sous la forme {{ name }}.
422 template_error avec undeclared_variablesUn marqueur n'est pas dans variables.Déclarez-le, ou retirez variables pour les déduire.
422 template_error avec typeType de variable inconnu.Utilisez string, integer, number, boolean, array ou object.
422 missing_variablesValeurs absentes, mal typées, hors enum, trop longues ou inconnues.Lisez errors ; n'envoyez strict: false que pour ignorer des valeurs en trop.
400 invalid_requestLe nom ne suit pas le motif.Utilisez des minuscules, des chiffres, ., _ et -.
403 forbiddenL'appelant n'a ni tenant_admin ni developer.Demandez le rôle.
404 not_foundPrompt ou version inconnu.Listez-les avec enterprise-ai get prompts.

Étapes suivantes​