Version de développement

Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.

Développeurs

Développer avec Flow

Référence développeur du module frappe.flow : DocTypes, API whitelistée, événements temps réel et intégration de la page /flow.

Développer avec Flow

Le module Python frappe.flow (nom de module : Flow) intègre l'assistant Flow au framework. Les autres applications peuvent s'appuyer sur lui pour définir des agents, des compétences, des outils et des déclencheurs en Python.

Organisation du module

frappe/flow/doctype/ : les DocTypes de Flow (agents, sessions, exécutions, modèles, fournisseurs, compétences, outils, déclencheurs, connaissances) ;
frappe/flow/api/api.py : les méthodes whitelistées appelées par la page /flow ;
frappe/flow/lib/ : agent, modèle, session, outils et résolution ;
frappe/flow/triggers/triggers.py et frappe/flow/lib/trigger.py : exécution et synchronisation des déclencheurs sur les événements de documents ;
frappe/flow/knowledge/ : ingestion, découpage, vectorisation et interrogation des bases de connaissances ;
frappe/flow/daemon/ : cycle de vie du serveur qui exécute les agents ;
frappe/flow/launcher.py et frappe/public/js/flow_launcher.bundle.js : injection du lanceur Flow dans les pages HTML servies par le framework ;
frappe/www/flow/ : la page /flow. C'est une application Vite (paquet flow/, code Vue dans flow/frontend/) construite par bench build avec le reste des assets du framework. Un échec de ce build fait échouer bench build.

Les hooks de Flow (after_install, after_migrate…) sont déclarés dans le hooks.py du framework. Par exemple, frappe.flow.lib.agent.sync_agents, sync_tools et frappe.flow.lib.trigger.sync_triggers synchronisent après chaque migration les agents, outils et déclencheurs définis en Python par les applications.

DocTypes

DocType	Rôle
Flow Provider	fournisseur de modèles
Flow Model	modèle disponible dans les conversations
Flow Agent	assistant (modèle, compétences, outils, sous-agents, bases de connaissances, mémoires)
Flow Agent Skill / Flow Agent Tool / Flow Agent Sub Agent / Flow Agent Knowledge Base / Flow Agent Memory	éléments rattachés à un agent
Flow Skill	compétence, définissable en Python par une application
Flow Tool	outil, définissable en Python par une application
Flow Trigger	déclencheur sur les événements de documents
Flow Knowledge Base / Flow Knowledge Source / Flow Knowledge Chunk / Flow Knowledge Settings	bases de connaissances, leurs sources et leur configuration
Flow Settings	réglages de Flow
Flow Session	une conversation
Flow Session Message	un message d'une conversation
Flow Session Attachment	une pièce jointe d'une conversation
Flow Run	une exécution de l'agent dans une conversation

API whitelistée

La page /flow appelle les méthodes frappe.flow.api.* suivantes :

Méthode	Paramètres	Rôle
`boot`	—	données initiales de la page, dont la liste des modèles
`list_sessions`	`limit`, `query`, `before`	liste paginée des conversations, filtrable par titre
`session`	`session`	détail d'une conversation
`create_session`	`agent`, `model`, `auto_approve`	création d'une conversation
`entries`	`session`, `since`, `path` (`active` ou `all`)	événements du journal d'une conversation
`sync_session`	`session`	resynchronisation d'une conversation
`run`	`session`, `message`, `attachments`	envoi d'un message
`resume`	`session`, `answers`, `approval_seq`	reprise après une pause d'approbation
`abort`	`session`	interruption d'une exécution en cours
`cancel_pending`	`session`	annulation des actions en attente
`rewind`	`session`, `target_seq`	retour arrière dans la conversation
`compact`	`session`	compaction de l'historique
`set_model`	`session`, `model`, `reasoning_effort`	changement de modèle de la conversation
`set_title`	`session`, `title`	renommage de la conversation
`set_auto_approve`	`session`, `auto_approve`	mode d'approbation automatique
`delete_session`	`session`	suppression de la conversation
`list_shares` / `share_session` / `unshare_session`	`session`, `user`	partage d'une conversation avec un utilisateur
`find_users`	`query`	recherche d'utilisateurs Flow par nom ou e-mail
`set_general_access`	`session`, `access` (`Restricted` ou `Everyone`)	accès général à la conversation
`attach_file` / `cleanup_attachments`	`file`, `model` / `attachments`, `session`	préparation et nettoyage des pièces jointes (fichiers privés)
`skills`	`session` ou `agent`	compétences actives d'une conversation, ou aperçu pour un agent
`submit_feedback`	`run_name`, `rating`, `comment`	évaluation d'une exécution
`screen_result`	`session`, `token`, `screen`, `error`	réponse du panneau à une lecture d'écran demandée par l'agent
`save_secret`	`session`, `call_id`, `password`	enregistrement d'un secret saisi par l'utilisateur dans une carte de demande

Temps réel

Les événements d'une conversation sont diffusés en temps réel sur Socket.io, dans le namespace nommé d'après le site :

le client envoie flow:subscribe avec le nom de la session et reçoit un acquittement { subscribed: true } ; flow:unsubscribe met fin à l'abonnement ;
le serveur publie flow:event (un événement du journal portant session_id), ainsi que flow:resync et flow:resubscribe (demande de réabonnement, notamment après une vérification d'accès refusée par le relais).

Le relais est assuré côté serveur par frappe/realtime/flow_handlers.py et realtime/flow_handlers.js.

Le lanceur Flow dans le Desk

frappe/flow/launcher.py injecte le script flow_launcher.bundle.js dans les pages HTML servies par le framework. Ce script, écrit en JavaScript simple dans un shadow root, ajoute l'icône et le panneau du lanceur sans dépendre du code du Desk.