diff --git a/docs/Flowdeck_Agent_integration.md b/docs/Flowdeck_Agent_integration.md new file mode 100644 index 0000000..5c09276 --- /dev/null +++ b/docs/Flowdeck_Agent_integration.md @@ -0,0 +1,702 @@ +# FlowDeck Agent — Intégration & Fonctionnement + +> **Version:** 1.0 · **Date:** 2026-07-20 · **Auteur:** Hermes-Deepin +> **Cible:** Agent IA natif pour FlowDeck, inspiré de Notion Agent (2026) +> **Prérequis:** FlowDeck v4.0.x · FastAPI · SQLite · Gitea/GitHub + +--- + +## Table des matières + +1. [Vision & Objectifs](#1-vision--objectifs) +2. [Concept : de l'IA qui répond à l'IA qui réalise](#2-concept) +3. [Positionnement dans l'architecture FlowDeck](#3-positionnement) +4. [Placement dans l'interface (sidebar 🤖 Agents)](#4-placement-interface) +5. [Boucle d'exécution de l'agent](#5-boucle-dexécution) +6. [Sources de contexte FlowDeck](#6-sources-de-contexte) +7. [Modèle de données (nouvelles tables)](#7-modèle-de-données) +8. [Routes & API Agent](#8-routes--api) +9. [Le service AgentEngine](#9-service-agentengine) +10. [Système d'outils (Tools)](#10-système-doutils) +11. [Permissions & sécurité](#11-permissions--sécurité) +12. [Custom Agents & déclencheurs](#12-custom-agents) +13. [Skills réutilisables](#13-skills) +14. [Cas d'usage FlowDeck](#14-cas-dusage) +15. [Plan de migration](#15-plan-de-migration) +16. [Limitations](#16-limitations) + +--- + +## 1. Vision & Objectifs + +FlowDeck Agent transforme FlowDeck d'un clone Notion **passif** (où l'utilisateur crée manuellement collections, pages, propriétés) en un espace de travail **agentique** où une IA peut : + +- Comprendre un objectif exprimé en langage naturel +- Lire le contexte du workspace (collections, pages, propriétés, issues Gitea) +- Planifier une suite d'actions +- **Exécuter** ces actions via l'API interne (créer collections, pages, propriétés, vues, sync Gitea) +- Retourner un résultat consolidé + +L'agent réutilise l'infrastructure existante : **il n'appelle pas directement la DB**, il passe par les mêmes routers FastAPI (`/db/*`, `/board/api/*`) que l'utilisateur, garantissant cohérence, validation et respect du `PermissionManager`. + +Cette fonctionnalité concrétise la ligne `v5.0.0 — AI Assistants` de la roadmap, en s'inspirant directement du modèle Notion Agent. + +--- + +## 2. Concept : de l'IA qui répond à l'IA qui réalise {#2-concept} + + + +Assistant classique : +Utilisateur → Prompt → Réponse texte +FlowDeck Agent : +Utilisateur → Objectif → Planification → Collecte contexte → Actions API → Résultat + + +| Notion AI | FlowDeck Agent | +|-----------|----------------| +| Répond, résume, réécrit | Planifie, recherche, **agit** | +| Bloc de texte | Crée collections, pages, propriétés, vues | +| Sans état | Historique de conversation + snapshots | +| Aucune action DB | Modifie le workspace via routers FastAPI | + +--- + +## 3. Positionnement dans l'architecture FlowDeck {#3-positionnement} + +L'agent s'insère comme un **nouveau service** et un **nouveau router**, sans modifier le cœur existant. + + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ CLIENT (Browser) │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ agent_panel.html — Panneau conversation (Alpine.js) │ │ +│ │ agent_message.html — Fragment message (HTMX streaming) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +└──────────────────────────┬───────────────────────────────────────┘ + │ HTTP (SSE stream / JSON) +┌──────────────────────────▼───────────────────────────────────────┐ +│ FASTAPI (Python 3.11+) │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ ROUTERS │ │ +│ │ ├─ agent.py ← NOUVEAU /api/agent/* │ │ +│ │ └─ (existants: board.py, api.py, collections.py, ...) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ SERVICES │ │ +│ │ ├─ AgentEngine ← NOUVEAU (orchestrateur) │ │ +│ │ ├─ ToolRegistry ← NOUVEAU (outils actionnables) │ │ +│ │ ├─ LLMClient ← NOUVEAU (GPT/Claude/Gemini/local) │ │ +│ │ ├─ ContextBuilder ← NOUVEAU (collecte workspace) │ │ +│ │ ├─ SearchEngine (réutilisé — FTS5) │ │ +│ │ ├─ PermissionManager (réutilisé — ACL) │ │ +│ │ └─ GiteaClient (réutilisé — API Gitea) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ DATA LAYER — SQLite │ │ +│ │ ├─ agents ← NOUVEAU │ │ +│ │ ├─ agent_conversations ← NOUVEAU │ │ +│ │ ├─ agent_messages ← NOUVEAU │ │ +│ │ ├─ agent_actions ← NOUVEAU (journal audit) │ │ +│ │ ├─ agent_skills ← NOUVEAU │ │ +│ │ └─ (tables existantes: collections, pages, ...) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +└──────────────────────────┬───────────────────────────────────────┘ + │ HTTPS + ┌──────────────────┴──────────────────┐ + ▼ ▼ +┌──────────────────┐ ┌──────────────────────────┐ +│ GITEA API REST │ │ PROVIDER LLM │ +│ (contexte issues)│ │ OpenAI / Anthropic / │ +│ │ │ Gemini / Ollama local │ +└──────────────────┘ └──────────────────────────┘ +``` + +**Principe clé — Tool-calling en boucle fermée :** +Le `LLMClient` ne touche jamais la base. Il émet des *intentions d'outil* (function calls). L'`AgentEngine` les traduit en appels HTTP internes vers les routers existants, exécutés avec la session et les permissions de l'utilisateur. + +--- + +## 4. Placement dans l'interface (sidebar 🤖 Agents) {#4-placement-interface} + +Le sidebar FlowDeck contient déjà une entrée **🤖 Agents** (voir ARCHITECTURE §5.2). Elle devient le point d'entrée de l'agent. + + +``` +┌────────────┬─────────────────────────────────────────────────┐ +│ SIDEBAR │ CONTENU PRINCIPAL │ +│ │ │ +│ 🕒 Recents │ ┌─ Page / Collection courante ──────────────┐ │ +│ ⭐ Favoris │ │ │ │ +│ 🤖 Agents ◄┼── clic ouvre le panneau agent (droite) │ │ +│ 👥 Shared │ └────────────────────────────────────────────┘ │ +│ │ ┌────────────┐ │ +│ │ │ 🤖 Agent │ │ +│ │ ├────────────┤ │ +│ │ │ Historique │ │ +│ │ │ Réponses │ │ +│ │ │ ───────── │ │ +│ │ │ @Sources │ │ +│ │ │ 📎 Fichier │ │ +│ │ │ [Modèle ▾] │ │ +│ │ │ [Saisie... ]│ │ +│ │ └────────────┘ │ +└────────────┴─────────────────────────────────────────────────┘ +``` + +Deux modes d'accès, comme Notion Agent : + +- **Icône flottante** (coin inférieur droit) — accès global rapide +- **Section 🤖 Agents** du sidebar — liste des agents (personnel + custom) + +L'affichage de la section 🤖 Agents est déjà prévu dans les 3 scénarios de compte (A/B/C) — voir ARCHITECTURE §6.5.4 : **toujours visible**. + +--- + +## 5. Boucle d'exécution de l'agent {#5-boucle-dexécution} + +Adaptation du modèle Notion (Compréhension → Contexte → Raisonnement → Action) à l'architecture FlowDeck : + +``` +Utilisateur formule un objectif + │ + ▼ +┌─────────────────────────────────────────────┐ +│ 1. COMPRÉHENSION (AgentEngine) │ +│ Parse objectif + instructions custom │ +└──────────────────┬──────────────────────────┘ + ▼ +┌─────────────────────────────────────────────┐ +│ 2. COLLECTE CONTEXTE (ContextBuilder) │ +│ - Page/collection courante (cookie ws) │ +│ - @mentions explicites │ +│ - SearchEngine FTS5 (pages pertinentes) │ +│ - Issues Gitea liées (GiteaClient) │ +│ - Fichiers joints │ +│ ⚠ filtré par PermissionManager │ +└──────────────────┬──────────────────────────┘ + ▼ +┌─────────────────────────────────────────────┐ +│ 3. RAISONNEMENT (LLMClient + ToolRegistry) │ +│ LLM reçoit: objectif + contexte + schéma │ +│ des outils disponibles (function calling) │ +│ → émet un plan / une intention d'outil │ +└──────────────────┬──────────────────────────┘ + ▼ +┌─────────────────────────────────────────────┐ +│ 4. ACTION (AgentEngine → routers FastAPI) │ +│ Exécute l'appel outil → route interne │ +│ POST /db → create_collection │ +│ POST /db/{id}/properties → add_property │ +│ POST /db/{id}/pages → create_page │ +│ Journalise dans agent_actions │ +└──────────────────┬──────────────────────────┘ + ▼ + Résultat outil réinjecté dans le LLM + │ + ┌────────┴────────┐ + │ Objectif atteint?│ + └────┬────────┬────┘ + non │ │ oui + │ ▼ + (retour étape 3) ┌─────────────────────────────┐ + │ 5. RÉSULTAT consolidé + lien │ + │ vers les objets créés │ + └─────────────────────────────┘ +``` + +Cette boucle **ReAct** (Reason + Act) se répète jusqu'à `max_iterations` (défaut : 12) ou atteinte de l'objectif. + +--- + +## 6. Sources de contexte FlowDeck {#6-sources-de-contexte} + +Correspondance avec les sources Notion Agent, adaptées aux entités FlowDeck : + +| Source Notion | Équivalent FlowDeck | Mécanisme | +|---------------|---------------------|-----------| +| Pages, sous-pages | `pages`, `collection_pages` (parent_id) | `SearchEngine` FTS5 + lecture directe | +| Bases de données | `collections` + `collection_properties` | Lecture schéma `schema_json` | +| Wikis / docs internes | Blocs éditeur (`content_json`) | Parsing blocs | +| Jira | **Issues Gitea/GitHub** | `GiteaClient` (issues, labels, milestones) | +| Slack / Drive | Fichiers uploadés (`/api/files/`) | Lecture `files` property | +| Fichiers joints | Upload local-workspace | PDF/MD parsing | +| `@Projet Alpha` | `@collection` / `@page` / `@repo` | Résolution de mention | + +**Résolution des mentions** — L'utilisateur peut cibler : + + +@collection:Roadmap → force le contexte sur une collection +@page:123 → une page précise +@repo:bruno/flowdeck → issues d'un repo Gitea +@ws → workspace courant complet + + +Le `ContextBuilder` respecte strictement le `PermissionManager` : l'agent ne voit **que** ce que l'utilisateur peut voir (même token, mêmes ACL — voir ARCHITECTURE §6.2). + +--- + +## 7. Modèle de données (nouvelles tables) {#7-modèle-de-données} + +```sql +-- Définition d'un agent (personnel ou custom) +CREATE TABLE agents ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + workspace_id INTEGER REFERENCES workspaces(id), + name TEXT NOT NULL DEFAULT 'FlowDeck Agent', + icon TEXT DEFAULT '🤖', + agent_type TEXT NOT NULL DEFAULT 'personal', + -- 'personal' | 'custom' + description TEXT DEFAULT '', + + -- Instructions personnalisées (ton, format, règles métier) + system_instructions TEXT DEFAULT '', + + -- Modèle IA par défaut + model TEXT DEFAULT 'claude-opus-4-8', + -- gpt-* | claude-* | gemini-* | ollama:* + + -- Périmètre custom agent : collections/repos autorisés + scope_json TEXT NOT NULL DEFAULT '{}', + -- {collections:[3,7], repos:["bruno/flowdeck"], tools:["create_page"]} + + -- Déclencheurs (custom agents) + trigger_json TEXT NOT NULL DEFAULT '{}', + -- {type:"schedule", cron:"0 9 * * 1"} | {type:"webhook", event:"issue.opened"} + + is_active BOOLEAN NOT NULL DEFAULT 1, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + created_by INTEGER REFERENCES users(id), + UNIQUE(workspace_id, name) +); + +-- Conversations (fils de discussion, comme Notion history) +CREATE TABLE agent_conversations ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + agent_id INTEGER NOT NULL REFERENCES agents(id) ON DELETE CASCADE, + user_id INTEGER NOT NULL REFERENCES users(id), + title TEXT DEFAULT 'New conversation', + -- Contexte de départ (page/collection ouverte à l'invocation) + context_json TEXT NOT NULL DEFAULT '{}', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +-- Messages d'une conversation +CREATE TABLE agent_messages ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + conversation_id INTEGER NOT NULL REFERENCES agent_conversations(id) ON DELETE CASCADE, + role TEXT NOT NULL, + -- 'user' | 'assistant' | 'tool' | 'system' + content TEXT NOT NULL DEFAULT '', + -- Pour role='tool' : nom de l'outil + payload + résultat + tool_calls_json TEXT DEFAULT '[]', + model TEXT, + tokens_used INTEGER DEFAULT 0, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +-- Journal d'audit : CHAQUE action modifiant le workspace +CREATE TABLE agent_actions ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + conversation_id INTEGER NOT NULL REFERENCES agent_conversations(id) ON DELETE CASCADE, + tool_name TEXT NOT NULL, + -- create_collection | create_page | add_property | ... + target_type TEXT, + -- collection | page | property | view | issue + target_id TEXT, + payload_json TEXT NOT NULL DEFAULT '{}', + result_json TEXT NOT NULL DEFAULT '{}', + status TEXT NOT NULL DEFAULT 'success', + -- success | error | reverted + -- Snapshot avant modification → permet le rollback + undo_snapshot_json TEXT DEFAULT '{}', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + executed_by INTEGER REFERENCES users(id) +); + +-- Skills réutilisables (mini-prompts) +CREATE TABLE agent_skills ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + workspace_id INTEGER REFERENCES workspaces(id), + name TEXT NOT NULL, + -- "Génération de PRD", "Analyse SWOT", "Préparation sprint" + description TEXT DEFAULT '', + prompt_template TEXT NOT NULL, + -- Outils que la skill peut invoquer + allowed_tools_json TEXT NOT NULL DEFAULT '[]', + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + created_by INTEGER REFERENCES users(id), + UNIQUE(workspace_id, name) +); + +CREATE INDEX idx_agent_conv_user ON agent_conversations(user_id, updated_at); +CREATE INDEX idx_agent_msg_conv ON agent_messages(conversation_id, created_at); +CREATE INDEX idx_agent_action_conv ON agent_actions(conversation_id); + + +Intégration au diagramme de relations existant + + +users ──1:N──► agent_conversations ──1:N──► agent_messages + │ │ + │ └──1:N──► agent_actions ──► (collections/pages/...) + │ +workspaces ──1:N──► agents ──1:N──► agent_conversations + │ + └──1:N──► agent_skills + +``` + + +## 8. Routes & API Agent {#8-routes--api} + +Nouveau router agent.py, préfixe /api/agent. + +# Agents (définitions) +``` +GET /api/agent → Liste agents du workspace +POST /api/agent → Créer custom agent +GET /api/agent/{agent_id} → Détail agent +PUT /api/agent/{agent_id} → Update (instructions, scope, model) +DELETE /api/agent/{agent_id} → Supprimer custom agent +``` + +# Conversations +``` +GET /api/agent/conversations → Historique des conversations +POST /api/agent/conversations → Nouvelle conversation +GET /api/agent/conversations/{id} → Messages d'une conversation +DELETE /api/agent/conversations/{id} → Supprimer conversation +``` + +# Exécution (cœur) +``` +POST /api/agent/conversations/{id}/run → Envoyer un objectif (SSE stream) + body: {message, model?, mentions?, files?, skill_id?} + → stream: reasoning → tool_call → tool_result → ... → final +``` + +# Actions & audit +``` +GET /api/agent/conversations/{id}/actions → Journal des actions +POST /api/agent/actions/{action_id}/undo → Annuler une action (rollback) +``` + +# Skills +``` +GET /api/agent/skills → Liste skills +POST /api/agent/skills → Créer skill +POST /api/agent/skills/{id}/apply → Appliquer une skill +``` + +# Custom agents — déclencheurs +``` +POST /api/agent/{agent_id}/trigger → Déclenchement manuel +``` + +# (déclenchement auto via scheduler interne + webhooks.py) + + +Streaming — La route /run renvoie un flux Server-Sent Events (SSE) pour afficher en temps réel le raisonnement et chaque action, à la manière de l'interface conversationnelle Notion. Le frontend (Alpine.js) consomme le flux et met à jour agent_panel.html. + +------------------------- + +## 9. Le service AgentEngine {#9-service-agentengine} + +Orchestrateur central. Pseudo-implémentation : + +``` +class AgentEngine: + """Orchestrateur ReAct pour FlowDeck Agent.""" + + def __init__(self, db, user, request): + self.db = db + self.user = user + self.request = request # pour réutiliser session/cookies + self.llm = LLMClient() + self.tools = ToolRegistry(db, user, request) + self.ctx = ContextBuilder(db, user) + self.perms = PermissionManager(db, user) + + async def run(self, conversation_id, objective, *, model=None, + mentions=None, files=None, skill_id=None): + agent = self._load_agent(conversation_id) + model = model or agent.model + + # 1. COMPRÉHENSION + instructions custom + skill + system = self._build_system_prompt(agent, skill_id) + + # 2. COLLECTE CONTEXTE (respecte permissions) + context = await self.ctx.build( + workspace=self._active_workspace(), + mentions=mentions, + files=files, + ) + + messages = [ + {"role": "system", "content": system}, + {"role": "user", "content": f"{objective}\n\n# Contexte\n{context}"}, + ] + + # 3-4. BOUCLE RAISONNEMENT ↔ ACTION + for _ in range(MAX_ITERATIONS): # défaut 12 + response = await self.llm.complete( + model=model, + messages=messages, + tools=self.tools.schema(scope=agent.scope), # function calling + stream=True, + ) + yield {"type": "reasoning", "content": response.text} + + if not response.tool_calls: + yield {"type": "final", "content": response.text} + break + + for call in response.tool_calls: + # Vérif permission AVANT exécution + self.perms.assert_can(call.tool, call.args) + + result = await self.tools.execute(call.tool, call.args) + + # Journal d'audit + snapshot rollback + self._log_action(conversation_id, call, result) + + yield {"type": "action", + "tool": call.tool, + "target": result.get("target"), + "status": result["status"]} + + messages.append({"role": "tool", + "name": call.tool, + "content": result}) + +``` + +Points clés : +- stream=True → SSE vers le frontend +- Chaque tool_call passe par PermissionManager.assert_can() avant exécution +- Chaque action modifiant la DB écrit un agent_actions avec undo_snapshot_json → rollback possible +- La boucle réutilise le même token Gitea que l'utilisateur (via user_tokens) +------------------------- + +10. Système d'outils (Tools) {#10-système-doutils} + +Les outils sont des wrappers autour des routers FastAPI existants — l'agent ne réinvente rien. + +| Outil | Route interne appelée | Ce que ça fait | +|-------|----------------------|----------------| +| `search_workspace` | `SearchEngine` (FTS5) | Recherche full-text pages/collections | +| `read_collection` | `GET /db/{id}` | Lit schéma + pages d'une collection | +| `read_page` | `GET /db/{c}/pages/{p}` | Lit une page + propriétés + blocs | +| `create_collection` | `POST /db` | Crée une database | +| `add_property` | `POST /db/{id}/properties` | Ajoute une propriété typée | +| `create_view` | `POST /db/{id}/views` | Crée une vue (table/board/calendar…) | +| `create_page` | `POST /db/{id}/pages` | Crée une page + valeurs propriétés | +| `update_page` | `PUT /db/{c}/pages/{p}` | Modifie propriétés/contenu | +| `write_blocks` | `POST /board/api/pages/{id}/blocks` | Écrit du contenu (éditeur de blocs) | +| `add_relation` | `POST /db/{id}/properties` (type relation) | Lie deux collections | +| `create_sub_item` | `POST /db/{c}/pages/{p}/sub-items` | Crée un sub-item | +| `add_dependency` | `POST /db/{c}/pages/{p}/dependencies` | Ajoute blocks/blocked_by | +| `sync_gitea` | `POST /board/api/sync/{o}/{r}` | Synchronise issues ↔ collection | +| `read_gitea_issues` | `GiteaClient` | Lit issues/labels/milestones | +| `create_gitea_issue` | `POST /api/issues/{o}/{r}` | Crée une issue Gitea | +| `apply_template` | `POST /db/{id}/templates/{t}/apply` | Applique un template | + + + +Schéma d'un outil (function calling) exposé au LLM : +``` +{ + "name": "create_page", + "description": "Crée une page dans une collection FlowDeck avec ses valeurs de propriétés.", + "parameters": { + "type": "object", + "properties": { + "collection_id": {"type": "integer"}, + "title": {"type": "string"}, + "property_values": { + "type": "object", + "description": "Map property_id → valeur (respecte le type)" + } + }, + "required": ["collection_id", "title"] + } +} +``` + +Filtrage par scope — Pour un custom agent, ToolRegistry.schema(scope=...) ne renvoie que les outils autorisés dans agents.scope_json.tools, et limite les cibles aux collections/repos de scope_json. + +------------------------- + +## 11. Permissions & sécurité {#11-permissions--sécurité} + +L'agent agit avec les permissions de l'utilisateur, jamais au-delà (principe Notion Agent : « mêmes permissions que l'utilisateur »). + +``` +┌───────────────────────────────────────────────────────────┐ +│ GARDE-FOUS AGENT │ +│ │ +│ 1. Identité → session utilisateur + user_tokens │ +│ 2. ACL → PermissionManager.assert_can() par outil│ +│ 3. Scope custom → scope_json limite collections/repos │ +│ 4. Database lock → collection is_locked ⇒ outils write KO │ +│ 5. Audit → agent_actions journalise TOUT │ +│ 6. Rollback → undo_snapshot_json par action │ +│ 7. Rate limiting → RateLimiter (middleware existant) │ +│ 8. Confirmation → actions destructives ⇒ approbation UI │ +└───────────────────────────────────────────────────────────┘ +``` + +Mode approbation — Configurable par agent : +- auto : l'agent exécute directement (création de contenu) +- confirm : actions destructives (delete_page, sync massif) demandent une confirmation dans le panneau avant exécution +Cohérent avec le modèle de rôles workspace (owner/admin/editor/commenter/viewer, ARCHITECTURE §6.2) : un agent lancé par un viewer ne peut que lire. + +------------------------- + +## 12. Custom Agents & déclencheurs {#12-custom-agents} + +Comme Notion (Custom Agents 2026), FlowDeck distingue : +| Type | Portée | Exemple | +|------|--------|---------| +| **Personal Agent** | Généraliste, tout le workspace visible | Assistant quotidien | +| **Custom Agent** | Spécialisé, scope restreint, déclencheurs | Agent Reporting, Agent Support | + + + +Déclencheurs (agents.trigger_json) : +``` +type: "manual" → bouton dans l'UI +type: "schedule" → cron interne (ex: "0 9 * * 1" = lundi 9h) +type: "webhook" → branché sur webhooks.py (issue.opened, issue.closed…) +``` + +Exemples de custom agents FlowDeck : +- Agent Reporting — chaque lundi, scanne toutes les collections, produit une page « Rapport hebdo » avec KPI +- Agent Gitea Triage — à issue.opened, classe l'issue dans la bonne collection et remplit ses propriétés +- Agent Sprint — prépare une collection sprint depuis les issues du milestone courant +Le scheduler s'appuie sur le lifespan FastAPI (main.py) et les webhooks réutilisent le router webhooks.py existant. + +------------------------- + +## 13. Skills réutilisables {#13-skills} + +Une skill est un mini-prompt paramétrable + liste d'outils autorisés (table agent_skills). +``` +Skill "Préparation de sprint" +├─ prompt_template: +│ "Analyse les issues ouvertes du repo {repo}, crée une collection +│ sprint '{sprint_name}', ajoute les propriétés Status/Priority/Assignee, +│ importe chaque issue comme page, groupe en vue Board." +├─ allowed_tools: [read_gitea_issues, create_collection, +│ add_property, create_page, create_view] +└─ Invocation: POST /api/agent/skills/{id}/apply +``` + +Autres skills livrées par défaut : Analyse SWOT, Génération de compte-rendu, Génération de PRD, Synthèse GitHub/Gitea. + +------------------------- + +## 14. Cas d'usage FlowDeck {#14-cas-dusage} + +Gestion de produit + +> « Crée une roadmap Q3 à partir des issues du repo bruno/flowdeck » + +``` +L'agent : read_gitea_issues → create_collection("Roadmap Q3") → add_property(Status, Priority, DueDate) → create_page × N → create_view(timeline). +Développement logiciel +``` + +> « Analyse les bugs des 6 derniers mois et crée un plan d'amélioration » + +``` +sync_gitea → search_workspace → analyse LLM → create_collection("Plan qualité") → create_page (causes, actions) → add_dependency. +Direction +``` + +> « Génère les OKR du prochain trimestre depuis nos objectifs actuels » + +``` +read_collection(Objectifs) → raisonnement → create_collection("OKR Q4") → create_page × N. +Multi-étapes (comme Notion) +``` + +> « Résume les notes de réunion du trimestre et crée les tâches de suivi » + +``` +search_workspace(meetings) → synthèse → write_blocks (page résumé) → create_page × N (tâches) dans la collection Tasks. +``` + +------------------------- + +## 15. Plan de migration {#15-plan-de-migration} + +Phase 1 — Fondations DB & Service + 1. Créer tables agents, agent_conversations, agent_messages, + agent_actions, agent_skills + 2. Implémenter LLMClient (abstraction multi-provider) + 3. Implémenter ContextBuilder (réutilise SearchEngine) + +Phase 2 — Tool-calling + 1. ToolRegistry : wrappers read-only d'abord (search, read_*) + 2. Ajouter outils write (create_collection, create_page, ...) + 3. Brancher PermissionManager.assert_can() sur chaque outil + 4. Journal agent_actions + snapshots rollback + +Phase 3 — Interface + 1. agent_panel.html (Alpine.js) branché sur section 🤖 Agents + 2. Streaming SSE (/run) + 3. Icône flottante coin inférieur droit + 4. Affichage temps réel reasoning + actions + +Phase 4 — Personnalisation + 1. Instructions custom par agent + 2. Skills (table + /apply) + 3. Sélecteur de modèle (GPT/Claude/Gemini/Ollama) + +Phase 5 — Custom Agents + 1. Scope + trigger_json + 2. Scheduler (lifespan FastAPI) + 3. Déclencheurs webhook (via webhooks.py) + 4. Mode approbation (auto/confirm) + + +------------------------- + +## 16. Limitations {#16-limitations} + +Alignées sur les limites connues de Notion Agent, adaptées à FlowDeck. L'agent ne peut pas : +- Modifier les paramètres du workspace (/workspace/{id}/settings) +- Gérer les membres / rôles (workspace_members) +- Gérer l'authentification ou les intégrations OAuth (connexion/déconnexion Gitea/GitHub) +- Publier ou partager publiquement une page sans confirmation utilisateur (/api/pages/{id}/publish, /share) +- Modifier une collection verrouillée (is_locked = 1) +- Agir au-delà des permissions de l'utilisateur qui l'invoque +- Supprimer définitivement (hard delete) sans mode confirm +------------------------- + +Résumé + +FlowDeck Agent porte le modèle Notion Agent dans FlowDeck en réutilisant l'infrastructure existante : +- Un service AgentEngine orchestrant une boucle ReAct (raisonnement ↔ action) +- Des outils qui sont de simples wrappers des routers FastAPI existants (/db/*, /board/api/*, Gitea) +- Un contexte collecté via SearchEngine + GiteaClient, filtré par PermissionManager +- Un audit complet (agent_actions) avec rollback +- Custom Agents, skills et déclencheurs pour l'automatisation +Le passage de « l'IA qui répond » à « l'IA qui réalise le travail » se fait sans réécrire FlowDeck : l'agent agit comme un utilisateur privilégié mais contraint, à travers les mêmes portes que l'interface humaine. + + +J'ai créé le document `Flowdeck_Agent_integration.md`. Points saillants de l'intégration proposée : + +- **Réutilisation maximale** : l'agent n'accède jamais directement à SQLite — il appelle les routers FastAPI existants (`/db/*`, `/board/api/*`, `GiteaClient`), ce qui garantit validation, cohérence et respect du `PermissionManager`. + +- **Boucle ReAct** : Compréhension → Contexte → Raisonnement → Action, calquée sur le fonctionnement de Notion Agent mais mappée sur vos entités (`collections`, `collection_pages`, issues Gitea). + +- **5 nouvelles tables** seulement (`agents`, `agent_conversations`, `agent_messages`, `agent_actions`, `agent_skills`), plus un router `agent.py` et 4 services. + +- **Sécurité** : audit complet avec `undo_snapshot_json` pour rollback, respect des rôles workspace, mode `confirm` pour les actions destructives. + +- **Custom Agents + Skills + déclencheurs** (cron via `lifespan`, webhooks via votre `webhooks.py` existant). diff --git a/docs/Guide_Complet_Notion_Agent_2026.md b/docs/Guide_Complet_Notion_Agent_2026.md new file mode 100644 index 0000000..460ba0b --- /dev/null +++ b/docs/Guide_Complet_Notion_Agent_2026.md @@ -0,0 +1,464 @@ +# Guide complet — Notion Agent (2026) + +## Introduction + +Notion Agent est l'évolution la plus avancée de Notion AI. Contrairement à un assistant conversationnel classique qui répond uniquement à des questions, Notion Agent est conçu pour **agir directement dans votre espace de travail**. + +L'objectif est de transformer l'IA d'un simple outil de rédaction en un véritable collaborateur numérique capable d'exécuter des tâches complètes à travers les pages, bases de données et outils connectés. + +--- + +# 1. Qu'est-ce que Notion Agent ? + +Notion Agent est un agent IA intégré nativement dans Notion. + +Il possède : + +- Un accès au contexte de votre espace de travail +- La capacité de lire des pages et bases de données +- La capacité de créer et modifier du contenu +- La possibilité d'effectuer des tâches multi‑étapes +- L'accès à certaines sources externes et outils connectés + +Conceptuellement : + +Assistant IA traditionnel : +Utilisateur → Prompt → Réponse + +Notion Agent : +Utilisateur → Objectif → Planification → Recherche → Actions → Résultat + +L'agent agit davantage comme un employé numérique que comme un chatbot. + +--- + +# 2. Où apparaît-il dans l'interface ? + +## Emplacement principal + +Notion affiche l'agent sous la forme d'une icône circulaire représentant un visage. + +Position habituelle : + +- Coin inférieur droit de l'écran + +Ou : + +- Section AI dans la barre latérale gauche + +--- + +## Interface de conversation + +Lorsque l'utilisateur ouvre l'agent : + +┌──────────────────────────┐ +│ Conversation Agent │ +├──────────────────────────┤ +│ Historique │ +│ │ +│ Réponses │ +│ │ +├──────────────────────────┤ +│ @Sources │ +│ 📎 Fichier │ +│ Modèle IA │ +│ Zone de saisie │ +└──────────────────────────┘ + +L'interface ressemble à ChatGPT mais avec davantage de contrôles contextuels. + +--- + +# 3. Comment fonctionne l'agent ? + +## Étape 1 : Compréhension + +L'utilisateur formule un objectif. + +Exemples : + +- Construis un CRM. +- Résume les notes de réunion du trimestre. +- Crée les OKR du prochain trimestre. + +L'agent interprète l'intention. + +--- + +## Étape 2 : Collecte du contexte + +Il récupère automatiquement : + +- La page actuelle +- Les blocs sélectionnés +- Les bases de données liées +- Les documents référencés +- Les permissions utilisateur + +Il fonctionne avec les mêmes permissions que l'utilisateur. + +--- + +## Étape 3 : Raisonnement + +L'agent décompose la demande. + +Exemple : + +Créer un CRM + +→ déterminer les propriétés +→ créer la base +→ créer les vues +→ créer les relations +→ générer des exemples + +--- + +## Étape 4 : Action + +L'agent modifie directement Notion. + +Contrairement à un chatbot traditionnel, il peut : + +- créer +- modifier +- organiser +- restructurer + +le contenu. + +--- + +# 4. Sources de connaissances + +## Sources Notion + +L'agent peut consulter : + +- Pages +- Sous-pages +- Bases de données +- Wikis +- Documents internes + +--- + +## Sources connectées + +Selon la configuration du workspace : + +- Jira +- Slack +- Google Drive +- GitHub +- Figma +- Outils connectés compatibles + +--- + +## Fichiers + +L'utilisateur peut joindre : + +- PDF +- Documents +- Présentations +- Fichiers importés + +--- + +## Mention manuelle + +L'utilisateur peut préciser : + +@Projet Alpha + +ou + +@Équipe Marketing + +pour forcer l'utilisation d'un contexte particulier. + +--- + +# 5. Ce que Notion Agent peut faire + +## Création de contenu + +- Pages +- Sous-pages +- Documentation +- SOP +- Guides +- Rapports +- Comptes-rendus + +--- + +## Modification de contenu + +- Réécriture +- Résumé +- Traduction +- Simplification +- Restructuration + +--- + +## Bases de données + +L'agent peut : + +- créer une base +- ajouter des propriétés +- ajouter des relations +- créer des vues +- remplir les données + +--- + +## Recherche documentaire + +Il peut analyser : + +- des centaines de pages +- plusieurs bases de données +- des documents attachés + +pour produire un résultat consolidé. + +--- + +## Analyse + +Exemples : + +- Identifier les tendances +- Comparer des projets +- Détecter les risques +- Produire des synthèses exécutives + +--- + +## Travail multi‑étapes + +Exemple : + +« Analyse les incidents des 6 derniers mois et crée un plan d'amélioration. » + +L'agent : + +1. collecte les incidents +2. les analyse +3. identifie les causes +4. produit un rapport +5. crée les tâches + +--- + +# 6. Fonctionnalités avancées + +## Changement de modèle IA + +Le sélecteur de modèle permet selon la disponibilité : + +- GPT +- Claude +- Gemini +- autres modèles partenaires + +Certains modèles peuvent n'utiliser que le Web alors que d'autres exploitent le contexte Notion. + +--- + +## Historique + +L'agent conserve l'historique des conversations. + +Permet : + +- reprendre un travail +- relancer une tâche +- réutiliser un contexte + +--- + +## Instructions personnalisées + +L'utilisateur peut définir : + +- ton +- style +- format +- règles métier + +Exemple : + +« Toujours écrire les procédures en format SOP. » + +--- + +## Skills + +Notion introduit des compétences réutilisables. + +Une skill agit comme un mini‑prompt réutilisable. + +Exemples : + +- Génération de compte-rendu +- Analyse SWOT +- Préparation de sprint + +--- + +# 7. Ce que l'agent ne peut pas faire + +À ce jour, certaines limitations existent. + +Il ne peut généralement pas : + +- modifier les permissions des pages +- partager des pages +- gérer la facturation +- modifier les paramètres du workspace +- créer certaines propriétés avancées complexes +- créer des rappels système + +--- + +# 8. Différence entre Notion AI et Notion Agent + +## Notion AI (ancienne approche) + +- Répond +- Résume +- Réécrit + +## Notion Agent + +- Planifie +- Recherche +- Agit +- Modifie le workspace +- Réalise des tâches complètes + +--- + +# 9. Custom Agents (2026) + +Notion a également lancé les Custom Agents. + +Différence : + +Notion Agent : +- Agent personnel généraliste + +Custom Agent : +- Agent spécialisé + +Exemples : + +- Agent RH +- Agent Support +- Agent Produit +- Agent Marketing +- Agent GitHub +- Agent Reporting + +Ces agents peuvent fonctionner automatiquement selon des déclencheurs et horaires. + +--- + +# 10. Cas d'usage réels + +## Gestion de produit + +- Générer des PRD +- Créer des roadmaps +- Analyser Jira + +## Développement logiciel + +- Synthèse GitHub +- Documentation technique +- Suivi des bugs + +## Marketing + +- Rapports de campagne +- Veille concurrentielle +- Création de contenu + +## Direction + +- OKR +- KPI +- Rapports exécutifs + +--- + +# 11. Architecture conceptuelle + +Utilisateur + ↓ +Notion Agent + ↓ +Contexte Workspace + ↓ +Sources Connectées + ↓ +Moteur IA + ↓ +Planification + ↓ +Actions Notion + ↓ +Résultat + +--- + +# 12. Vision produit + +Notion cherche à transformer son produit en système d'exploitation du travail. + +L'évolution observée : + +2018 → Notes + +2020 → Bases de données + +2023 → Notion AI + +2025 → Notion Agent + +2026 → Custom Agents + +Direction probable : + +- équipes d'agents spécialisés +- automatisation continue +- orchestration inter‑outils +- assistants autonomes de projet + +--- + +# Résumé + +Notion Agent est un agent IA intégré profondément dans Notion. + +Ses caractéristiques majeures : + +- Compréhension du contexte +- Accès aux connaissances du workspace +- Raisonnement multi‑étapes +- Création et modification de contenu +- Gestion des bases de données +- Analyse documentaire +- Personnalisation via instructions et skills +- Intégration avec outils externes +- Possibilité d'évoluer vers des agents spécialisés + +Il représente le passage de « l'IA qui répond » à « l'IA qui réalise le travail » directement dans l'environnement Notion. diff --git a/images/chat/Notion_chat_main_page.png b/images/chat/Notion_chat_main_page.png new file mode 100644 index 0000000..59aa831 Binary files /dev/null and b/images/chat/Notion_chat_main_page.png differ