🇬🇧 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. Rightsest obligatoire pour chaque compte :Read, Write, Organize, Share, Delete, Purge.Rootconfine 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:AllowedRecipientsvide n'autorise personne, et les liens publics restent désactivés tant queShare:AllowPublicLinksne vaut pastrue. - Chaque compte se connecte une fois en OAuth2 (
orkeon drive logindans 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
- Ouvrez le centre d'administration Microsoft Entra › Inscriptions d'applications (App registrations) › Nouvelle inscription.
- 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. - 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.
- Dans Autorisations d'API › Microsoft Graph › Autorisations déléguées, ajoutez
Files.ReadWrite(ouFiles.Readpour un compte qui ne fait que lire) etoffline_access. Sansoffline_access, Microsoft ne délivre aucun jeton de rafraîchissement, et le login refuse d'enregistrer une connexion qui expirerait dans l'heure. - 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.
Dans la console Google Cloud, créez un projet et activez l'API Google Drive.
Configurez l'écran de consentement OAuth : type d'utilisateur Externe, ajoutez le scope
https://www.googleapis.com/auth/drive(oudrive.readonlypour un compte qui ne fait que lire), et votre propre adresse comme utilisateur test.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_SECRETci-dessous).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" } }Connectez-vous : dans un terminal, lancez
orkeon drive login perso. La commande affiche une adresse Google à ouvrir et écoute sur un port libre de127.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. AccorderWriteplus tard change les scopes, et le compte demande une nouvelle connexion. Rootest 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 quelimit.- 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_deletemet à la corbeille (la corbeille de OneDrive), d'où une personne le restaure.permanent: trueexigePurge; un compte du tenantconsumers(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.comougraph.microsoft.com, en HTTPS. Un téléchargement OneDrive passe par la@microsoft.graph.downloadUrlpré-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_reads'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). AvecScreening: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).extquand 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_cursorreprend exactement après le dernier élément montré ;drive_readrend des tranches avecnext_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
consumerspeut le faire), si bien quedrive_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 unnext_cursorqui 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.