mirror of
https://github.com/R0m1k3/TodoFlow.git
synced 2026-10-13 18:29:27 +02:00
384 lines
12 KiB
Markdown
384 lines
12 KiB
Markdown
# 🤖 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 :
|
|
```http
|
|
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 :
|
|
```json
|
|
[
|
|
{
|
|
"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) :**
|
|
```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) :**
|
|
```json
|
|
{
|
|
"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) :**
|
|
```json
|
|
{
|
|
"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` :
|
|
|
|
```python
|
|
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)
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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)
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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'."*
|