Créer un agent IA Polkadot avec le SDK OpenAI Agents

Dans ce tutoriel, nous allons pas à pas construire un agent IA autonome capable d’analyser des propositions de gouvernance Polkadot OpenGov et de générer automatiquement des rapports synthétiques. L’objectif est de montrer comment combiner le SDK Agents d’OpenAI et le protocole MCP pour permettre à un agent alimenté par un LLM d’interroger des données externes (ici les propositions de gouvernance on-chain) et de fournir des analyses intelligentes.

Cas d’usage : Imaginons un utilisateur qui demande « Analyse la proposition OpenGov #1462 ». Notre agent va alors récupérer en temps réel les informations de cette proposition via les API de Polkadot (Subsquare, Subscan, etc.), identifier l’auteur (adresse ou identité sur le réseau), analyser l’historique de participation de cet auteur (propositions passées, taux de succès, réputation), résumer le contenu de la proposition, et enfin formuler un avis argumenté (bénéfices, risques, impact). Le tout sera présenté sous forme d’un mini-rapport structuré (titre, résumé, analyse, conclusion).

Ce tutoriel s’adresse à un public technique passionné d’IA et de crypto. Il suppose une familiarité de base avec Python et les concepts de gouvernance décentralisée (DAO, on-chain governance). Nous couvrirons : l’introduction du cas d’usage OpenGov, une présentation concise du SDK OpenAI Agents et du protocole MCP, l’installation et la configuration de l’environnement, la création d’un outil MCP sur mesure pour interroger les données OpenGov, la construction de l’agent IA chaînant ces outils et raisonnant sur les résultats, un exemple concret d’exécution, et pour finir une idée bonus d’extension avec un second agent « conseiller DAO ».

📚 Pour les curieux

Envie d’explorer plus loin les architectures d’agents IA ou les frameworks émergents comme LangChain, MCP ou PydanticAI ? Voici quelques articles recommandés pour approfondir :

• 🇫🇷 Architectures d'Agents IA en 2025 : Au-delà des Frameworks – Un panorama des approches modernes pour construire des agents robustes et modulaires.
• 🇫🇷 PydanticAI : Les Design Patterns de l’IA Moderne – Comment structurer vos agents avec rigueur et réutilisabilité.
• 🇫🇷 Développer avec l'IA en 2025 : L'art du dompteur d'IA – Retour d'expérience sur la collaboration entre développeurs et IA.

⚡️ Contexte : Polkadot OpenGov et les propositions de gouvernance

Polkadot OpenGov est le nouveau système de gouvernance entièrement décentralisé de Polkadot, déployé en 2023. Il place la communauté au centre du processus décisionnel en éliminant les organes centralisés (Conseil, Comité technique) au profit d’un modèle de démocratie directe (Polkadot OpenGov Deep Dive | Messari). Concrètement, n’importe quel détenteur de DOT peut soumettre une proposition (aussi appelée référendum) et plusieurs référendums peuvent être menés en parallèle, ce qui accélère le rythme des décisions collectives. Chaque proposition passe par différentes phases on-chain (période de candidature, de décision/vote, puis éventuellement exécution si elle est adoptée).

Ce modèle ouvert (d’où le nom OpenGov) augmente fortement le nombre de propositions à évaluer à tout moment. Pour un token holder ou un membre d’une DAO Polkadot, il devient difficile de suivre et analyser chaque proposition en détail : il faut lire la description (souvent longue), vérifier l’identité ou l’adresse du proposant, parcourir l’historique on-chain de cette adresse (a-t-elle déjà proposé des idées ? ont-elles été acceptées ou rejetées ?), et peser les avantages et risques de la proposition avant de voter. Des plateformes communautaires comme Polkassembly et SubSquare facilitent l’accès aux informations et discussions des propositions (Polkadot Governance Apps · Polkadot Wiki), mais l’analyse reste manuelle et chronophage.

C’est ici qu’un agent IA peut aider. En automatisant la collecte d’informations on-chain/off-chain et en produisant un rapport automatique, un agent IA permet à la communauté de gagner du temps et d’obtenir un éclairage objectif sur chaque proposition. Notre agent « OpenGov Analyst » interrogera en particulier les données disponibles via des API publiques : par exemple, SubSquare (une plate-forme qui suit les événements de gouvernance on-chain et offre une interface aux utilisateurs) expose les détails des référendums actifs et historiques, et Subscan (un explorateur de blockchain Polkadot) permet de rechercher des informations sur les comptes et transactions. En combinant ces sources, l’agent pourra rassembler les pièces du puzzle : métadonnées de la proposition (titre, catégorie, date, statut, etc.), contenu/résumé de la proposition, profil du proposant (adresse Polkadot, éventuellement nom d’identité, statistiques de participation), et indicateurs pour évaluer la proposition (montant demandé si c’est une dépense de trésorerie, niveau de soutien actuel, etc.).

📚 OpenAI Agents SDK et protocole MCP : aperçu rapide

