Table of Contents

🇬🇧 English version

Donner une boîte aux lettres à vos agents

Voir aussi : Outils e-mail · Écrire une crew en TypeScript · Référence CLI · Retour à l'index

En un quart d'heure environ, vous allez lancer un agent qui trie une vraie boîte Gmail : il lit le courrier non lu, range chaque message dans un dossier selon son genre, et écrit les réponses en brouillons qu'un humain relit et envoie. Rien n'est envoyé. Cette page est le chemin court à travers un exemple fourni ; le guide des outils e-mail est la référence complète.

Ce que vous obtenez

L'exemple est 13-email-triage.ork.ts avec son fichier de réglages 13-email-triage.appsettings.json. Trois règles tiennent ensemble les outils e-mail, et l'exemple s'appuie sur les trois :

  • Un agent ne fait que nommer un compte. Serveurs, identifiants et droits sont les rĂ©glages de l'opĂ©rateur (Orkeon:Tools:Email).
  • Les Rights du compte dĂ©cident de ce qu'un agent peut faire, et l'envoi reste fermĂ© tant que Send:AllowedRecipients ne liste pas qui peut recevoir du courrier.
  • Le courrier reçu est une donnĂ©e, jamais une instruction. Chaque rĂ©sultat de lecture porte le verdict d'un filtre anti-injection de prompt.

Prérequis

Il vous faut Notes
Orkeon Un clone du dépôt, ou l'outil orkeon installé — voir Trois façons d'exécuter Orkeon. Un script .ork.ts demande aussi esbuild : les archives de release le livrent, un clone l'installe à son premier build, et l'outil dotnet ne le livre pas — npm install -g esbuild (où il est cherché ; orkeon doctor le vérifie).
Un modèle Les réglages de l'exemple pointent vers un Docker Model Runner local (ai/granite-4.0-h-tiny sur localhost:12434). N'importe quel profil de examples/appsettings/ convient : une exécution résout un seul fichier de réglages, copiez donc la section Llm du profil dans le fichier de l'exemple.
Un compte Gmail Avec la validation en deux étapes activée — les mots de passe d'application n'existent pas sans elle.

1. Créer un mot de passe d'application Gmail

  1. Ouvrez https://myaccount.google.com/apppasswords, créez un mot de passe d'application nommé Orkeon et copiez les 16 lettres que Google affiche — sans les espaces entre les groupes. Si Google répond que les mots de passe d'application ne sont pas disponibles pour votre compte, passez par Gmail avec OAuth2.

  2. Exportez-le dans le shell qui lancera l'exemple :

    export TRIAGE_GMAIL_APP_PASSWORD='abcdefghijklmnop'      # bash / zsh
    
    $env:TRIAGE_GMAIL_APP_PASSWORD = 'abcdefghijklmnop'      # PowerShell
    

2. Les réglages

Le fichier de réglages de l'exemple déclare un compte sous Orkeon:Tools:Email (sa section Llm, et la limite de temps Scripting traitée à l'étape 4, sont omises ici). Remplacez l'adresse par la vôtre :

"Orkeon": {
  "Tools": {
    "Email": {
      "DefaultAccount": "triage",
      "Accounts": {
        "triage": {
          "Provider": "Gmail",
          "Address": "your.name@gmail.com",
          "Rights": "Read, Organize, Draft",
          "Auth": {
            "Method": "Password",
            "PasswordEnvVar": "TRIAGE_GMAIL_APP_PASSWORD"
          }
        }
      }
    }
  }
}
  • Provider: Gmail est un prĂ©rĂ©glage : il renseigne imap.gmail.com:993 pour la lecture et smtp.gmail.com:465 pour l'envoi, tous deux en TLS.
  • PasswordEnvVar nomme la variable d'environnement qui contient le mot de passe. Le secret n'est jamais dans le fichier, ni jamais un argument d'outil — les arguments d'outil sont journalisĂ©s. La variable peut porter n'importe quel nom.
  • Rights est obligatoire. Read, Organize, Draft permet Ă  l'agent de chercher et lire, de crĂ©er des dossiers et d'y dĂ©placer le courrier, et d'enregistrer des brouillons — exactement ce qu'utilise le script. Il ne peut rien envoyer, supprimer ni purger ; un appel hors de ces droits Ă©choue avec un message qui nomme le droit manquant.
  • DefaultAccount est le compte qu'utilise un appel qui n'en nomme aucun. Avec un seul compte, on pourrait l'omettre ; le script ne nomme aucun compte.

3. Vérifier le compte depuis le terminal

Les commandes orkeon email sont le côté opérateur de la famille — les agents ne les lancent jamais. Depuis un clone, remplacez orkeon par dotnet run --project src/scripting/Orkeon.Scripting.Cli --.

