Agent D-ID

Le composant Agent D-ID intègre dans votre projet un avatar conversationnel IA, un chatbot avec un visage et une voix. Le visiteur lui parle, et l’agent peut agir en retour sur votre projet : changer d’écran, lire vos données, déclencher n’importe quelle action que vous avez configurée.

Comment l’agent IA et votre projet s’articulent

La plupart des composants attendent que votre projet leur dise quoi faire. Celui-ci fonctionne aussi dans l’autre sens, et c’est l’idée à garder en tête avant tout le reste.

Le partage des rôles est simple :

• La conversation appartient à D-ID. L’agent écoute, comprend, décide quoi dire, et le dit avec le visage et la voix que vous avez choisis dans le Studio D-ID. Les exemples ci-dessous prennent un guide de musée, mais le même schéma convient à un catalogue produit, à une application de formation ou à une borne d’accueil.
• L’application appartient à PandaSuite. Vos écrans, vos collections, votre Datastore, vos actions.

L’agent est piloté par un modèle d’intelligence artificielle, et la charnière entre les deux mondes est un Client Tool. Chez D-ID, un Client Tool est une capacité que vous promettez à l’agent : un nom, une description, et une liste d’arguments. L’agent ne sait pas comment le tool fonctionne. Il sait seulement que, lorsque la conversation s’y prête, il peut demander son exécution, avec des arguments remplis à partir de ce que le visiteur a dit.

Dans PandaSuite, cette promesse devient un événement du composant. L’agent appelle le tool, l’événement se déclenche avec les arguments du tool, et les actions que vous y avez attachées s’exécutent. Si l’agent attend quelque chose en retour, l’une de ces actions lui répond.

Un aller-retour complet ressemble donc à ceci :

Tout ce qui suit est une façon de mettre en place une partie de cette boucle.

Ajouter et configurer le composant

Cliquez sur Composants et ajoutez le composant Agent D-ID à votre écran. C’est un composant visuel : il affiche l’interface officielle D-ID, avatar et contrôles compris, dans la zone que vous lui donnez.

Étape 1 : renseigner votre clé API

Dans le panneau Propriétés, collez votre Clé API. Vous la trouverez dans votre compte D-ID, sous Settings > API Key.

Étape 2 : choisir votre agent

Cliquez sur Actualiser à côté de la propriété Agent. Le composant demande à D-ID les agents de votre clé et remplit la liste déroulante. Choisissez celui que vous voulez.

Cliquez de nouveau sur Actualiser chaque fois que vous créez un nouvel agent dans le Studio D-ID, pour que la liste se mette à jour.

Si la liste reste vide, la clé n’appartient pas au compte propriétaire de l’agent. Vérifiez-la dans votre compte D-ID puis appuyez de nouveau sur Actualiser.

Étape 3 : synchroniser

Double-cliquez sur le composant pour l’ouvrir, puis appuyez sur Sync.

Vous êtes maintenant à l’intérieur du composant. Sync, les client tools et le prompt de l’agent se trouvent ici. Le panneau Propriétés et le panneau Actions restent à l’extérieur : utilisez le fil d’Ariane en haut de l’espace de travail pour en ressortir. Vous ferez plusieurs fois l’aller-retour.

La synchronisation est le moment où le composant apprend ce que votre agent sait faire. En une passe, elle :

• rafraîchit la liste de vos agents, comme le fait Actualiser, et s’arrête si celui que vous avez choisi n’y est plus,
• lit les Client Tools de l’agent et déclare chacun comme un événement du composant,
• lit le prompt de l’agent dans le champ Agent prompt,
• crée, ou réutilise, la Client Key D-ID qui permet à votre projet publié de parler à l’agent,
• utilise la vignette de l’agent comme image du composant lorsqu’il parvient à la lire, pour que vous le reconnaissiez sur l’espace de travail.

Vous devriez maintenant voir le nom de l’agent en haut du composant, la date de la dernière synchronisation, et la liste de ses client tools avec leurs arguments.

Laisser l’agent IA agir sur votre projet

Un Client Tool est un événement

Après une synchronisation, chaque client tool de l’agent apparaît dans le panneau Actions du composant, exactement comme un événement déclencheur natif. Attachez-y les actions de votre choix.

Les arguments du tool voyagent avec l’événement. Dans n’importe quelle action de cette liste, ouvrez la fenêtre de data binding et choisissez Depuis l’événement : les arguments s’y trouvent, sous leurs propres noms, prêts à être liés. Un argument dont le nom entrerait en conflit avec un nom réservé apparaît sous un alias, que la fiche du tool précise.

Exemple. Une application Museum Explorer possède un tool search_exhibits(query). Un visiteur dit « avez-vous quelque chose sur les volcans ? », l’agent appelle search_exhibits avec query valant volcans, et l’événement search_exhibits se déclenche dans votre projet en portant ce mot. Vous y attachez une action qui lance une Recherche, et vous liez son Terme de recherche avec