Avant de plonger dans l’implémentation, faisons un bref rappel des deux technologies que nous allons utiliser :

OpenAI Agents SDK : Il s’agit d’un kit de développement open-source proposé par OpenAI (sorti en mars 2025) qui vise à simplifier la création et l’orchestration d’agents IA. Un agent est défini comme un système piloté par un LLM qui peut agir de façon autonome pour accomplir des tâches, en s’appuyant sur des outils (fonctions, actions) lorsque nécessaire (OpenAI's Agents SDK and Anthropic's Model Context Protocol (MCP)). Le SDK fournit une structure légère avec quelques primitives clés : les Agents (des LLM avec instructions et outils intégrés), les Handoffs (transferts de contrôle entre agents, pour créer des workflows multi-agents), et les Guardrails (contrôles et validations sur les entrées/sorties) (OpenAI Agents SDK). Il intègre surtout une boucle d’exécution agent robuste : l’agent peut planifier des actions, appeler un outil, recevoir le résultat, le combiner au contexte, et ainsi de suite jusqu’à ce qu’il aboutisse à une réponse finale, le tout de manière transparente pour le développeur. En pratique, le SDK permet de définir des outils comme de simples fonctions Python (décorées pour en faire des outils utilisables par le LLM) et gère automatiquement la génération du schema JSON d’appel, l’appel du LLM via l’API OpenAI, et la coordination des étapes de raisonnement.

En résumé, l’Agents SDK nous permet de construire facilement un agent capable de raisonnement multi-étapes et d’appel d’outils (chain-of-thought). Dans notre cas, nous aurons un unique agent « analyste OpenGov » équipé de deux outils : un outil pour obtenir les détails d’une proposition, et un autre pour obtenir le profil de l’auteur. Le SDK se chargera de la coordination : l’agent (via le LLM) décidera quand utiliser chaque outil et bouclera jusqu’à avoir assez d’infos pour rédiger son rapport final.

MCP (Model Context Protocol) : Le protocole MCP, introduit par Anthropic fin 2024, est un standard ouvert visant à connecter les modèles IA à des sources de données et outils externes de manière unifiée. L’idée est de définir une sorte de « port universel » pour les IA – Anthropic décrit MCP comme un “port USB-C pour l’IA” afin qu’un modèle (peu importe qu’il s’agisse de Claude, GPT-4 ou autre) puisse interagir avec un ensemble de services/outils via un protocole commun. MCP distingue les serveurs MCP (des services qui se connectent à des sources de données spécifiques – bases de données, API, fichiers – et exposent ces ressources/outils via le protocole) et les clients MCP (des modèles IA ou applications qui interrogent dynamiquement ces serveurs). Concrètement, un serveur MCP héberge un ou plusieurs outils ou resources que l’IA peut appeler en formulant des requêtes MCP standard (généralement en JSON) ; le serveur exécute l’action demandée et renvoie la réponse au modèle.

Pourquoi MCP dans notre projet ? Certes, l’Agents SDK peut directement appeler des fonctions Python locales en tant qu’outils. Toutefois, intégrer MCP présente plusieurs avantages : cela permet une découplage entre l’agent et la source de données (on pourrait faire évoluer l’outil OpenGov indépendamment du code de l’agent), et ouvre la porte à l’utilisation du même outil par d’autres modèles MCP-compatibles (par exemple un agent Claude pourrait interroger le même serveur MCP). De plus, l’extension openai-agents-mcp que nous utiliserons facilite grandement la connexion – l’agent OpenAI pourra utiliser des outils MCP aux côtés de ses outils Python natifs. L’Agents SDK et MCP se complètent bien : “OpenAI’s Agent SDK [...] fournit l’orchestration (raisonnement, outils, traçage) tandis que MCP facilite l’accès à des données externes”. Dans ce tutoriel, nous créerons un outil MCP “OpenGov” exposant les données Polkadot dont nous avons besoin, et nous le brancherons à notre agent via l’extension. Ainsi, notre agent disposera d’un outil externe spécialisé pour la gouvernance Polkadot, qu’il pourra appeler comme n’importe quel autre outil.

📦 Installation et configuration de l’environnement

Commençons par installer et configurer tout le nécessaire sur votre machine de développement.

1. Installer Python 3.8+ – Assurez-vous de disposer d’un environnement Python récent (3.8 ou plus). Créez un virtual env si besoin.

2. Installer le SDK OpenAI Agents et l’extension MCP – Les packages sont disponibles sur PyPI : on installera openai-agents (le cœur du SDK) ainsi que openai-agents-mcp (extension pour MCP). Exécutez :

bash
pip install openai-agents
pip install openai-agents-mcp

Cette installation inclut également les dépendances nécessaires (comme mcp-agent). Pour vérifier, vous pouvez importer le module dans Python sans erreur.

3. Configuration de la clé OpenAI – Le SDK utilise l’API d’OpenAI pour faire fonctionner le LLM derrière l’agent. Vous devez donc posséder une clé API OpenAI valide (et éventuellement avoir accès à GPT-4 via l’API, recommandé pour des résultats de haute qualité). Exportez la clé dans votre environnement :

