Tutoriel : Créer un agent IA qui délègue des tâches du monde réel à des humains
L'une des capacités les plus puissantes émergeant en 2026 est la possibilité pour les agents IA de déléguer des tâches du monde physique à des opérateurs humains vérifiés. Au lieu d'être limités à ce qu'ils peuvent accomplir via des API numériques, les agents IA peuvent désormais demander des actions concrètes comme photographier un lieu, vérifier une livraison, inspecter un équipement ou collecter des documents. Ce tutoriel vous guide dans la création d'un agent IA complet qui fait exactement cela, de la configuration au déploiement en production.
Nous allons construire un exemple d'agent qui surveille les plateformes d'avis de restaurants, détecte les problèmes potentiels comme des signalements de fermeture ou des violations du code de la santé, et dépêche automatiquement un opérateur humain sur le lieu physique pour vérifier la situation et soumettre des preuves photographiques. L'agent traitera ensuite les résultats de la vérification et prendra les mesures appropriées en fonction des conclusions. Cela représente un cas d'utilisation réaliste pour les entreprises ayant besoin d'une vérification de la vérité terrain des informations en ligne.
Le tutoriel couvre deux méthodes d'intégration : l'API REST de HumanOps pour une flexibilité maximale et une intégration indépendante du langage, et le serveur MCP de HumanOps pour une intégration native avec Claude, Cursor et d'autres agents IA compatibles MCP. Les deux méthodes offrent les mêmes capacités de base, et le choix entre elles dépend de l'architecture de votre agent. Tous les exemples de code sont en TypeScript, mais les concepts de l'API REST s'appliquent à n'importe quel langage de programmation.
À la fin de ce tutoriel, vous disposerez d'un agent fonctionnel capable de créer des tâches, de les assigner à des opérateurs humains, de recevoir des soumissions de preuves, de vérifier les résultats de la vérification et de gérer le cycle de vie complet des tâches de manière programmatique. Vous comprendrez également comment étendre cette base avec des intégrations de webhooks, la création de tâches par lots et la gestion des priorités pour les vérifications urgentes.
Prérequis et configuration
Avant de commencer, vous avez besoin d'un compte HumanOps avec une clé API. Inscrivez-vous sur humanops.io, terminez le processus d'intégration et accédez à la page des paramètres API pour générer votre première clé. La clé ne sera affichée qu'une seule fois, stockez-la donc en toute sécurité dans une variable d'environnement. Pour ce tutoriel, nous utiliserons la variable d'environnement HUMANOPS_API_KEY.
Vous avez également besoin de Node.js version 18 ou ultérieure installé sur votre machine de développement. Nous utiliserons TypeScript pour la sécurité des types et une meilleure expérience de développement, mais les exemples d'API REST peuvent être adaptés à tout langage capable d'effectuer des requêtes HTTP. Créez un nouveau répertoire de projet et initialisez-le avec npm init, puis installez les dépendances nécessaires : typescript, tsx pour exécuter TypeScript directement, et node-fetch si vous êtes sur Node 18 sans support natif de fetch.
Pour l'intégration du serveur MCP, vous aurez besoin d'un hôte compatible MCP comme Claude Desktop, Cursor ou toute application prenant en charge le Model Context Protocol. Le serveur MCP de HumanOps est disponible sous forme de package npm qui s'exécute localement sur votre machine et se connecte à l'API HumanOps à l'aide de votre clé API. Nous aborderons la configuration MCP dans une section dédiée plus loin dans ce tutoriel.
L'environnement de test HumanOps fournit un bac à sable où les tâches sont résolues instantanément avec des opérateurs fictifs. Cela signifie que vous pouvez développer et tester l'intégralité de votre intégration sans dépenser de vrais USDC ni attendre que des opérateurs humains réels terminent les tâches. Lorsque vous êtes prêt pour la production, remplacez votre clé API de test par une clé de production et le même code fonctionnera avec de vrais opérateurs.
Fondamentaux de l'API REST
L'API REST de HumanOps est hébergée sur api.humanops.io et accepte des corps de requête JSON avec des réponses au format JSON. L'authentification est gérée via l'en-tête X-API-Key, qui doit être inclus dans chaque requête. L'API suit les conventions REST : POST pour créer des ressources, GET pour les lire, PUT pour les mises à jour, et les codes d'état HTTP standard pour les réponses de succès et d'erreur.
Commençons par l'opération la plus fondamentale : la création d'une tâche. Une tâche nécessite une description indiquant à l'opérateur ce qu'il doit faire, un emplacement spécifiant où la tâche doit être effectuée, un montant de récompense en USDC et une date limite avant laquelle la tâche doit être terminée. Voici une fonction TypeScript qui crée une tâche via l'API REST. La fonction prend les paramètres de la tâche, envoie une requête POST au point de terminaison des tâches et renvoie l'objet de tâche créé, incluant son identifiant unique, son statut et la référence de la transaction d'entiercement.
La réponse de création de tâche comprend plusieurs champs importants. L'identifiant de la tâche (task ID) est utilisé pour référencer cette tâche spécifique dans tous les appels API ultérieurs. Le champ status indique l'état actuel de la tâche, qui commence par POSTED lorsque la tâche est disponible pour les opérateurs. L'identifiant escrow_tx_id fait référence à la transaction du grand livre qui a déplacé les fonds du compte de dépôt de votre agent vers le compte d'entiercement, confirmant que la tâche est entièrement financée. L'horodatage created_at enregistre exactement le moment où la tâche a été créée.
Une fois qu'une tâche est publiée, les opérateurs peuvent la parcourir et la réclamer en soumettant une estimation de temps. Votre agent sera informé de l'estimation soit en interrogeant le point de terminaison de la tâche, soit en recevant une notification par webhook. L'estimation inclut l'ID de l'opérateur, son délai d'exécution estimé et son niveau de confiance. Votre agent doit approuver ou rejeter l'estimation en fonction des qualifications de l'opérateur et de l'urgence de la tâche.
Construction de l'agent de surveillance de restaurant
Voici l'implémentation TypeScript complète de notre agent de surveillance de restaurant. Ce code démontre le cycle de vie complet d'une tâche : création d'une tâche de vérification, surveillance des estimations des opérateurs, approbation d'une estimation et récupération du résultat de la vérification.
L'agent est structuré autour d'une classe HumanOpsClient qui encapsule toutes les interactions API. La méthode createVerificationTask publie une nouvelle tâche avec une description adaptée à la vérification de restaurant, incluant des instructions spécifiques sur les photos à prendre et les éléments à observer. La description est cruciale car elle indique à la fois à l'opérateur et à l'AI Guardian ce qui constitue une exécution réussie. Une description de tâche bien rédigée conduit à de meilleures soumissions de preuves et à une vérification automatisée plus précise.
La méthode waitForEstimate illustre la surveillance des tâches basée sur l'interrogation (polling). En production, vous utiliseriez généralement des webhooks au lieu de l'interrogation, mais l'interrogation est plus simple à des fins de démonstration et fonctionne bien pour les agents traitant un petit nombre de tâches. La méthode vérifie le statut de la tâche toutes les trente secondes, cherchant la transition de POSTED à ESTIMATED, ce qui indique qu'un opérateur a soumis une estimation de temps et est prêt à commencer le travail.
La méthode approveEstimate autorise l'opérateur à commencer la tâche. Après approbation, le statut de la tâche passe à IN_PROGRESS et l'opérateur a jusqu'à la date limite pour soumettre les preuves. La méthode getResult récupère la tâche terminée, incluant le score de vérification de l'AI Guardian, l'URL de la preuve et le détail de la vérification. Votre agent peut utiliser ces informations pour prendre des décisions concernant le restaurant, comme mettre à jour son statut dans votre base de données ou déclencher des actions de suivi.
La gestion des erreurs est intégrée à chaque appel API. Les échecs réseau sont capturés et journalisés avec des messages explicites. Les réponses d'erreur HTTP sont analysées pour extraire le code d'erreur et la description de l'API. Les réponses de limite de débit incluent la valeur de l'en-tête retry-after afin que votre agent puisse temporiser de manière appropriée. Ce style de codage défensif est essentiel pour les agents de production qui doivent fonctionner de manière fiable sans supervision humaine.
Intégration du serveur MCP
Le serveur MCP de HumanOps offre une voie d'intégration alternative particulièrement puissante pour les agents IA fonctionnant dans des environnements compatibles MCP comme Claude Desktop et Cursor. Au lieu d'effectuer des requêtes HTTP et d'analyser des réponses JSON, votre agent peut appeler les opérations HumanOps comme des outils natifs, ce qui rend l'intégration naturelle et réduit la quantité de code répétitif à écrire.
Pour configurer le serveur MCP, installez le package humanops-mcp-server globalement ou ajoutez-le aux dépendances de votre projet. Ajoutez ensuite la configuration du serveur au fichier de configuration de votre hôte MCP. Pour Claude Desktop, cela signifie ajouter une entrée à la section mcpServers de votre configuration avec la commande pour démarrer le serveur et la variable d'environnement contenant votre clé API. La configuration complète tient en trois lignes : le chemin de la commande, le tableau d'arguments et l'objet env avec votre HUMANOPS_API_KEY.
Une fois configuré, votre agent IA accède à quatre outils principaux : post_task pour créer de nouvelles tâches avec des paramètres de description, de lieu, de récompense et de date limite ; approve_estimate pour autoriser un opérateur à commencer le travail sur une tâche ; get_task_result pour récupérer la tâche terminée avec les résultats de vérification ; et check_verification_status pour surveiller la progression de l'analyse de l'AI Guardian. Chaque outil accepte des paramètres structurés et renvoie des réponses typées, éliminant le besoin d'analyse JSON manuelle.
L'intégration MCP est particulièrement puissante pour les agents IA conversationnels. Un agent s'exécutant dans Claude peut naturellement décider au cours d'une conversation qu'il a besoin d'une vérification dans le monde physique, appeler l'outil post_task pour créer la tâche, puis plus tard dans la conversation appeler get_task_result pour récupérer et analyser la vérification. Cela crée un flux de travail fluide où l'agent réfléchit à ce qui doit être fait, délègue le travail physique à un humain et traite le résultat, le tout au sein d'un seul fil de conversation.
Intégration des webhooks pour des mises à jour en temps réel
Bien que l'interrogation fonctionne pour les agents simples, les déploiements en production devraient utiliser des webhooks pour les notifications en temps réel du cycle de vie des tâches. Les webhooks HumanOps envoient des requêtes HTTP POST signées par HMAC-SHA256 à votre point de terminaison chaque fois qu'un événement significatif se produit dans le cycle de vie d'une tâche. Cela élimine la latence et le gaspillage de ressources de l'interrogation périodique et garantit que votre agent réponde aux événements le plus rapidement possible.
Pour configurer les webhooks, enregistrez une URL de point de terminaison via l'API ou le tableau de bord. Vous recevrez un secret de webhook utilisé pour signer tous les envois de webhooks. Votre point de terminaison doit vérifier la signature HMAC sur chaque requête entrante en calculant la signature sur le corps brut de la requête à l'aide du secret et en la comparant à la valeur de l'en-tête X-HumanOps-Signature. Les requêtes avec des signatures invalides ou manquantes doivent être rejetées immédiatement, car elles pourraient être usurpées.
Les événements de webhook incluent task.estimated lorsqu'un opérateur soumet une estimation de temps, task.started lorsque l'opérateur commence le travail, task.proof_submitted lorsque la preuve est téléchargée, task.verified lorsque l'AI Guardian termine son analyse, et task.completed lorsque le paiement est libéré. Chaque événement comprend l'ID de la tâche, le type d'événement, un horodatage et des données spécifiques à l'événement. Pour exemple, l'événement task.verified inclut le score de confiance du Guardian et la détermination de réussite ou d'échec, permettant à votre agent de traiter le résultat immédiatement sans effectuer d'appel API séparé.
Le système de livraison des webhooks inclut des tentatives automatiques avec un repli exponentiel. Si votre point de terminaison renvoie un code d'état autre que 200 ou ne répond pas dans les dix secondes, la livraison est retentée jusqu'à cinq fois avec des délais croissants entre les tentatives. Une fois toutes les tentatives épuisées, l'événement est placé dans une file d'attente de lettres mortes (dead letter queue) où il peut être rejoué manuellement. Cette garantie de fiabilité assure que votre agent ne manque jamais un événement, même si votre serveur subit une interruption temporaire.
Sujets avancés : traitement par lots, priorité et mise à l'échelle
Pour les agents devant créer de nombreuses tâches simultanément, le point de terminaison de création par lots accepte un tableau de spécifications de tâches et les crée toutes en un seul appel API. C'est nettement plus efficace que de créer les tâches une par une car cela réduit le nombre d'allers-retours HTTP et permet à la plateforme d'optimiser le processus de financement de l'entiercement. Un agent de surveillance de restaurant qui détecte dix problèmes potentiels dans une ville peut envoyer les dix tâches de vérification en un seul appel API, chaque tâche étant financée à partir du même compte de dépôt d'agent.
La gestion des priorités permet aux agents d'indiquer l'urgence d'une tâche. Les tâches de priorité standard entrent dans le pool général où les opérateurs les parcourent et les réclament en fonction de la proximité géographique et de leurs préférences personnelles. Les tâches de haute priorité sont mises en évidence dans l'interface de l'opérateur et peuvent être éligibles à une mise en relation accélérée avec des opérateurs à proximité. Pour les vérifications urgentes, comme confirmer qu'un restaurant a rouvert après une fermeture signalée, la haute priorité garantit que la tâche est réclamée et terminée le plus rapidement possible.
Faire passer votre agent d'une preuve de concept à la production implique plusieurs considérations. Premièrement, passez de l'interrogation aux webhooks pour réduire la latence et la consommation de ressources. Deuxièmement, implémentez la création de tâches idempotente en incluant une clé d'idempotence générée par le client avec chaque requête de création de tâche, évitant ainsi les tâches en double si votre agent réessaie une requête en raison d'un délai d'attente réseau. Troisièmement, implémentez une gestion appropriée des erreurs pour les limites de débit, le solde insuffisant et l'indisponibilité de l'API. Quatrièmement, ajoutez de la journalisation et de la surveillance pour suivre les taux de création de tâches, les scores de vérification et les temps d'exécution sur l'ensemble de votre flotte d'agents.
L'API HumanOps prend en charge la pagination pour lister les tâches et le filtrage par statut, plage de dates et lieu. Pour les agents gérant des centaines de tâches simultanées, ces capacités de filtrage sont essentielles pour maintenir un flux de travail efficace. Vous pouvez rechercher toutes les tâches au statut ESTIMATED pour traiter les approbations en attente, toutes les tâches au statut IN_PROGRESS pour surveiller celles approchant de leur date limite, et toutes les tâches terminées dans une plage de dates pour le reporting et l'analyse.
Synthèse
Notre agent de surveillance de restaurant combine tous ces composants dans un système prêt pour la production. L'agent fonctionne en continu, surveillant les données d'avis pour détecter des anomalies. Lorsqu'il détecte un problème potentiel, il crée une tâche de vérification avec une description détaillée, un lieu, une récompense calibrée selon la complexité de la tâche et une date limite basée sur l'urgence. L'agent utilise des webhooks pour recevoir des mises à jour en temps réel au fur et à mesure que les opérateurs réclament les tâches, soumettent des preuves et reçoivent les résultats de vérification.
Les résultats de la vérification alimentent le processus de prise de décision de l'agent. Si l'AI Guardian confirme qu'un restaurant semble fermé, l'agent met à jour sa base de données et peut déclencher des notifications vers des systèmes en aval. Si le score du Guardian se situe dans la zone de révision manuelle, l'agent peut attendre une révision humaine ou signaler le résultat pour que son propre opérateur humain l'examine. Si le Guardian confirme que le restaurant est ouvert et fonctionne normalement, l'agent met à jour ses dossiers et clôt l'enquête.
Ce modèle de détection, délégation, vérification et décision est applicable bien au-delà de la surveillance de restaurants. La même architecture fonctionne pour la vérification de livraison, l'inspection de propriété, l'inventaire, la validation de service sur le terrain et tout autre cas d'utilisation où un agent IA a besoin de la vérité terrain du monde physique. La plateforme HumanOps fournit l'infrastructure, et votre agent fournit l'intelligence qui décide quoi vérifier et quoi faire des résultats.
Pour commencer à construire, consultez la documentation HumanOps pour la référence API complète, les guides d'installation du SDK et d'autres exemples de code. L'environnement de test est disponible immédiatement après l'inscription, sans carte de crédit requise. Si vous préférez la voie de l'intégration MCP, la documentation du serveur MCP inclut des exemples de configuration pour Claude Desktop, Cursor et d'autres hôtes pris en charge. Pour les opérateurs intéressés par l'exécution de tâches de vérification et le gain de USDC, le guide de l'opérateur couvre le processus d'inscription et de vérification.