.

La recherche se lance, mais l’agent n’entend toujours rien au sujet des volcans. Lui dire ce que vous avez trouvé est une étape distincte, et c’est la section suivante.

Répondre à l’agent avec Renvoyer une valeur

Certains appels de tool sont des questions. L’agent demande, attend, et énonce ce qu’il reçoit.

Pour répondre, ajoutez l’action Renvoyer une valeur à la liste d’actions de l’événement et remplissez son paramètre Réponse. Liez-le à tout ce que votre projet sait produire : une collection, un champ de Datastore, le résultat d’une recherche, une simple constante.

Une liste contient au plus un Renvoyer une valeur : une fois que vous l’avez ajouté, Studio ne le propose plus pour cette liste. Placez-le où vous voulez dans la liste. Il répond à l’appel, et les actions qui le suivent s’exécutent quand même : vous pouvez répondre vite puis continuer.

Si un événement ne comporte pas de Renvoyer une valeur, l’agent reçoit un simple ok une fois la liste d’actions terminée, sauf si l’une de ces actions a échoué, auquel cas l’agent est informé de l’échec de l’appel. C’est la bonne réponse pour un tool qui agit au lieu d’informer, comme un changement d’écran.

Nommer vos tools dans le prompt de l’agent

C’est l’étape qui surprend, et cela mérite d’être dit clairement : un tool vers lequel rien dans le prompt ne pointe reste inutilisé. Un tool parfaitement synchronisé, avec des actions parfaites derrière lui, attend que les instructions donnent à l’agent une raison d’y recourir.

Nommer le tool est la façon la plus sûre, et celle vers laquelle revenir quand l’agent ignore un tool que vous attendiez. Inviter le comportement fonctionne aussi, lorsque la description du tool est elle-même assez explicite : un agent à qui l’on demande de naviguer entre les écrans pour illustrer son propos trouvera un tool décrit par « Change the screen to illustrate what you are saying ». Ce qui ne fonctionne jamais, c’est le silence.

Le champ Agent prompt du composant montre les instructions de l’agent telles que D-ID les conserve, lues à la dernière synchronisation. Modifiez-les ici puis appuyez sur Save prompt : le texte est enregistré chez D-ID, pour cet agent.

Écrivez les tools dans les instructions en langage clair, comme vous le feriez pour un nouveau guide :

Quand un visiteur demande ce qu’il y a à voir, appelle list_screens et décris les résultats. Quand il en choisit un, appelle change_screen avec l’écran correspondant pour que l’application suive la conversation.

Créer un Client Tool sans quitter PandaSuite

Vous n’avez pas besoin de quitter PandaSuite pour donner une nouvelle capacité à l’agent. Dans le composant, appuyez sur New client tool. Un panneau s’ouvre avec :

• Name : le nom qu’emploiera l’agent. Lettres, chiffres, _ et -, jusqu’à 64 caractères. Ni espaces ni accents : écrivez list_screens, pas list screens.
• Description : ce que fait le tool, dans les termes de l’agent, de 1 à 500 caractères. C’est ce que l’agent lit pour décider s’il doit l’appeler.
• Arguments : une ligne par argument, chacune avec un nom, un type, une description et une case Required. Un nom d’argument commence par une lettre, puis accepte lettres, chiffres ou _. Pas de - ici, contrairement au nom du tool.

Appuyez sur Save changes. Le tool est créé chez D-ID, attaché à votre agent et déclaré comme événement du composant d’un seul geste.

Quatre types d’arguments sont disponibles, parce qu’un argument doit être quelque chose qu’un modèle de langage sait produire :

Type	Ce que l’agent envoie	Usage typique
String	du texte	une requête de recherche, un nom, une réponse libre
Number	un nombre	une quantité, une année, une note
Boolean	true ou false	un oui ou un non
Page	un écran de votre projet	la navigation, les visites guidées, « emmenez-moi aux volcans »

Page est le type intéressant. L’argument arrive dans vos actions comme un véritable écran, que vous pouvez lier directement dans Changer d’écran. L’agent doit encore savoir quels écrans existent : donnez à un tool change_screen un argument de type Page, associez-le à un tool list_screens qui distribue les écrans, et orientez le prompt vers les deux.

Les données plus riches ont leur place du côté de la réponse, pas du côté des arguments. Un tool renvoie une collection entière via Renvoyer une valeur, sans rien de tout cela.

Modifier ou supprimer un tool

Chaque tool de la liste porte deux boutons.

Edit rouvre le panneau sur la définition existante. Enregistrer réécrit le tool chez D-ID, ce qui compte lorsque plusieurs agents de votre compte le partagent : ils reçoivent tous la nouvelle définition.