orkeon email accounts --settings examples/scripting/13-email-triage.appsettings.json
orkeon email check triage --settings examples/scripting/13-email-triage.appsettings.json
  • accounts n'ouvre aucune connexion : il liste triage (default), son adresse, comment il lit et envoie, ses droits, et affiche ready — ou NOT READY: suivi de ce qu'il faut corriger (le plus souvent la variable qui n'est pas dĂ©finie dans ce shell).
  • check se connecte, s'authentifie et liste les dossiers, puis affiche E-mail account 'triage' is reachable: avec le nombre de dossiers et les compteurs de la boĂ®te de rĂ©ception.

Codes de sortie : 0 succès, 1 ce que vous corrigez (les réglages, un compte inconnu, une variable non définie), 2 ce qu'ont fait le serveur ou le réseau (un mot de passe refusé, un échec de connexion), 130 Ctrl+C. Le fichier de réglages utilisé est nommé sur stderr (Using settings: …).

4. Lancer le tri

Depuis un clone, à la racine du dépôt :

dotnet run --project src/scripting/Orkeon.Scripting.Cli -- run examples/scripting/13-email-triage.ork.ts \
  --settings examples/scripting/13-email-triage.appsettings.json

Avec l'outil installé, placez les deux fichiers de l'exemple côte à côte et lancez :

orkeon run 13-email-triage.ork.ts --settings 13-email-triage.appsettings.json

Ce que fait le script, dans l'ordre :

  1. Il s'arrête aussitôt si les réglages ne déclarent aucun modèle — l'écho qui répond sans modèle ne sait pas trier du courrier.
  2. Il crée les dossiers Triage/Reply, Triage/Read, Triage/Newsletters et Triage/Review (des libellés sur Gmail). Un dossier existant est laissé tel quel : chaque exécution peut le refaire.
  3. Il prend une page de la boîte de réception : les dix messages non lus les plus récents (email_search). Les lire (email_read) les laisse non lus.
  4. Un message que le filtre anti-injection ne juge pas clean n'atteint jamais le modèle : il part dans Triage/Review. Les autres sont remis au modèle encadrés, comme des données, et classés en reply, read ou newsletter ; toute autre réponse part aussi dans Triage/Review.
  5. Pour un reply, le modèle rédige une courte réponse que le script enregistre comme brouillon de réponse (email_draft) — il attend dans les Brouillons de Gmail.
  6. Chaque message est ensuite déplacé dans son dossier (email_move), un à la fois : une exécution interrompue à mi-chemin a rangé ce qu'elle a fini, et la suivante reprend sur le reste.

L'exécution se termine en affichant son résultat en JSON sur stdout — la ligne de synthèse de l'agent, le nombre de messages rangés par genre et le nombre de brouillons :

{
  "result": {
    "output": "sorted 10 message(s), 3 draft(s) to review",
    "filed": { "reply": 3, "read": 4, "newsletter": 2, "review": 1 },
    "drafts": 3
  }
}

Les nombres ci-dessus sont illustratifs. Ouvrez Gmail : la boîte de réception a perdu ces messages, les libellés Triage/… les contiennent, et les Brouillons contiennent les réponses, que vous modifiez et envoyez — ou non.

Une limite de temps s'applique. Le bac à sable du scripting borne une exécution entière à 30 secondes de temps réel par défaut, appels de messagerie et de modèle attendus compris, et dix messages passés par un modèle local prennent plus longtemps. Le fichier de réglages de l'exemple relève la borne à dix minutes, "Orkeon": { "Scripting": { "Limits": { "ExecutionTimeout": "00:10:00" } } } à côté de Tools ; gardez ce bloc quand vous écrivez votre propre fichier de réglages. Les messages rangés avant un arrêt restent rangés.

5. L'adapter

  • D'autres dossiers, d'autres genres. L'objet folders en tĂŞte du script associe chaque genre Ă  un dossier, et kinds liste ce que le modèle peut rĂ©pondre ; changez les deux, ainsi que le prompt qui nomme les genres. emailSearch accepte d'autres critères (from, subject, since, limit jusqu'Ă  50…) — les paramètres les listent. Dans un script, les noms d'outils sont en camelCase (tools.emailSearch) mais les clĂ©s des arguments gardent le snake_case des outils (unread_only, reply_to_id).

  • Le laisser envoyer — sans risque. Ajoutez Send aux Rights et listez les destinataires : tant que Send:AllowedRecipients ne contient aucune entrĂ©e, email_send refuse tout message. Les entrĂ©es sont des adresses, *@domaine ou * ; To, Cc et Bcc sont tous vĂ©rifiĂ©s, et MaxRecipients / MaxPerHour plafonnent le volume. Les brouillons restent le meilleur chemin pour toute personne hors de vos propres adresses. Voir Droits et liste d'autorisation d'envoi.

    "Rights": "Read, Organize, Draft, Send",
    "Send": { "AllowedRecipients": [ "your.name@gmail.com" ], "MaxPerHour": 10 }
    
  • Depuis un crew YAML plutĂ´t. L'hĂ´te d'exĂ©cution derrière orkeon run enregistre les treize outils email_* : un agent YAML les liste par leur nom — tools: [email_accounts, email_search, email_read, email_move, email_draft] — et c'est le modèle qui dĂ©cide des appels. DĂ©clarez les comptes dans le fichier de rĂ©glages propre Ă  ce crew (il contient aussi la section Llm du crew), pas dans un appsettings.json du dossier d'oĂą vous lancez, ni dans des variables d'environnement : ceux-lĂ  atteignent toutes les exĂ©cutions. Voir Depuis un crew YAML. orkeon forge propose les outils de boĂ®te aux lettres aux crews qu'il forge et les essaie sur une boĂ®te fictive : voir Crews forgĂ©s.

Autres boîtes aux lettres

Gmail et Hotmail sont campagnés. Le parcours de ce tutoriel — un mot de passe d'application Gmail — a été joué sur un vrai compte le 2026-10-04, et Gmail en OAuth2 le 2026-10-05 : voir Ce que la campagne Gmail a établi. Hotmail via Microsoft Graph a été joué sur un vrai compte le 2026-10-12.