bash
export OPENAI_API_KEY=<votre_clé_sk-...>

(Sous Windows PowerShell : $env:OPENAI_API_KEY="sk-..."). Vous pouvez aussi utiliser un fichier .env ou une variable d’environnement dans votre IDE. Sans cette clé, l’agent ne pourra pas appeler le modèle OpenAI (OpenAI Agents SDK).

4. (Optionnel) Outils externes – Dans ce projet, nous allons créer notre propre outil via MCP. L’extension openai-agents-mcp permet de définir des serveurs MCP via un fichier de config YAML ou par code. Si vous souhaitez utiliser des serveurs MCP existants (par exemple le serveur générique de fetch web d’Anthropic, ou un serveur filesystem), vous pouvez les configurer dans mcp_agent.config.yaml. Dans notre cas, nous allons développer un serveur MCP personnalisé en Python, donc cette étape de config peut être sautée. Assurez-vous simplement que l’extension MCP est bien installée et prête.

5. Installer les bibliothèques pour l’API Polkadot – Selon l’API que vous comptez utiliser pour interroger OpenGov, vous pourriez avoir besoin de packages additionnels. Par exemple, pour appeler une API REST (Subsquare/Subscan), la bibliothèque standard requests suffira (pip install requests). Si vous envisagez d’utiliser l’API GraphQL de Polkassembly, vous pourriez installer un client GraphQL Python. Pour notre tutoriel, nous utiliserons de simples requêtes HTTP, donc importez requests dans votre code.

Une fois ces étapes faites, nous avons notre environnement prêt : Python, le SDK d’agent, l’extension MCP, et l’accès aux API OpenGov. Nous pouvons maintenant passer à la création de l’outil MCP OpenGov.

🔍 Création de l’outil MCP « OpenGov » pour interroger les données Polkadot

Nous allons développer un petit serveur MCP dédié à Polkadot OpenGov, qui servira d’interface entre l’agent et les APIs de gouvernance. L’idée est de doter ce serveur de deux fonctionnalités (outils) :

• get_proposal_details : Récupérer les informations détaillées d’une proposition donnée (identifiée par son numéro de référendum ou un ID). Cet outil retournera un ensemble de données structuré : le titre de la proposition, sa description (ou un résumé), le proposant (adresse ou nom), la date de soumission, le statut actuel (en cours, accepté, rejeté…), etc.
• get_author_profile : Récupérer le « profil » d’un auteur de proposition (via son adresse). L’idée est de compiler quelques métriques sur la participation de cette adresse : combien de propositions a-t-elle soumises dans le passé, combien ont été acceptées vs rejetées, et possiblement d’autres indicateurs (ex : a-t-elle voté fréquemment, délègue-t-elle son vote, etc., selon les données disponibles). Pour simplifier, on se concentrera sur les propositions soumises par cette adresse et leur taux de succès.

Créons d’abord le squelette de notre serveur MCP en Python. Un serveur MCP a besoin de recevoir des requêtes (généralement en JSON) et d’y répondre. Cependant, l’extension openai-agents-mcp va se charger de lancer notre serveur en arrière-plan et de gérer la communication. Nous, nous devons simplement fournir des fonctions Python qui effectuent les actions désirées. Pour cela, nous pouvons utiliser la librairie mcp_agent qui accompagne l’extension.

Toutefois, pour plus de simplicité, nous allons éviter d’implémenter nous-mêmes tout un serveur HTTP. À la place, nous allons profiter du fait que l’Agents SDK sait aussi utiliser directement des fonctions Python comme outils (via les function tools). Nous développerons donc les fonctions Python nécessaires, puis nous les intégrerons via MCP. Cela nous permettra de tester facilement les fonctions en local, et de les enregistrer comme outils de l’agent.

🔍 Récupérer les détails d’une proposition via l’API OpenGov

Polkadot OpenGov ayant un protocole on-chain assez complexe, il est plus facile d’utiliser une API tierce qui indexe ces données. Deux choix populaires sont :

• Subsquare : propose une API orientée gouvernance (puisqu’il s’agit d’une plateforme dédiée). Récemment, Subsquare a refondu son architecture d’API pour la rendre plus accessible aux développeurs et peut renvoyer les contenus de propositions en Markdown ou HTML (Polkassembly Social Contract 2025). On peut l’interroger pour lister les référendums OpenGov actifs, obtenir les détails d’un référendum particulier, etc.
• Subscan : explorateur blockchain multi-chaînes, qui offre une API REST couvrant les comptes, extrinsics et événements de gouvernance. L’API Subscan nécessite une clé API gratuite et a des endpoints spécifiques (par ex, /api/scan/referendum pour les détails d’un référendum).

