Tutoriel AI Agent Framework + MCP Integration Nanny Level : créer un agent à partir de zéro qui peut appeler des outils externes

🛒 Pour les développeurs, un didacticiel d'introduction unique depuis la préparation de l'environnement, l'écriture du serveur MCP vers le débogage conjoint LangGraph.

Objectifs du didacticiel

Ce didacticiel vous amènera à créer un agent IA à partir de zéro pouvant appeler des outils externes : utilisez d'abord Python pour écrire un service d'outils (serveur MCP) conforme aux normes MCP, puis utilisez LangGraph pour le connecter à un agent conversationnel. Après avoir appris, vous pourrez non seulement parcourir les exemples, mais également encapsuler l'API de votre propre système dans un outil pour vous connecter à l'Agent.

Liste de contrôle de préparation

• [ ] Une machine de développement compatible Internet (macOS/Linux/Windows est acceptable), Python 3.10 et supérieur.
• [ ] Installer uv (recommandé, utilisé pour gérer l'environnement Python et les dépendances) : curl -LsSf https://astral.sh/uv/install.sh | sh, puis source ~/.zshrc.
• [ ] Une clé API LLM disponible (les grands modèles OpenAI / Anthropic / domestiques sont acceptables, ce tutoriel utilise l'interface compatible OpenAI comme exemple).
• [ ] Préparez un exemple de « véritable outil » : ce didacticiel utilise "lire le fichier local" comme outil, vous pouvez également le modifier en API météo ou en requête de base de données.
• [ ] (Facultatif) Installez l'outil de débogage visuel MCP Inspector.

Conseils de version : MCP SDK et LangGraph itèrent rapidement. Les numéros de version dans les commandes suivantes sont soumis à la page officielle en temps réel ; en cas d'échec de l'installation, donnez la priorité aux invites du rapport d'erreurs.

Première étape : Créer un projet et un environnement virtuel

mkdir mcp-agent-demo && cd mcp-agent-demo
uv initialisation --python 3.11
uv ajouter "mcp[cli]" langgraph langchain-openai python-dotenv

Remarque : uv init générera pyproject.toml et main.py ; mcp[cli] fournit des commandes d'exécution et de débogage MCP.

Étape 2 : Écrire le premier serveur MCP

Créez server.py pour implémenter un outil de « lecture du contenu des fichiers locaux » :

à partir de mcp.server.fastmcp importer FastMCP

mcp = FastMCP("lecteur de fichiers")

@mcp.tool()
def read_file(chemin : str) -> str :
    """Lire le contenu du fichier texte au chemin spécifié. Utilisé pour démontrer que l'agent appelle des outils externes."""
    essaye :
        avec open(path, "r", encoding="utf-8") comme f :
            retourner f.read(2000)
    sauf exception comme e :
        return f "Échec de lecture : {e}"

si __name__ == "__main__":
    mcp.run()

Point clé : le décorateur @mcp.tool() enregistre une fonction normale en tant qu'outil, et les paramètres de fonction et la chaîne de documentation généreront automatiquement un schéma d'outil que le modèle pourra voir - La description doit être écrite clairement afin que le modèle sache quand l'appeler.

Étape 3 : Vérifier le serveur avec MCP Inspector

uv exécuter mcp dev server.py

Ouvrez « http://localhost:6274 » dans le navigateur et dans l'inspecteur :

1. Sélectionnez l'outil read_file.
2. Entrez le paramètre {"path": "README.md"} (créez d'abord un README.md dans le projet).
3. Cliquez sur Appeler et le contenu du fichier devrait être renvoyé à droite.

Cette étape peut confirmer que « l'outil lui-même est disponible » et isoler d'abord les problèmes au niveau du modèle.

Étape 4 : Créez l'agent avec LangGraph et connectez-vous à l'outil MCP

Créez « agent.py » :

importer asyncio
depuis langchain_openai importer ChatOpenAI
à partir de langgraph.prebuilt import create_react_agent
à partir de langchain_mcp_adapters.client importer MultiServerMCPClient

async def main() :
    asynchrone avec MultiServerMCPClient (
        {"file-reader": {"command": "uv", "args": ["run", "server.py"], "transport": "stdio"}}
    ) en tant que client :
        outils = client.get_tools()
        modèle = ChatOpenAI(model="gpt-4o-mini", température=0)
        agent = create_react_agent (modèle, outils)
        result = wait agent.ainvoke({"messages": [("user", "Veuillez lire le README.md dans le projet et résumer les trois premières lignes")]})
        print(résultat["messages"][-1].content)

si __name__ == "__main__":
    asyncio.run(main())

Exécuter :

export OPENAI_API_KEY="Votre clé"
uv exécuter python agent.py

Résultat attendu : le modèle appelle d'abord l'outil read_file pour lire le fichier, puis donne un résumé basé sur le contenu renvoyé - il s'agit d'un lien complet "Agent → MCP → outil réel".

Étape 5 : Connectez-vous à un véritable outil métier (exemple : requête SQLite)

Étendez server.py avec un outil de « requête de base de données » :

importer sqlite3

@mcp.tool()
def query_sqlite (db_path : str, sql : str) -> str :
    """Exécutez une requête SELECT en lecture seule sur une base de données SQLite et renvoyez les résultats."""
    sinon sql.strip().lower().startswith("select") :
        return "Seules les requêtes SELECT autorisées"
    conn = sqlite3.connect(db_path)
    essaye :
        lignes = conn.execute(sql).fetchmany(10)
        return "\n".join(str(r) for r in rows)
    sauf exception comme e :
        return f "Échec de la requête : {e}"
    enfin :
        conn.close()

Lorsqu'elle est implémentée dans une entreprise, le remplacement de cette requête en lecture seule par « l'encapsulation API interne avec vérification des autorisations » constitue la forme minimale d'un outil de niveau production.

Étape 6 : Configuration, journaux et erreurs courantes

• Journal : ajoutez verbose=True à ChatOpenAI et à l'agent dans agent.py pour observer les appels de l'outil à chaque étape.
• Timeout : le délai d'expiration des appels à l'outil MCP peut être configuré sur le client pour éviter que l'agent ne reste bloqué.
• Rapport et traitement des erreurs courantes :

Méthode de vérification

1. Vérification de la couche d'outils : MCP Inspector teste chaque outil individuellement.
2. Vérification du lien : laissez l'agent effectuer 3 tâches différentes pour confirmer que l'outil est correctement sélectionné à chaque fois.
3. Vérification de régression : consolidez le cas d'utilisation dans un script et réexécutez-le après modification.

Foire aux questions (FAQ)

1. MCP doit-il utiliser Python ?

   Non. Le SDK officiel prend en charge Python et TypeScript, et l'environnement Node utilise @modelcontextprotocol/sdk.

2. Puis-je utiliser ce didacticiel si je n’ai pas de GPU local ?

   capable. Le LLM de ce didacticiel utilise l'API, seule l'inférence de grands modèles nécessite une puissance de calcul et seuls les services d'outils légers sont exécutés localement.

3. Que dois-je faire si l'agent n'appelle jamais l'outil ?

Vérifiez d'abord si la description de l'outil contient la condition de déclenchement « quand appeler », confirmez ensuite que le modèle dispose de capacités d'appel de fonction et enfin utilisez une invite plus simple pour tester.

4. Comment déployer le serveur MCP dans un environnement de production ?

   Le serveur peut être déployé en tant que processus/conteneur indépendant, en utilisant le transport HTTP diffusable au lieu de stdio et en accédant à l'authentification unifiée.

5. Plusieurs outils vont-ils interférer les uns avec les autres ?

   Chaque outil possède un espace de noms et un schéma indépendants. Tant que la description est claire et que les autorisations sont minimisées, il n'y aura généralement aucune interférence ; il est recommandé de limiter le flux dans les scénarios à forte concurrence.

Avancement et expansion

• Orchestration multi-agents : utilisez la machine à états de LangGraph pour diviser « planification-exécution-révision » en plusieurs rôles.
• Registre MCP : créez un centre d'enregistrement d'outils interne pour unifier les versions et les autorisations.
• Ensemble d'évaluation : précipitez les cas d'utilisation commerciale dans une régression automatisée pour éviter toute dérive comportementale.
• Privatisation : remplacez LLM par un modèle de déploiement local (tel que Ollama) pour obtenir un fonctionnement intranet à liaison complète.