Table of Contents

🇬🇧 English version

Outils drive

Voir aussi : Inventaire des outils · Outils e-mail · Référence de configuration · ADR-013 · Retour à l'index

La famille drive donne aux agents un drive dans le nuage : Google Drive (« Mon Drive ») via l'API Drive v3, et OneDrive — personnel, ou professionnel et scolaire — via Microsoft Graph. Les deux sont parlés en HTTP simple, sans SDK de fournisseur. Un agent liste, cherche, lit, télécharge vers le système de fichiers virtuel, charge sur le drive des fichiers qui en viennent, crée des dossiers, déplace, renomme, supprime et partage — dans les limites de ce qu'autorise l'opérateur :

  • L'opĂ©rateur dĂ©clare les comptes sous Orkeon:Tools:Drive. Un agent nomme un compte (ou prend celui par dĂ©faut), jamais un id client, un secret ou un jeton.
  • Rights est obligatoire pour chaque compte : Read, Write, Organize, Share, Delete, Purge.
  • Root confine un compte Ă  un dossier de son drive. Tout Ă©lĂ©ment que touche un appel doit se trouver dessous ; un Ă©lĂ©ment hors de ce dossier est signalĂ© comme introuvable.
  • Le partage est fermĂ© par dĂ©faut : une liste Share:AllowedRecipients vide n'autorise personne, et les liens publics restent dĂ©sactivĂ©s tant que Share:AllowPublicLinks ne vaut pas true.
  • Chaque compte se connecte une fois en OAuth2 (orkeon drive login dans un terminal), et les outils rafraĂ®chissent eux-mĂŞmes le jeton d'accès.

Couverture de test. La famille est couverte par des tests hors ligne contre des API Google et Microsoft scriptées ; elle n'est pas vérifiée ici contre toutes les configurations de comptes réels. Signalez ce qui diffère.

Les onze outils

Outil Droit requis Ce qu'il fait
drive_accounts aucun Liste les comptes : nom, droits, dossier racine, si chacun est prĂŞt
drive_list Read Une page d'un dossier (la racine par défaut), dossiers en tête
drive_search Read Les éléments qui correspondent à des mots, un nom, un type MIME, une nature, une date ou un dossier, dans la racine
drive_info Read Les métadonnées d'un élément, son adresse dans le navigateur comprise
drive_read Read Le texte d'un fichier texte ou d'un document Google, filtré, par tranches
drive_download Read + un montage accessible en écriture Enregistre un fichier dans un répertoire virtuel ; les documents Google sont exportés
drive_upload Write Charge un fichier du VFS, ou remplace le contenu d'un fichier (replace_id)
drive_create_folder Write Crée un dossier
drive_move Organize Déplace et/ou renomme un élément
drive_delete Delete (+ Purge avec permanent) Met un élément à la corbeille, ou le supprime définitivement
drive_share Share Donne accès à des adresses autorisées, ou crée un lien public quand c'est permis

Les ids sont ceux du fournisseur, et opaques : repassez-les exactement tels que drive_list ou drive_search les ont rendus. root désigne le dossier racine du compte partout où un id de dossier est attendu (folder_id, parent_id, destination_id).

OneDrive (Microsoft Graph)

Enregistrer une application dans Microsoft Entra

  1. Ouvrez le centre d'administration Microsoft Entra › Inscriptions d'applications (App registrations) › Nouvelle inscription.
  2. Nommez-la (Orkeon drive, par exemple) et choisissez les types de comptes pris en charge : Comptes Microsoft personnels uniquement pour un OneDrive personnel, Comptes dans un annuaire organisationnel et comptes Microsoft personnels pour servir les deux. Aucun URI de redirection n'est nécessaire.
  3. Dans Authentification, réglez Autoriser les flux de clients publics (Allow public client flows) sur Oui : la connexion utilise le flux par code d'appareil.
  4. Dans Autorisations d'API › Microsoft Graph › Autorisations déléguées, ajoutez Files.ReadWrite (ou Files.Read pour un compte qui ne fait que lire) et offline_access. Sans offline_access, Microsoft ne délivre aucun jeton de rafraîchissement, et le login refuse d'enregistrer une connexion qui expirerait dans l'heure.
  5. Copiez l'ID d'application (client).