Dans ce tutoriel, nous utiliserons Subsquare pour simplicité, en supposant qu’elle offre un endpoint public pour les référendums OpenGov. (Si besoin, l’API Polkassembly pourrait aussi être interrogée pour obtenir le texte de la proposition ou le nombre de commentaires, mais on s’en passera ici.)

Implementons la fonction get_proposal_details(ref_id: int) en Python. Cette fonction va :

1. Construire une requête HTTP vers l’API de gouvernance pour le référendum ref_id. Par exemple, si l’API Subsquare est disponible à l’adresse fictive https://polkadot.api.subsquare.io/opengov/referenda/, on l’utilisera.
2. Parser la réponse JSON pour en extraire les champs importants.
3. Retourner un dictionnaire Python contenant ces champs, que le SDK convertira en JSON pour le LLM.

Voici un exemple de code commenté :

python
import requests

def get_proposal_details(ref_id: int) -> dict:
    """Interroge l'API OpenGov pour obtenir les détails du référendum donné."""
    # Construire l'URL de l'API (exemple pour Subsquare)
    url = f"https://polkadot.api.subsquare.io/v1/open-gov/referenda/{ref_id}"
    response = requests.get(url)
    if response.status_code != 200:
        raise Exception(f"Erreur API: statut {response.status_code}")
    data = response.json()

    # Extraire les champs pertinents (selon la structure de l'API)
    title = data.get("title") or data["referendum_title"]
    content = data.get("content") or data.get("description")  # texte de la proposition
    author_address = data.get("proposer") or data["submitter"]
    submit_date = data.get("submitted_at")  # timestamp ou date
    status = data.get("status")  # ex: ongoing/confirming/approved/rejected

    # (Optionnel) Raccourcir ou résumer le contenu si trop long
    summary = content[:200] + "..." if content and len(content) > 250 else content

    # Préparer le dictionnaire de résultat
    result = {
        "id": ref_id,
        "title": title,
        "summary": summary,
        "author": author_address,
        "submitted_date": submit_date,
        "status": status
    }
    return result

Remarques : Dans cet exemple, nous spéculons sur la forme de l’API. En pratique, il faudra ajuster les clés d’accès (referendum_title, submitter, etc.) d’après la documentation réelle de l’API. L’API Subsquare retournant possiblement du HTML/Markdown, on peut choisir de garder le champ content brut ou d’en extraire un résumé. Ici, pour la concision, on tronque le contenu à ~200 caractères et on l’appelle summary. Une amélioration pourrait être d’utiliser une fonction de résumé automatique (par un appel LLM ou autre), mais on évitera la récursion d’IA dans l’IA pour l’instant !

Cette fonction, lorsqu’elle sera appelée, retournera par exemple :

python
{
    "id": 1462,
    "title": "Polkadot-API 2025 Development Funding through Polkadot Community Foundation",
    "summary": "Hi everyone, As many of you may already know, Polkadot-API was envisioned to provide a robust and flexible suite of libraries... (truncated)",
    "author": "16JG...pr9J",
    "submitted_date": "2025-03-01T12:34:56Z",
    "status": "Confirming"
}

Ainsi, on a bien le titre de la proposition #1462, un début de résumé du contenu, l’adresse auteur (ici abrégée), la date et le statut (« Confirming » signifie peut-être que la proposition est au stade de collecte de confirmations). Toutes ces informations seront très utiles à notre agent pour rédiger le rapport.

🕵️‍♂️ Récupérer le profil de l’auteur (historique de participation)

Maintenant, créons la fonction get_author_profile(address: str). L’objectif est de rassembler quelques stats sur une adresse Polkadot donnée qui correspond à l’auteur d’une proposition. Typiquement, on veut savoir : combien de propositions OpenGov cette adresse a soumises par le passé, et parmi elles combien ont été acceptées (ou rejetées). Cela nous donne un taux de succès qui peut indiquer la crédibilité ou la maîtrise de l’auteur dans le processus de gouvernance.

Subsquare propose probablement un moyen de filtrer les référendums par proposant (via son API ou son interface utilisateur). D’après des mises à jour récentes, on sait qu’il est possible de « consulter l’historique de vote de n’importe quelle adresse sur Subsquare » (Mises à jour de fonctionnalités Subsquare - Gouvernance - Forum Polkadot), et qu’il existe une vue profil (peut-être accessible via /user/). Subscan permettrait également d’interroger les extrinsics du module Democracy/Referendum soumis par une adresse. Pour simplifier, nous supposerons qu’un endpoint du type https://polkadot.api.subsquare.io/v1/account//referenda existe sur Subsquare.

On va implémenter la fonction en pseudo-code : appeler l’API, compter les propositions, calculer le ratio. Si l’API n’existe pas, on montrera comment on pourrait procéder, et on simulera les données.

