TodoFlow/server/README_AI_AGENT.md

🤖 Guide d'Intégration pour Agent IA - TodoFlow API

Ce guide explique comment un Agent d'Intelligence Artificielle (comme un assistant autonome, un agent de codage ou un script LLM) peut se connecter, comprendre et piloter la Todo List centralisée de l'utilisateur.

---

🔑 1. Authentification & Sécurité

Pour toutes les requêtes HTTP, l'Agent IA doit s'authentifier en fournissant la clé API configurée dans l'en-tête X-API-Key.

En-tête HTTP Requis :

X-API-Key: ai-agent-token-secure-101

Note : La clé par défaut pour l'agent IA dans la configuration de production est ai-agent-token-secure-101, mais elle peut être personnalisée via la variable d'environnement API_KEYS_RAW du conteneur Docker.

---

📐 2. Découverte Automatique (OpenAPI / Swagger)

L'API TodoFlow a été conçue avec FastAPI, ce qui signifie qu'elle génère dynamiquement une spécification OpenAPI standard au format JSON.

Endpoints de Découverte :

• Schéma OpenAPI JSON : http://<IP_SERVEUR>:8000/openapi.json (Idéal pour qu'un LLM lise et comprenne la structure des données et des routes de manière autonome)
• Documentation Swagger Interactive : http://<IP_SERVEUR>:8000/docs

---

📋 3. Spécifications des Opérations (CRUD)

A. Récupérer toutes les tâches (GET /api/v1/tasks)

Permet à l'Agent IA de lire la liste de tâches actuelle. Il peut filtrer les tâches par statut.

• Query Parameters (Optionnel) :
  • status : Peut être "A faire", "En cours" ou "Termine".
• Réponse (200 OK) : Une liste d'objets au format suivant :

  [
    {
      "id": "e1a77ff0-2c32-4f37-baef-e68b903f806e",
      "title": "Acheter du pain",
      "description": null,
      "status": "A faire",
      "created_at": "2026-05-26T14:15:30Z",
      "updated_at": "2026-05-26T14:15:30Z"
    }
  ]
  

B. Créer une nouvelle tâche (POST /api/v1/tasks)

Permet à l'Agent IA d'ajouter un nouvel objectif pour l'utilisateur.

• Request Body (JSON) :

  {
    "title": "Préparer la réunion de projet",
    "description": "Rédiger l'ordre du jour et préparer les diapositives",
    "status": "A faire"
  }
  

• Réponse (201 Created) : Renvoie l'objet créé avec son UUID unique généré par le serveur et son horodatage de création (created_at).

C. Récupérer les détails d'une tâche (GET /api/v1/tasks/{id})

Permet à l'Agent IA d'obtenir les informations complètes d'une tâche spécifique à partir de son UUID.

• Réponse (200 OK) :

  {
    "id": "e1a77ff0-2c32-4f37-baef-e68b903f806e",
    "title": "Acheter du pain",
    "description": "Prendre une tradition bien cuite",
    "status": "A faire",
    "created_at": "2026-05-26T14:15:30Z",
    "updated_at": "2026-05-26T14:15:30Z"
  }
  

• Réponse (404 Not Found) : Si aucune tâche ne correspond à l'identifiant fourni.

D. Mettre à jour une tâche (PUT /api/v1/tasks/{id})

Permet à l'Agent IA de marquer une tâche comme "En cours" ou "Termine", ou d'en modifier le titre/description.

• Request Body (JSON - Mise à jour partielle acceptée) :

  {
    "status": "En cours"
  }
  

• Réponse (200 OK) : Renvoie l'objet mis à jour avec son nouvel horodatage updated_at.

E. Supprimer une tâche (DELETE /api/v1/tasks/{id})

Permet à l'Agent IA de nettoyer la liste en supprimant une tâche.

• Réponse (204 No Content) : Succès de la suppression (aucun corps de réponse).

---

🐍 4. Exemple d'implémentation en Python pour l'Agent IA

Voici un script simple montrant comment un Agent IA peut interagir avec l'API en utilisant la bibliothèque requests :

import requests

API_URL = "http://localhost:8000/api/v1"
API_KEY = "ai-agent-token-secure-101"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# 1. Lire toutes les tâches actives
response = requests.get(f"{API_URL}/tasks", headers=headers)
if response.status_code == 200:
    tasks = response.json()
    print(f"L'utilisateur a {len(tasks)} tâches au total.")

# 2. Créer une nouvelle tâche pour l'utilisateur
new_task = {
    "title": "Analyser les performances de la stack",
    "description": "Tâche générée automatiquement par l'Agent IA",
    "status": "A faire"
}
create_resp = requests.post(f"{API_URL}/tasks", json=new_task, headers=headers)
if create_resp.status_code == 201:
    created_task = create_resp.json()
    task_id = created_task["id"]
    print(f"Tâche créée par l'IA avec succès ! ID: {task_id}")

    # 3. Passer cette tâche "En cours"
    update_resp = requests.put(
        f"{API_URL}/tasks/{task_id}", 
        json={"status": "En cours"}, 
        headers=headers
    )
    if update_resp.status_code == 200:
        print("La tâche a été marquée 'En cours' par l'IA.")

---

🛠️ 5. Définition des Outils pour Agents IA (Function Calling)