Une application enregistrée pour la famille e-mail peut aussi servir la famille drive : ajoutez-lui les autorisations Files.*.

Déclarer le compte et se connecter

Sous Orkeon:Tools:Drive:Accounts :

"pro": {
  "Provider": "OneDrive",
  "Rights": "Read, Write, Organize",
  "Root": "Orkeon/agents",
  "Auth": { "ClientId": "00000000-0000-0000-0000-000000000000" }
}

Auth:Tenant vaut par défaut consumers, le tenant des comptes personnels ; pour un OneDrive professionnel ou scolaire, mettez "Tenant": "organizations" ou l'id de votre tenant.

Dans un terminal :

orkeon drive login pro

La commande affiche l'adresse de vérification de Microsoft et un code. Ouvrez l'adresse dans n'importe quel navigateur — sur n'importe quel appareil —, saisissez le code, connectez-vous et acceptez. La commande enregistre les jetons et affiche Signed in. Vérifiez le compte avec orkeon drive check pro : elle trouve le dossier racine et liste ses premiers éléments.

Google Drive

Le device flow de Google ne propose pas les scopes Drive : le login affiche donc l'adresse de la page de consentement de Google, à ouvrir, et reçoit la réponse sur une adresse de bouclage (127.0.0.1), avec PKCE — le même flux qu'un compte Gmail en OAuth2.

  1. Dans la console Google Cloud, créez un projet et activez l'API Google Drive.

  2. Configurez l'écran de consentement OAuth : type d'utilisateur Externe, ajoutez le scope https://www.googleapis.com/auth/drive (ou drive.readonly pour un compte qui ne fait que lire), et votre propre adresse comme utilisateur test.

  3. Créez un ID client OAuth de type Application de bureau (Desktop app). Copiez son ID client, et mettez son secret client dans une variable d'environnement (GOOGLE_DRIVE_CLIENT_SECRET ci-dessous).

  4. Déclarez le compte, sous Orkeon:Tools:Drive:Accounts :

    "perso": {
      "Provider": "GoogleDrive",
      "Rights": "Read, Write",
      "Root": "Orkeon",
      "Auth": {
        "ClientId": "123456789012-abcdefghijklmnop.apps.googleusercontent.com",
        "ClientSecretEnvVar": "GOOGLE_DRIVE_CLIENT_SECRET"
      }
    }
    
  5. Connectez-vous : dans un terminal, lancez orkeon drive login perso. La commande affiche une adresse Google à ouvrir et écoute sur un port libre de 127.0.0.1. Connectez-vous et acceptez ; Google affiche un écran d'avertissement pour une application qu'il n'a pas vérifiée, que vous pouvez passer pour votre propre application. Quand le navigateur tourne sur une autre machine — WSL, un conteneur, une session SSH — la dernière page ne peut pas se charger : copiez l'adresse où elle aboutit (http://127.0.0.1:…/?state=…&code=…) depuis la barre d'adresse, collez-la dans le terminal et appuyez sur Entrée.

Garder la connexion. Une application Google laissée au statut de publication Test reçoit des jetons de rafraîchissement qui expirent au bout de 7 jours. Publiez-la (En production) pour les garder.

Référence des réglages

Clé (sous Orkeon:Tools:Drive) Signification
DefaultAccount Le compte que prend un appel qui n'en nomme aucun ; facultatif avec un seul compte
CredentialsDirectory Où sont gardés les jetons (son sous-répertoire drive) ; par défaut credentials à côté des réglages de l'utilisateur
Screening:WithholdRejected Retenir le texte d'un fichier que le filtre anti-injection de prompt rejette (défaut false : signaler seulement)
Accounts:<nom>:Provider GoogleDrive ou OneDrive — obligatoire
Accounts:<nom>:Rights Parmi Read, Write, Organize, Share, Delete, Purge — obligatoire
Accounts:<nom>:Root Le dossier auquel le compte est confiné, en chemin depuis la racine du drive (Orkeon/agents) ; non renseigné : tout le drive
Accounts:<nom>:Auth:ClientId L'application Google Cloud ou Microsoft Entra — obligatoire
Accounts:<nom>:Auth:ClientSecretEnvVar Le nom de la variable qui contient le secret client Google — obligatoire pour Google Drive. Écrivez le nom seul : Orkeon ne développe aucune variable, et un compte dont Auth:ClientSecretEnvVar contient une référence ${NOM} ou %NOM% est mis de côté, avec ce problème
Accounts:<nom>:Auth:Tenant Microsoft seulement : consumers (défaut), organizations, common ou un id de tenant
Accounts:<nom>:Share:AllowedRecipients Avec qui un agent peut partager : une adresse, *@domaine ou * ; vide : personne
Accounts:<nom>:Share:AllowPublicLinks Si un agent peut créer un lien que quiconque le détient peut ouvrir (défaut false)
Accounts:<nom>:MaxUploadMegabytes Le plus gros chargement (défaut 100)
Accounts:<nom>:TimeoutSeconds Délai HTTP des appels du compte

La section est validée paresseusement, comme celle de l'e-mail : un compte cassé est signalé quand un appel ou orkeon drive s'en sert, et ne casse jamais un crew qui n'ouvre aucun drive. Le secret client est lu comme les secrets de l'e-mail : l'environnement du processus, puis — sous Windows — les variables propres à l'utilisateur.

Droits, dossier racine et scopes

Droit Outils qu'il ouvre
Read drive_list, drive_search, drive_info, drive_read, drive_download
Write drive_upload, drive_create_folder
Organize drive_move
Share drive_share
Delete drive_delete (vers la corbeille)
Purge drive_delete avec permanent: true
  • Un compte qui ne fait que lire demande un scope en lecture seule (drive.readonly, Files.Read) : le jeton divulguĂ© d'un crew qui lit ne peut pas Ă©crire non plus. Accorder Write plus tard change les scopes, et le compte demande une nouvelle connexion.
  • Root est trouvĂ© une fois par run : par chemin sur OneDrive, par nom sous chaque parent sur Google Drive (qui n'a pas de chemins). Un Ă©lĂ©ment est dans la racine quand son chemin parent le dit (OneDrive) ou quand la remontĂ©e de ses parents atteint la racine (Google Drive, 32 niveaux au plus). Une recherche sur Google Drive ne peut pas ĂŞtre bornĂ©e Ă  une sous-arborescence : ses rĂ©sultats hors de la racine sont Ă©cartĂ©s, si bien qu'une page peut contenir moins d'Ă©lĂ©ments que limit.
  • Un nom dĂ©jĂ  pris dans un dossier est refusĂ© au chargement, Ă  la crĂ©ation de dossier et au dĂ©placement : Google Drive accepterait deux Ă©lĂ©ments du mĂŞme nom, et un agent qui dĂ©signe les fichiers par leur nom prendrait alors le mauvais.
  • La corbeille d'abord. drive_delete met Ă  la corbeille (la corbeille de OneDrive), d'oĂą une personne le restaure. permanent: true exige Purge ; un compte du tenant consumers (comptes Microsoft personnels ; le dĂ©faut) n'a pas de suppression dĂ©finitive sur OneDrive et l'outil la refuse.
  • Un crew dont les outils drive exigent un droit qu'aucun compte prĂŞt n'accorde est refusĂ© au dĂ©part, avant tout appel au modèle, avec une ligne par outil — comme pour les outils mail.

Ce qui atteint l'agent, et ce qui ne sort jamais

  • Le jeton reste auprès de l'API. Il n'est envoyĂ© qu'Ă  www.googleapis.com ou graph.microsoft.com, en HTTPS. Un tĂ©lĂ©chargement OneDrive passe par la @microsoft.graph.downloadUrl prĂ©-authentifiĂ©e sans lui, une session de chargement reçoit les octets sans lui, et un curseur de pagination qui ne pointe pas vers l'API est refusĂ©.
  • Le contenu est une donnĂ©e. drive_read s'ouvre sur un avis qui dit que le texte n'est pas fiable, et sur le verdict du filtre anti-injection de prompt (clean, suspicious, rejected). Avec Screening:WithholdRejected, le texte d'un fichier rejetĂ© est retenu. Les noms et mĂ©tadonnĂ©es des autres outils passent par le filtrage habituel des rĂ©sultats du run.
  • Un tĂ©lĂ©chargement n'Ă©crase jamais rien. drive_download Ă©crit un nouveau fichier (nom (2).ext quand le nom est pris) dans un montage oĂą le crew a le droit de crĂ©er.
  • Les rĂ©sultats tiennent dans la boucle d'agent. Une page est redemandĂ©e avec moins d'Ă©lĂ©ments jusqu'Ă  tenir dans un rĂ©sultat d'outil, si bien que next_cursor reprend exactement après le dernier Ă©lĂ©ment montrĂ© ; drive_read rend des tranches avec next_offset.
  • Une recherche s'en tient Ă  la racine. Aucun des deux fournisseurs ne cherche dans un sous-arbre seul (Google cherche dans tout le drive, OneDrive du tenant consumers peut le faire), si bien que drive_search Ă©carte ce qui est hors de la racine du compte et lit d'autres pages du fournisseur, jusqu'Ă  cinq, pour remplir la page demandĂ©e. Une page peut encore revenir courte, voire vide, avec un next_cursor qui reprend de lĂ .
  • Le trafic drive reste hors du journal des Ă©changes LLM. Le client drive est exclu de ce que capture --llm-log : ses requĂŞtes, le contenu des fichiers et les adresses des sessions de chargement n'y sont jamais Ă©crits.

Utiliser les outils

Depuis un crew YAML :

agents:
  archivist:
    role: "Archivist"
    goal: "File the weekly report in the team drive"
    tools: [drive_list, drive_upload, drive_move]

Depuis un script .ork.ts, les outils sont typés (Typings/tools.d.ts), avec les clés snake_case propres à l'outil :

const page = await tools.driveList({ folder_id: "root" });
const report = await tools.driveUpload({ path: "/output/report.pdf", folder_id: page.items[0].id });

Commandes

orkeon drive accounts [--json]     # les comptes, leurs droits, dossier racine et état de préparation (sans réseau)
orkeon drive login <account>       # la seule étape interactive : code d'appareil (OneDrive) ou navigateur (Google)
orkeon drive check <account>       # se connecte, trouve le dossier racine, liste ses premiers éléments
orkeon drive logout <account>      # oublie les jetons stockés

Chaque verbe prend --settings <fichier> ; sans lui, les réglages sont résolus comme orkeon run les résout, si bien que les jetons arrivent là où chaque run les cherche. login et check prennent aussi --events jsonl : une ligne d'événement par étape, pour un programme qui les pilote (référence CLI).

accounts --json écrit un objet par compte : name, provider, rights, root, default, ready, problem, plus configuration_problems (les problèmes de la configuration, une phrase chacun, ceux de la section d'abord ; vide quand le compte se résout), credential_problem (pourquoi un compte résolu ne peut pas encore se connecter, sinon null) et token_endpoint (le point de terminaison des jetons OAuth après préréglages : pour OneDrive il nomme le tenant ; null pour un compte mis de côté). problem garde son texte : les problèmes de configuration joints ou le diagnostic des identifiants.

OĂą vivent les jetons

Le runner les garde sous sa racine interne /credentials, qu'aucun outil destiné aux agents ne résout, dans un sous-répertoire drive créé réservé au propriétaire sous Unix — à côté du sous-répertoire email de la famille e-mail, dans le même répertoire d'identifiants. Comme pour l'e-mail, les jetons sont à l'abri des outils du VFS, pas d'un shell_command qui tourne sous le même utilisateur du système. orkeon-repl ne tient aucun magasin de jetons : un outil drive appelé depuis la REPL le dit.

Hors périmètre pour l'instant

Les drives partagés Google et les bibliothèques de documents SharePoint (un compte voit son propre « Mon Drive » ou son OneDrive), les révisions, les commentaires, le retrait d'un partage, la copie, et un drive d'essai pour la forge — la forge retire les outils drive d'un crew forgé. Un drive monté dans le système de fichiers virtuel n'est pas proposé non plus : les outils sont l'interface.