flowdeck/docs/Flowdeck_Agent_integration.md

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
2. Concept : de l'IA qui répond à l'IA qui réalise
3. Positionnement dans l'architecture FlowDeck
4. Placement dans l'interface (sidebar 🤖 Agents)
5. Boucle d'exécution de l'agent
6. Sources de contexte FlowDeck
7. Modèle de données (nouvelles tables)
8. Routes & API Agent
9. Le service AgentEngine
10. Système d'outils (Tools)
11. Permissions & sécurité
12. Custom Agents & déclencheurs
13. Skills réutilisables
14. Cas d'usage FlowDeck
15. Plan de migration
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

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

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)

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

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

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)

-- 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

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

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é

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

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

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

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

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

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).