Développement de module

Création du service

Un module est un service qui doit exposer deux routes :

• Un fichier de manifeste servi sur la route /.well-known/ai-plugin.json
• Une route d'exécution de méthode sur la route définie dans le manifeste.

Par exemple en NodeJS, un tel service peut être créé avec le code suivant :

const Koa = require('koa');
const Router = require('@koa/router');
const app = new Koa();
const router = new Router();

// route du manifeste
router.get('/.well-known/ai-plugin.json', (ctx) => {
  ctx.body = {
    // Voir plus loin pour la définition du manifeste.
  };
});

router.post('/ai-functions', (ctx) => {
  switch (ctx.body.method) {
    case 'hello':
      ctx.body = {
        message: 'Hello World!'
      };
      return;
    default:
      ctx.body = {
        error: 'Unknown method'
      };
  }
});

app.use(router.routes());
app.listen(8080, () => {
  console.info('Service started.');
});

Définition du manifeste

Le manifeste contient quelques information décrivant le module et ses fonctionnalités. Il est servi sur la route /.well-known/ai-plugin.json.

Il définit dans la propriété api la liste des fonctions que le module expose, avec à chaque fois la signature de la méthode et de ses paramètres, un nom et une description. Ces informations doivent reste concises car elles seront inclues dans le contexte du moteur IA.

La propriété api.endoint définit l'URL de la route d'exécution des méthodes que le cerveau appellera lorsqu'il estimera devoir utiliser ce module.

const manifest = {
  "schema_version": "v1",
  "name_for_human": "ActInTech Events",
  "name_for_model": "actintech",
  "description_for_human": "Access ActInTech events and manage your participation.",
  "description_for_model": "Help the user with ActInTech events. You can view events and manage the participation status of the user.",
  "auth": {
    "type": "none"
  },
  "api": {
    "type": "functions",
    "functions": [
      {method: 'getEvents()', name: 'getEvents', description: "Retrieve the list of upcoming events."},
      {
        method: 'eventParticipation({ eventId: "ID of the event", participation: "YES or NO" })',
        name: 'eventParticipation',
        description: "Update the participation status to an event."
      },
    ],
    "endpoint": "http://localhost:8085/ai-functions",
  },
  "logo_url": "http://localhost:8085/logo.png",
  "contact_email": "kevin.thizy@intech.lu",
  "legal_info_url": "https://act.intech.lu"
};

Authentification

Si le module est libre d'accès, précisez "none" en valeur auth.type.

Si le module nécessite une authentification, précisez une des valeurs suivantes.

Authentification par clé d'API de service

Un cerveau IA peut être configuré pour utiliser une clé d'API de service pour accéder à un module. Dans ce cas, le cerveau utilisera sa clé d'API pour tous les appels au module.

{
  "type": "service_api_key"
}

Le cerveau ajoutera sa clé d'API dans chaque requête via le header X-API-KEY: <clé d'API>.

La clé d'API est à fournir lors de l'ajout du module au cerveau:

POST {{endpointCerveau}}/brains/:brainId/modules
Body
{
    "type": "External",
    "name": "module name",
    "configuration": {
        "definition": "http://localhost:3000/.well-known/ai-plugin.json"
        "auth": {
            "apiKey": "<clé API>"
        }
    }
}

Format des appels et des réponses

Lorsque le cerveau interroge le module, il exécute un POST sur la route définie par api.endpoint. L'appel contient en body le nom de la méthode appelée et les paramètres tels qu'ils ont été générés par le moteur IA :

{
  "method": "eventParticipation",
  "params": "{\"eventId\":\"INEBD763D\",\"participation\":\"YES\"}"
}

La réponse du module doit contenir la propriété text dans le body. Ce texte sera transmis au moteur IA comme contexte.

{
  "text": "Participation of user to event INEBD763D (Soirée Magic the Gathering) has been validated."
}

Le langage utilisé pour générer le texte peut être en anglais ou en français sans incidence sur le reste du flux de l'IA et du cerveau.

Flux de confirmation

Pour les opérations en écriture, il est recommandé d'implémenter un flux de confirmation. Pour déclencher une demande de confirmation à transmettre à l'utilisateur, le module peut indiquer le paramètre askConfirmation dans sa réponse. Il est également conseillé de l'indiquer dans le texte de la réponse:

{
  "text": "Demande de confirmation pour une inscription à l'évènement Magic the Gathering (ID INEBD763D) du vendredi 6 octobre.",
  "askConfirmation": true,
  "confirmationLink": "http://localhost:8085/confirmations/873YDBAI"
}

Le cerveau transmettra alors la demande de confirmation à l'utilisateur. Si l'utilisateur confirme, le cerveau contactera de nouveau le plugin pour la confirmation. Le cerveau appelle alors la route indiquée dans confirmationLink pour référencer le flux de confirmation déclenché. Le module peut alors exécuter l'action confirmée. Il est possible d'ajouter des paramètres en query dans l'URL de confirmation. Le cerveau contactera la route via un POST.

Actions

Les modules peuvent définir des actions que le cerveau pourra transmettre à l'agent. C'est par exemple utile pour jouer des animations du côté de l'avatar. Pour indiquer au cerveau une action qu'il peut exécuter, le module peut ajouter une propriété action dans la réponse.

{
  "text": "...",
  "actions": [
    {
      "code": "...",
      "type": "..."
    }
  ]
}

Il est nécessaire de spécifier code, qui sera la clé que l'IA pourra inclure dans sa réponse pour déclencher l'action. Ce code est une chaîne de caractère sans espaces qui doit être unique dans le tableau actions. Pour que l'IA sache qu'elle peut utiliser ces actions, il est recommandé de les inclure dans le texte de la réponse de l'outil, entouré de crochets : [[code]].

Le contenu de la propriété sera transmis à l'agent dans un message de type DO_ACTION:

{
  "type": "DO_ACTION",
  "messageId": "<UUID>",
  "sequence": 0,
  "action": {
  }
}

Par exemple, pour faire jouer une animation à l'avatar, un outil peut utiliser la réponse suivante :

{
  "text": "Animation de danse du canard : [[ACTION.PLAY_ANIMATION.WAIT]]",
  "actions": [
    {
      "code": "[[ACTION.PLAY_ANIMATION.WAIT]]",
      "type": "PLAY_ANIMATION",
      "animationId": "WAIT"
    }
  ]
}

Afin que le cerveau soit incité à exécuter des actions, il est recommander de rajouter une indication dans son prompt init, par exemple :

FR : Tu as la capacité d'exécuter des actions et activités physiques ou autre en les mettant entre crochets [[ACTION.NAME]] (n'utilise que les actions qui te sont proposées par les outils).
EN : You can execute physical or virtual actions and activities by putting them between brackets [[ACTION.NAME]] (use only actions suggested by tools).

Mode collecte

Dans certains cas, un outil peut souhaiter récupérer l'intégralité de la réponse brute de l'utilisateur (par exemple pour réaliser une collecte de témoignage). Pour cela, il peut indiquer au cerveau qu'il souhaite récupérer la réponse complète via le mode "collecte".

Ce mode s'active en via la propriété collectResponse à true dans le résultat de l'outil:

{
  "text": "Quel est votre avis sur l'évènement Magic the Gathering ?",
  "collectResponse": true,
  "collectResponseLink": "https://tool.intech.app/collection/INEBD763D"
}

Le cerveau renverra la réponse complète de l'utilisateur sur l'url collectResponseLink:

{
  "text": "Mon avis sur l'évènement Magic the Gathering est que..."
}