Si vous configurez un agent IA externe utilisant les API d'OpenAI, Anthropic ou Gemini, vous pouvez copier-coller les schémas de fonctions ci-dessous pour lui donner un accès direct et natif à la Todo List.

A. Format OpenAI / Gemini (JSON Schema)

[
  {
    "type": "function",
    "function": {
      "name": "get_tasks",
      "description": "Récupère la liste de toutes les tâches stockées dans TodoFlow. Permet de filtrer optionnellement par statut.",
      "parameters": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["A faire", "En cours", "Termine"],
            "description": "Filtre optionnel pour récupérer uniquement les tâches ayant ce statut ('A faire', 'En cours', 'Termine')."
          }
        }
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "get_task",
      "description": "Récupère les détails précis d'une tâche existante à partir de son UUID.",
      "parameters": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "format": "uuid",
            "description": "L'UUID unique de la tâche à récupérer."
          }
        },
        "required": ["task_id"]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "create_task",
      "description": "Crée une nouvelle tâche dans la Todo list.",
      "parameters": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Le titre court et descriptif de la tâche (ex: 'Acheter du pain')."
          },
          "description": {
            "type": "string",
            "description": "Description détaillée de la tâche ou consignes supplémentaires."
          },
          "status": {
            "type": "string",
            "enum": ["A faire", "En cours", "Termine"],
            "default": "A faire",
            "description": "Le statut initial de la tâche (par défaut 'A faire')."
          }
        },
        "required": ["title"]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "update_task",
      "description": "Met à jour une tâche existante (modifier le titre, la description, ou changer de statut comme passer à 'En cours' ou 'Termine').",
      "parameters": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "format": "uuid",
            "description": "L'UUID unique de la tâche à modifier."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Nouveau titre pour la tâche."
          },
          "description": {
            "type": "string",
            "description": "Nouvelle description pour la tâche."
          },
          "status": {
            "type": "string",
            "enum": ["A faire", "En cours", "Termine"],
            "description": "Nouveau statut pour la tâche."
          }
        },
        "required": ["task_id"]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "delete_task",
      "description": "Supprime définitivement une tâche de la liste à partir de son UUID.",
      "parameters": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "format": "uuid",
            "description": "L'UUID unique de la tâche à supprimer."
          }
        },
        "required": ["task_id"]
      }
    }
  }
]

B. Format Anthropic / Claude (Messages API Tools)

[
  {
    "name": "get_tasks",
    "description": "Récupère la liste de toutes les tâches stockées dans TodoFlow. Permet de filtrer optionnellement par statut.",
    "input_schema": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": ["A faire", "En cours", "Termine"],
          "description": "Filtre optionnel pour récupérer uniquement les tâches ayant ce statut."
        }
      }
    }
  },
  {
    "name": "get_task",
    "description": "Récupère les détails précis d'une tâche existante à partir de son UUID.",
    "input_schema": {
      "type": "object",
      "properties": {
        "task_id": {
          "type": "string",
          "format": "uuid",
          "description": "L'UUID unique de la tâche à récupérer."
        }
      },
      "required": ["task_id"]
    }
  },
  {
    "name": "create_task",
    "description": "Crée une nouvelle tâche dans la Todo list.",
    "input_schema": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Le titre court et descriptif de la tâche."
        },
        "description": {
          "type": "string",
          "description": "Description détaillée de la tâche."
        },
        "status": {
          "type": "string",
          "enum": ["A faire", "En cours", "Termine"],
          "default": "A faire",
          "description": "Le statut initial de la tâche."
        }
      },
      "required": ["title"]
    }
  },
  {
    "name": "update_task",
    "description": "Met à jour une tâche existante par son UUID (modifier le titre, la description, ou changer de statut).",
    "input_schema": {
      "type": "object",
      "properties": {
        "task_id": {
          "type": "string",
          "format": "uuid",
          "description": "L'UUID unique de la tâche à modifier."
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Nouveau titre pour la tâche."
        },
        "description": {
          "type": "string",
          "description": "Nouvelle description."
        },
        "status": {
          "type": "string",
          "enum": ["A faire", "En cours", "Termine"],
          "description": "Nouveau statut."
        }
      },
      "required": ["task_id"]
    }
  },
  {
    "name": "delete_task",
    "description": "Supprime définitivement une tâche de la liste à partir de son UUID.",
    "input_schema": {
      "type": "object",
      "properties": {
        "task_id": {
          "type": "string",
          "format": "uuid",
          "description": "L'UUID unique de la tâche à supprimer."
        }
      },
      "required": ["task_id"]
    }
  }
]

---

💡 Conseils pour le Prompt System de l'Agent IA

Si vous intégrez cette API à un LLM (comme GPT-4 ou Gemini), vous pouvez ajouter cette consigne dans son System Prompt :

"Tu es un Agent IA assistant personnel. Tu as accès à l'API de gestion des tâches de l'utilisateur. Pour piloter sa liste, tu dois faire des appels REST sur l'API en utilisant l'en-tête X-API-Key: ai-agent-token-secure-101. Découvre les spécifications exactes de l'API en interrogeant /openapi.json. Assure-toi de respecter les statuts valides : 'A faire', 'En cours', 'Termine'."