python
def get_author_profile(address: str) -> dict:
    """Récupère des stats de participation OpenGov pour une adresse donnée."""
    url = f"https://polkadot.api.subsquare.io/v1/account/{address}/referenda"
    response = requests.get(url)
    if response.status_code != 200:
        raise Exception(f"Erreur API (profil auteur): statut {response.status_code}")
    data = response.json()

    # Supposons que data contienne une liste de referenda soumis par cette adresse
    referenda_list = data.get("referenda") or []
    total = len(referenda_list)
    if total == 0:
        profile = {"address": address, "proposals": 0, "accepted": 0, "rejected": 0, "acceptance_rate": 0.0}
        return profile

    # Compter combien ont été acceptés/rejetés
    accepted = sum(1 for ref in referenda_list if ref.get("status") == "Approved")
    rejected = sum(1 for ref in referenda_list if ref.get("status") == "Rejected")
    rate = accepted / total if total > 0 else 0.0

    profile = {
        "address": address,
        "proposals": total,
        "accepted": accepted,
        "rejected": rejected,
        "acceptance_rate": round(rate, 2)
    }
    return profile

Pour illustrer, imaginons que l’adresse 16JG...pr9J (de la proposition #1462) avait déjà fait 5 propositions dans le passé, dont 3 acceptées et 2 refusées. Le résultat serait :

python
{
    "address": "16JG...pr9J",
    "proposals": 5,
    "accepted": 3,
    "rejected": 2,
    "acceptance_rate": 0.6
}

Astuce : On peut enrichir ce profil avec d’autres infos si disponibles – par exemple, la participation en tant que votant, ou l’identité on-chain (si l’adresse a un nom d’identité enregistré sur la chaîne, via le module Identity). Subsquare renvoie possiblement l’identité associée à l’adresse (cela pourrait être dans un champ identity_display). Pour ne pas complexifier, nous restons sur les chiffres de proposition.

🔄 Intégration des outils dans l’agent IA

Maintenant que nos fonctions Python sont prêtes, il est temps de les intégrer à l’agent IA en tant qu’outils. Il y a deux manières de le faire :

1. Directement via le SDK (function tools) – L’Agents SDK permet de déclarer une fonction Python en outil en la décorant avec @function_tool du module agents. Cela génère automatiquement le schéma JSON pour l’appel de fonction. Nous pourrions opter pour cette solution simple.
2. Via un serveur MCP – Nous pourrions encapsuler ces fonctions dans un petit serveur MCP. L’extension openai-agents-mcp permet ensuite de connecter ce serveur comme source d’outils pour l’agent. Cette approche modularise l’outil, le rendant disponible éventuellement à d’autres clients MCP.

Pour le tutoriel, nous allons illustrer la deuxième approche (MCP), puisque c’est celle mise en avant, tout en utilisant notre code Python. Concrètement, l’extension va nous permettre de fournir nos fonctions comme outils MCP sans trop de cérémonie. Voici comment procéder :

• Écrivez le code de vos fonctions (get_proposal_details et get_author_profile) dans un fichier Python (par ex opengov_server.py).
• Au lieu d’écrire tout un serveur HTTP, on va utiliser la fonctionnalité RunnerContext de l’extension. Dans notre script principal, on peut définir une configuration MCP programmatique en listant un serveur personnalisé. Par exemple, on va indiquer que pour le serveur MCP nommé "opengov", la commande à exécuter est notre script Python.

Il existe plusieurs méthodes (fichier YAML de config, etc.). Utilisons la config programmatique pour la démonstration.

python
from agents_mcp import Agent, Runner, RunnerContext
from mcp_agent.config import MCPSettings, MCPServerSettings

# Définir la config MCP pour lancer notre serveur opengov
mcp_config = MCPSettings(
    servers={
        "opengov": MCPServerSettings(
            command="python",
            args=["opengov_server.py"]  # script qui lancera nos outils MCP
        )
    }
)
context = RunnerContext(mcp_config=mcp_config)

Ici, on suppose que opengov_server.py une fois exécuté, va démarrer un serveur MCP exposant nos deux outils sous le nom par exemple de get_proposal_details et get_author_profile. La question qui se pose : comment ce script doit-il être écrit pour transformer nos fonctions en outils MCP ?

Une solution consiste à utiliser la librairie mcp_agent pour déclarer des outils. Par exemple, mcp_agent offre un moyen de créer un serveur MCP en définissant les outils et en lançant l’écoute. (Les détails de cette implémentation sortent un peu du cadre de ce tutoriel, mais l’idée serait d’utiliser un décorateur ou un registre d’outils fournis par mcp_agent puis d’appeler serve().)

Alternativement, pour rester focalisé sur l’Agents SDK, on peut ne pas réellement lancer de serveur externe et utiliser nos fonctions localement. En effet, on peut directement donner des tools à l’agent, qu’ils soient natifs ou MCP. Le plus simple est donc finalement d’utiliser @function_tool et de passer les fonctions à l’agent, en mentionnant éventuellement le serveur MCP comme contexte.

Pour ne pas embrouiller, nous allons opter pour la voie directe : enregistrer nos fonctions comme outils de l’agent. Ainsi, nous pourrons voir concrètement l’enchaînement des appels outils par l’agent.

Combinons donc tout : création de l’agent, en lui spécifiant : un nom, des instructions (rôle/système prompt), et la liste des outils (fonctions) qu’il peut utiliser.

python
from agents import Agent, Runner, function_tool

# Décorer les fonctions comme outils pour que le schema JSON soit auto-généré
@function_tool
def get_proposal_details(ref_id: int) -> dict:
    # ... (implémentation comme plus haut)
    return result

@function_tool
def get_author_profile(address: str) -> dict:
    # ... (implémentation comme plus haut)
    return profile

# Définir les instructions de l'agent (son rôle et son comportement)
instructions = (
    "Tu es un agent assistant expert en gouvernance Polkadot (OpenGov). "
    "Tu as accès à des outils pour obtenir les détails d'une proposition "
    "et pour vérifier le profil d'un auteur de proposition. "
    "Utilise ces outils de manière judicieuse pour répondre aux demandes. "
    "Lorsque l'utilisateur te demande d'analyser une proposition, "
    "tu devras rendre un rapport structuré comportant un Titre, un Résumé de la proposition, "
    "une Analyse (avantages, risques, contexte) et une Conclusion (avis argumenté). "
    "Si nécessaire, tu peux d'abord récupérer les infos avec les outils puis formuler ta réponse. "
    "Ton ton doit être neutre, informatif et professionnel."
)

# Créer l'agent avec son nom, ses instructions et ses outils
opengov_agent = Agent(
    name="Polkadot OpenGov Analyst",
    instructions=instructions,
    tools=[get_proposal_details, get_author_profile]
)

Quelques explications :

• Nous avons utilisé le décorateur @function_tool du SDK sur nos deux fonctions. Cela indique à l’agent qu’il peut appeler ces fonctions via le mécanisme d’appel de fonction de l’API OpenAI. Le LLM pourra choisir d’invoquer get_proposal_details ou get_author_profile en cours de conversation, en fournissant les arguments requis (le SDK génère pour chaque outil une spécification d’arguments types, ici ref_id entier, et address chaîne).
• Les instructions de l’agent jouent le rôle de Prompt Système. C’est une directive importante qui définit le comportement attendu. On explique à l’agent quel est son rôle (analyste OpenGov), quels outils il a à disposition, comment structurer la réponse finale, et le ton à employer. C’est ici que l’on guide la mise en forme du mini-rapport.
• On nomme l’agent "Polkadot OpenGov Analyst" (ce nom peut être utilisé en debug ou logging).
• On passe la liste des outils.

À ce stade, notre agent est configuré. Il est capable, en théorie, de recevoir une requête de l’utilisateur et de choisir de lui-même quand appeler get_proposal_details et/ou get_author_profile pour rassembler l’information nécessaire. L’Agents SDK et le LLM se chargent de tout le raisonnement : l’agent va élaborer un plan du genre « Pour répondre, j’ai besoin des détails de la proposition » → appel de l’outil → « Maintenant j’ai les détails, je veux l’historique de l’auteur » → appel de l’outil → « J’ai tout, je rédige le rapport ». Le développeur n’a pas à orchestrer ces étapes manuellement : on se contente d’exécuter l’agent et de récupérer le résultat final.

📝 Scénario d’utilisation : analyse d’une proposition OpenGov par l’agent

Mise en place terminée, testons notre agent sur un exemple concret. Reprenons la proposition fictive #1462 (Polkadot-API 2025 Development Funding) dont on a parlé. Supposons que l’utilisateur pose la question suivante à l’agent :

Utilisateur : « Peux-tu analyser la proposition OpenGov n°1462 ? »

Lorsque nous passons cette requête à l’agent via le SDK, voici ce qu’il va se passer étape par étape :

1. Réception de la requête – L’agent reçoit la question de l’utilisateur comme input. Le prompt complet vu par le LLM est alors la concaténation des instructions (système) et de la requête (utilisateur).
2. Raisonnement initial – Le LLM (ex. GPT-4) comprend qu’on lui demande une analyse d’une proposition spécifique (#1462). Conformément à ses instructions, il sait qu’il doit fournir un rapport structuré et qu’il a des outils pour obtenir des informations précises. Il va donc planifier d’utiliser ces outils.
3. Appel de get_proposal_details – L’agent va d’abord vouloir les détails de la proposition #1462. Il génère donc un appel de fonction interne pour get_proposal_details(ref_id=1462). Le SDK exécute notre fonction Python et récupère le résultat (les données JSON de la proposition).
4. Observation du résultat – Le LLM reçoit en retour les données de la proposition #1462, par exemple : titre « Polkadot-API 2025 Development Funding… », résumé du contenu « Hi everyone, ... », auteur 16JG...pr9J, date, statut Confirming. Ces informations sont maintenant insérées dans la conversation (sous forme de message assistant contenant une réponse de fonction). Le LLM les prend en compte pour la suite du raisonnement.
5. Appel de get_author_profile – L’agent réfléchit : il a le proposer (16JG...pr9J). Ses instructions lui suggèrent de vérifier l’historique de l’auteur. Il décide donc d’appeler le second outil : get_author_profile(address="16JG...pr9J"). Là encore, le SDK exécute la fonction Python correspondante et renvoie le résultat (profil de l’auteur) au LLM. Supposons que la réponse soit 5 propositions, 3 acceptées, 2 rejetées, taux 60%.
6. Observation du résultat – Le LLM intègre ces nouvelles données à son contexte. Il sait désormais que l’auteur a un taux de réussite de 60%, ce qui est plutôt bon, et qu’il a déjà fait plusieurs propositions (signe d’expérience).
7. Rédaction du rapport final – Ayant les éléments nécessaires, l’agent n’a plus besoin d’autres outils. Le LLM passe en mode génération de réponse finale. Sur la base de toutes les informations engrangées, il va composer une réponse textuelle structurée avec les sections demandées. Grâce au prompt système, il se rappelle de fournir un titre, un résumé, une analyse, une conclusion. Il peut par exemple utiliser le titre réel de la proposition comme titre du rapport, puis résumer le contenu (en s’appuyant sur le champ résumé fourni ou en reformulant), puis discuter des points positifs/négatifs (en utilisant peut-être le fait que le projet vise à améliorer l’écosystème développeur de Polkadot, etc.), et enfin conclure sur un avis (par ex « favorable » en argumentant que cela bénéficie à l’écosystème).

Pour exécuter cela dans notre code Python, on utilise le Runner du SDK :

python
user_query = "Analyse la proposition OpenGov #1462"
result = Runner.run_sync(opengov_agent, user_query)
print(result.final_output)

Le Runner va orchestrer l’échange décrit ci-dessus. Le result.final_output contiendra la réponse finale de l’agent. Voyons à quoi pourrait ressembler ce rapport généré :

Exemple de rapport généré par l’agent pour la proposition #1462 (Polkadot OpenGov). (Polkadot-API 2025 Development Funding through Polkadot Community Foundation)

Dans ce rapport fictif, on retrouve :

• Titre – repris de la proposition originale pour la clarté (il s’agit du financement du développement de l’API Polkadot pour 2025 via la fondation communautaire).
• Résumé de la proposition – l’agent explique en quelques phrases ce que demande le proposant (financement de la maintenance et du développement de la librairie Polkadot-API sur l’année 2025, avec quelques détails contextuels tirés de la description).
• Analyse – l’agent liste les bénéfices : continuité du support aux développeurs, impact positif pour l’écosystème, etc., puis les risques ou points d’attention : dépendance au financement récurrent, nécessité de surveillance de l’exécution du budget, etc. Il mentionne également le profil du proposant : ici, on voit « un membre actif (5 propositions soumises, 60% adoptées) », ce qui ajoute du contexte sur la réputation de l’auteur. L’agent utilise ces données pour renforcer la confiance dans la proposition.
• Conclusion – l’agent donne un avis argumenté. Dans cet exemple, une conclusion favorable est donnée, justifiée par l’importance de l’outil Polkadot-API pour la communauté et la bonne réputation de l’équipe proposante, tout en soulignant la vigilance nécessaire (ce qui montre une analyse nuancée).

Cette réponse est bien structurée et condensée, offrant à l’utilisateur une vision claire sans avoir à lire l’entièreté de la proposition ou fouiller les données on-chain. Bien sûr, la qualité de la conclusion dépendra du LLM et des données fournies : un LLM puissant comme GPT-4 pourra formuler des analyses pertinentes.

💡 Note : Durant le processus, le développeur peut suivre la trace de l’agent (appel des outils, etc.) si nécessaire en activant le mode verbose ou en utilisant les outils de traçage du SDK. Cela est utile pour déboguer ou pour vérifier que l’agent utilise bien les outils comme on l’entend. Par exemple, on verrait dans les logs l’intention d’appel de get_proposal_details(1462), puis la réponse JSON, etc., jusqu’à la réponse finale. Le SDK fournit ce traçage intégré qui facilite le debug des agents complexes (OpenAI Agents SDK).

💡 Bonus : Un agent “conseiller DAO” pour la recommandation de vote

Notre agent OpenGov Analyst fournit une analyse objective. On pourrait aller un pas plus loin en créant un second agent, un peu plus opinionated, qui jouerait le rôle d’un conseiller de vote pour la DAO. Par exemple, cet agent prendrait en entrée le rapport d’analyse (fourni par le premier agent) et formulerait une recommandation de vote (Pour ou Contre la proposition, voire s’Abstenir) à destination d’un conseil ou des membres de la DAO.

Techniquement, cela démontre la capacité de mettre en place un système multi-agents avec le SDK d’OpenAI. On pourrait avoir : l’agent Analyste qui, une fois son rapport généré, passe le relais à l’agent Conseiller. C’est exactement le concept de handoff du SDK (New tools for building agents | OpenAI) : un agent peut transférer le contexte à un autre agent pour la suite du traitement.

Comment procéder ? Nous pourrions définir un agent advisor_agent avec des instructions du style : « Tu es un conseiller de gouvernance. On te fournit l’analyse d’une proposition. Sur cette base, tu dois recommander aux membres s’ils devraient voter pour ou contre, avec une justification courte. Prends en compte uniquement l’intérêt du projet pour la communauté et les risques, sois concis et décisif. ». Cet agent n’aurait pas nécessairement besoin d’outils externes, juste du rapport en entrée.

On peut soit orchestrer cela dans le code Python (d’abord run l’analyste, puis passer son output au conseiller), soit configurer un handoff automatique dans le SDK (un agent principal qui d’abord utilise l’analyste puis envoie la réponse intermédiaire à l’agent conseiller). Le SDK Agents rend ce genre d’orchestration assez simple en permettant de définir plusieurs agents et de spécifier que l’agent A peut passer la main à l’agent B (New tools for building agents | OpenAI).

Sans entrer dans tous les détails, voici une esquisse de code pour le conseiller DAO :

python
advisor_instructions = (
    "Tu es un conseiller virtuel pour une DAO Polkadot. "
    "Un rapport d'analyse de proposition va te êtret fourni. "
    "Après l'avoir lu, tu donneras une recommandation de vote (Pour / Contre) pour la proposition, "
    "en expliquant brièvement pourquoi. Ta réponse doit tenir en 2-3 phrases maximum, directe et claire."
)
dao_advisor_agent = Agent(
    name="DAO Voting Advisor",
    instructions=advisor_instructions
    # Pas d'outils nécessaires, l'input sera le rapport.
)

# Exemple d'utilisation après avoir obtenu le rapport d'analyse 'analysis_report'
advice = Runner.run_sync(dao_advisor_agent, analysis_report)
print(advice.final_output)

Si analysis_report contient le texte du rapport généré précédemment, l’agent conseiller va le lire (in-context) et produire quelque chose comme : « Recommandation : Vote Pour. Cette proposition apportera un bénéfice clair à l’écosystème en finançant un outil crucial, et l’équipe proposante a fait ses preuves par le passé. ».

Ce second agent permet d’automatiser la prise de décision sur la base du rapport. Bien sûr, on peut affiner ses instructions selon la politique de la DAO (certains DAO advisors pourraient avoir un profil plus conservateur ou plus audacieux). L’important est qu’on voit comment on peut chaîner des agents aux rôles différents : l’un récolte et analyse l’information, l’autre prend une décision ou une recommandation à partir de cette analyse.

📝 Conclusion et perspectives

Nous avons construit un agent IA autonome capable d’analyser les propositions de gouvernance Polkadot OpenGov et de produire un rapport structuré utile aux participants de la gouvernance décentralisée. Ce projet a illustré l’utilisation conjointe du SDK OpenAI Agents (pour orchestrer le raisonnement et les appels d’outils du LLM) et du protocole MCP (pour se connecter aux données externes on-chain via des outils dédiés) dans un contexte réel de DAO.

En suivant ce tutoriel, nous sommes passés par toutes les étapes : installation de l’environnement, création d’outils spécialisés interrogeant les APIs de Polkadot (Subsquare/Subscan) pour extraire titre, description, auteur, statut des propositions, ainsi que le profil on-chain des auteurs, intégration de ces outils dans un agent avec un prompt système bien pensé, exécution et test sur un exemple concret (#1462), et enfin extension vers un système multi-agents avec un conseiller de vote.

Ce prototype peut être amélioré de multiples façons : on pourrait enrichir l’analyse (par ex, en faisant aussi un résumé automatisé du texte de la proposition via le LLM lui-même), ajouter la récupération du tally de votes en temps réel, ou connecter l’agent à d’autres sources comme le forum de discussion off-chain pour inclure des arguments de la communauté. De plus, l’approche présentée n’est pas limitée à Polkadot : elle peut s’adapter à d’autres systèmes de gouvernance décentralisée (par exemple Ethereum DAO proposals, etc.) en changeant simplement l’outil de connexion aux données.

En combinant agents IA et données de gouvernance, on entrevoit un futur où des assistants intelligents aident les communautés crypto à digérer l’information et à prendre des décisions plus éclairées, le tout de façon transparente et reproductible. Ce tutoriel n’est qu’une première étape, mais vous disposez désormais d’une base solide pour expérimenter avec votre propre agent d’analyse de propositions – à vous de le faire évoluer et de l’adapter aux besoins de votre DAO !

Résumé : En utilisant l’OpenAI Agents SDK pour l’orchestration et MCP pour l’accès aux données, nous avons créé un agent IA qui interroge automatiquement les propositions Polkadot OpenGov, en synthétise le contenu et l’historique du proposant, et délivre un rapport d’analyse structuré. Ce genre d’agent peut grandement faciliter la gouvernance décentralisée en fournissant des rapports automatiques aux votants, et ouvre la voie à des conseillers IA au sein des DAO.