Remove supprime le tool chez D-ID, pour tous les agents qui l’utilisent, et supprime l’événement et ses actions dans votre projet. Un second clic est demandé avant l’opération.

Avant toute écriture, le composant relit D-ID et refuse d’écraser ce qui y a changé depuis votre dernière synchronisation. Dans ce cas, appuyez sur Sync puis modifiez de nouveau.

Un tool qui n’est plus sur l’agent est signalé Not on the agent. Son événement et ses actions sont conservés, et vous décidez : Add to the agent le remet en place, Remove l’abandonne. Renommer un tool chez D-ID ne vous coûte jamais vos actions.

Piloter l’agent IA depuis votre projet

La conversation n’est pas à sens unique. Utilisez Agir sur un composant sur le composant Agent D-ID pour accéder à :

Action	Ce qu’elle fait
Parler	Fait dire à l’agent un Texte, que vous pouvez lier à vos données
Lire un audio	Fait jouer à l’agent un fichier audio depuis une URL audio
Interrompre	Arrête immédiatement l’agent de parler
Micro	Couper, Rétablir ou Basculer le micro du visiteur
Haut-parleur	Couper, Rétablir ou Basculer le son de l’agent

Parler sert à faire dire un texte à voix haute à l’agent : il accueille un visiteur en le nommant, énonce un résultat, ou commente l’endroit où l’application vient d’arriver. L’agent parle au visiteur avec sa propre voix, et le texte peut venir de n’importe où dans votre projet.

Réagir à la conversation

Événements déclencheurs

En plus des client tools, le composant déclenche ces événements déclencheurs :

Événement	Se déclenche quand	Porte
Session démarrée	la connexion à l’agent est établie
Session terminée	la connexion est fermée, perdue ou échoue	Raison : disconnected, closed ou fail
L’agent commence à parler	l’agent commence à parler
L’agent cesse de parler	l’agent cesse de parler
L’agent réfléchit	l’agent commence à générer une réponse
Erreur	D-ID signale une erreur, ou une action n’a pas pu s’exécuter parce que l’agent n’est pas encore chargé	Code et Message

Propriétés exposées

Le composant expose quatre valeurs pour le data binding, sous Depuis un composant. Pour la plupart des interfaces, les deux premières suffisent :

• Connecté : vrai tant que la session est active.
• Parle : vrai tant que l’agent parle.

Liez-les à un indicateur d’écoute, à une pulsation autour de l’avatar, ou à la visibilité d’une zone de sous-titres. Les deux valeurs brutes sont là quand vous voulez un contrôle plus fin :

• État de connexion : new, connecting, connected, completed, disconnecting, disconnected, closed, fail. connected et completed signifient tous deux que la session est active : les navigateurs diffèrent sur celui qu’ils finissent par signaler.
• Activité : IDLE, TALKING, LOADING, BUFFERING.

Propriétés du composant

Propriété	Description
Clé API	Votre clé API D-ID. Utilisée dans PandaSuite Studio uniquement, jamais publiée.
Agent	L’agent à intégrer. Appuyez sur Actualiser pour lister les agents de votre clé.
Domaines personnalisés	Vos propres origines où tourne le projet publié, avec le schéma, par exemple https://kiosque.example. Utilisez + Add pour chacune.
Connexion automatique	Se connecte à l’agent dès l’affichage du composant, sans attendre que le visiteur appuie sur le bouton de connexion.
Orientation	Disposition Verticale ou Horizontale de l’interface D-ID.
Identifiant externe	Identifiant optionnel du visiteur ou de la session transmis à D-ID, pour relier la conversation à votre propre utilisateur. Lu une seule fois au chargement du composant.

Publier votre projet

D-ID restreint un agent aux adresses sur lesquelles il a le droit de tourner. La synchronisation crée une Client Key qui couvre ces adresses, ou en réutilise une qui les couvre déjà.

Celles de PandaSuite sont prises en charge pour vous : l’aperçu dans PandaSuite Studio, le viewer web et l’adresse locale utilisée par les viewers iOS et Android. Vous ne déclarez que ce que PandaSuite ne peut pas savoir.

Si vous publiez sur un domaine personnalisé, ou si vous intégrez votre projet dans votre propre site, ajoutez cette origine dans Domaines personnalisés avec + Add, puis appuyez de nouveau sur Sync pour que la clé la couvre.

Un exemple complet : un avatar IA qui guide le visiteur

L’objectif : un visiteur demande à l’avatar ce qu’il y a à voir, et l’application suit la conversation.

Avant de commencer : votre Clé API est renseignée, un Agent est choisi, vous avez appuyé une fois sur Sync, et vous êtes à l’intérieur du composant. Le projet contient une collection d’expositions et un écran par exposition.

1. Créez le tool qui liste les expositions.

Dans le composant, appuyez sur New client tool. Nommez-le list_screens, décrivez-le par « Lists the PandaSuite project screens », et laissez la liste Arguments vide. Appuyez sur Save changes.

2. Répondez-lui.

Ressortez par le fil d’Ariane, sélectionnez le composant, ouvrez Actions et cliquez sur le bouton +. Vos client tools figurent dans la liste des déclencheurs, aux côtés de Session démarrée. Choisissez list_screens, puis ajoutez une seule action : Renvoyer une valeur. Liez son paramètre Réponse à la liste des écrans de votre projet, sous Depuis le projet dans la fenêtre de data binding, pour que l’agent apprenne quels écrans il peut demander.

3. Créez le tool qui navigue.

Retournez à l’intérieur du composant et appuyez de nouveau sur New client tool. Nommez-le change_screen, décrivez-le par « Change the screen to illustrate what you are saying », et ajoutez un argument : Screen, de type Page, décrit par « The representation of a PandaSuite screen, obtained by the list_screens tool », Required.

4. Faites-le naviguer.

De retour dans Actions, sur le déclencheur change_screen, ajoutez Changer d’écran. Studio l’affiche ensuite sous le nom Aller à l’écran : même action, autre nom. Cliquez sur le nom du paramètre de destination pour ouvrir la fenêtre de data binding, puis choisissez

. Aucun Renvoyer une valeur n’est nécessaire ici : ce tool agit, il ne renseigne pas, donc le simple ok que reçoit l’agent une fois la liste exécutée est la bonne réponse.

5. Parlez des deux à l’agent.

Dans Agent prompt, ajoutez un paragraphe qui les nomme, puis appuyez sur Save prompt :

Tu es un guide de musée. Quand le visiteur demande ce qu’il y a à voir, appelle list_screens et présente les résultats avec tes propres mots. Quand le visiteur en choisit un, appelle change_screen avec l’écran correspondant.

6. Testez.

Lancez l’aperçu du projet, appuyez sur le bouton de connexion de l’avatar (ou réglez Connexion automatique sur Yes au préalable), et autorisez le micro lorsque le navigateur le demande. Demandez à l’avatar ce qu’il y a à voir. Il devrait lister vos écrans, et vous emmener sur le bon quand vous le choisissez.

Si rien ne se passe, vérifiez d’abord le prompt : c’est la cause habituelle. Pour voir si un appel arrive, attachez une action Changer l’état de l’écran temporaire à l’événement, vous la verrez se déclencher.

Bonnes pratiques et limites

• Décrivez les tools pour l’agent, pas pour vous. Le nom et la description sont les seules choses que l’agent lit pour décider d’appeler un tool. « Ouvrir l’écran d’une exposition » lui vaut un appel ; « nav handler v2 » non.
• Gardez des réponses courtes. La réponse parvient à l’agent sous forme de texte, plafonnée à 15 Kio. Au-delà, elle est tronquée en silence, et une réponse structurée tronquée arrive cassée. Renvoyez les quelques champs dont l’agent a besoin pour parler, pas toute votre base.
• Un tool, une tâche. Un agent choisit entre ses tools d’après leurs descriptions. Deux tools qui se recouvrent rendent ce choix peu fiable.
• Le composant lit ses tools une seule fois, à son chargement. Un tool que vous ajoutez n’atteint pas un projet déjà lancé, et se reconnecter n’y change rien. Synchronisez, puis rechargez : relancez l’aperçu, ou rechargez la page.
• Le micro relève du navigateur. Les navigateurs n’accordent l’accès au micro que sur une adresse sécurisée en https, et seulement après autorisation du visiteur. Testez le projet publié à son adresse réelle, et pas seulement dans l’aperçu.
• Réexportez une application publiée avant cela. Tous les viewers transmettent désormais les réponses à l’agent, mais une application continue de tourner avec le viewer avec lequel elle a été exportée. Sur un export plus ancien, l’événement se déclenche et vos actions s’exécutent, mais aucun appel de tool ne rend la main à l’agent, pas même celui qui, sans Renvoyer une valeur, se serait contenté de répondre ok. Réexporter est le correctif.
• Avatar, voix, personnalité, salutations et connaissances restent chez D-ID. Modifiez-les dans le Studio D-ID : ils prennent effet à la connexion suivante, sans aucun Sync. Sync ne ramène que les tools, le prompt et l’image de l’agent.

Voir aussi

• Data binding pour alimenter les réponses de l’agent depuis votre projet.
• Actions interactives pour tout ce qu’un événement peut déclencher.
• Écrans et Collection pour les deux choses dont un agent parle le plus souvent.
• Composants personnalisés si vous voulez construire un composant qui déclare ses propres événements de la même façon.