AI Agent Framework + MCP-Integration Tutorial auf Nanny-Ebene: Erstellen Sie einen Agenten von Grund auf, der externe Tools aufrufen kann

🛒 Für Entwickler ein One-Stop-Einführungs-Tutorial von der Umgebungsvorbereitung über das Schreiben von MCP-Server bis hin zum gemeinsamen Debuggen von LangGraph.

Lernziele

In diesem Tutorial erfahren Sie, wie Sie einen KI-Agenten von Grund auf erstellen, der externe Tools aufrufen kann: Schreiben Sie zunächst mit Python einen Tool-Service (MCP-Server), der den MCP-Standards entspricht, und verbinden Sie ihn dann mit LangGraph mit einem Konversationsagenten. Nach dem Lernen können Sie nicht nur die Beispiele durchgehen, sondern auch die API Ihres eigenen Systems in ein Tool kapseln, um eine Verbindung zum Agenten herzustellen.

Vorbereitungscheckliste

• [ ] Eine internetfähige Entwicklungsmaschine (macOS/Linux/Windows ist akzeptabel), Python 3.10 und höher.
• [ ] Install uv (empfohlen, wird zum Verwalten der Python-Umgebung und -Abhängigkeiten verwendet): curl -LsSf https://astral.sh/uv/install.sh | sh, dann source ~/.zshrc.
• [ ] Ein verfügbarer LLM-API-Schlüssel (OpenAI-/Anthropic-/inländische große Modelle sind akzeptabel, dieses Tutorial verwendet die OpenAI-kompatible Schnittstelle als Beispiel).
• [] Bereiten Sie ein Beispiel für ein „echtes Tool“ vor: In diesem Tutorial wird „Lokale Datei lesen“ als Tool verwendet. Sie können es auch in eine Wetter-API oder eine Datenbankabfrage ändern.
• [ ] (Optional) Installieren Sie das visuelle Debugging-Tool MCP Inspector.

Versionstipps: MCP SDK und LangGraph iterieren schnell. Die Versionsnummern in den folgenden Befehlen unterliegen der offiziellen Echtzeitseite; Wenn die Installation fehlschlägt, geben Sie den Eingabeaufforderungen im Fehlerbericht Vorrang.

Schritt eins: Projekt und virtuelle Umgebung erstellen

„Bash mkdir mcp-agent-demo && cd mcp-agent-demo uv init --python 3.11 uv add „mcp[cli]“ langgraph langchain-openai python-dotenv „

Hinweis: „uv init“ generiert „pyproject.toml“ und „main.py“; „mcp[cli]“ stellt MCP-Laufzeit- und Debugging-Befehle bereit.

Schritt 2: Schreiben Sie den ersten MCP-Server

Erstellen Sie „server.py“, um ein Tool zum „Lesen lokaler Dateiinhalte“ zu implementieren:

„Python aus mcp.server.fastmcp FastMCP importieren

mcp = FastMCP("file-reader")

@mcp.tool() def read_file(path: str) -> str: „“„Lesen Sie den Inhalt der Textdatei im angegebenen Pfad. Wird verwendet, um zu demonstrieren, wie der Agent externe Tools aufruft.““ Versuchen Sie: mit open(path, "r",kodierung="utf-8") als f: return f.read(2000) außer Ausnahme als e: return f"Lesen fehlgeschlagen: {e}"

if name == "main": mcp.run() „

Kernpunkt: Der Dekorator „@mcp.tool()“ registriert eine normale Funktion als Werkzeug, und die Funktionsparameter und die Dokumentationszeichenfolge generieren automatisch ein Werkzeugschema, das das Modell sehen kann – Die Beschreibung muss klar geschrieben sein, damit das Modell weiß, wann es sie aufrufen muss.

Schritt 3: Überprüfen Sie den Server mit MCP Inspector

„Bash uv mcp dev server.py ausführen „

Öffnen Sie „http://localhost:6274“ im Browser und im Inspektor:

1. Wählen Sie das Tool „read_file“.
2. Geben Sie den Parameter „{“path“: „README.md“}“ ein (erstellen Sie zuerst eine README.md im Projekt).
3. Klicken Sie auf „Aufrufen“. Der Dateiinhalt sollte rechts angezeigt werden.

Dieser Schritt kann bestätigen, dass „das Tool selbst verfügbar ist“ und Probleme zunächst auf Modellebene isolieren.

Schritt 4: Erstellen Sie einen Agenten mit LangGraph und stellen Sie eine Verbindung zum MCP-Tool her

Erstellen Sie „agent.py“:

„Python Asynchron importieren aus langchain_openai ChatOpenAI importieren aus langgraph.prebuilt import create_react_agent aus langchain_mcp_adapters.client MultiServerMCPClient importieren

async def main(): asynchron mit MultiServerMCPClient( {"file-reader": {"command": "uv", "args": ["run", "server.py"], "transport": "stdio"}} ) als Kunde: tools = client.get_tools() model = ChatOpenAI(model="gpt-4o-mini", Temperatur=0) agent = create_react_agent(model, tools) result = wait agent.ainvoke({"messages": [("user", "Bitte lesen Sie die README.md im Projekt und fassen Sie die ersten drei Zeilen zusammen")]}) print(result["messages"][-1].content)

if name == "main": asyncio.run(main()) „

Ausführen:

„Bash export OPENAI_API_KEY="Ihr Schlüssel" uv python agent.py ausführen „

Erwartete Ausgabe: Das Modell ruft zuerst das Tool „read_file“ auf, um die Datei zu lesen, und gibt dann eine Zusammenfassung basierend auf dem zurückgegebenen Inhalt aus – dies ist ein vollständiger Link „Agent → MCP → echtes Tool“.

Schritt 5: Verbindung zu einem echten Geschäftstool herstellen (Beispiel: SQLite abfragen)

Erweitern Sie „server.py“ mit einem „Datenbank abfragen“-Tool:

„Python sqlite3 importieren

@mcp.tool() def query_sqlite(db_path: str, sql: str) -> str: „Führen Sie eine schreibgeschützte SELECT-Abfrage für eine SQLite-Datenbank aus und geben Sie die Ergebnisse zurück.““ wenn nicht sql.strip().lower().startswith("select"): Rückgabe „Nur SELECT-Abfragen erlaubt“ conn = sqlite3.connect(db_path) Versuchen Sie: rows = conn.execute(sql).fetchmany(10) return „\n“.join(str(r) für r in Zeilen) außer Ausnahme als e: return f"Abfrage fehlgeschlagen: {e}" schließlich: conn.close() „

Bei der Implementierung in einem Unternehmen ist das Ersetzen dieser schreibgeschützten Abfrage durch „interne API-Kapselung mit Berechtigungsüberprüfung“ die Mindestform eines Tools auf Produktionsebene.

Schritt 6: Konfiguration, Protokolle und häufige Fehler

• Protokoll: Fügen Sie „verbose=True“ zu „ChatOpenAI“ und agent in „agent.py“ hinzu, um die Tool-Aufrufe bei jedem Schritt zu beobachten.
• Timeout: Das Timeout für MCP-Tool-Aufrufe kann auf dem Client konfiguriert werden, um zu verhindern, dass der Agent hängen bleibt.
• Häufige Fehlerberichterstattung und -behandlung:

Verifizierungsmethode

1. Überprüfung der Werkzeugschicht: MCP Inspector testet jedes Werkzeug einzeln.
2. Linküberprüfung: Lassen Sie den Agenten drei verschiedene Aufgaben ausführen, um jedes Mal zu bestätigen, dass das Tool richtig ausgewählt wurde.
3. Regressionsüberprüfung: Konsolidieren Sie den Anwendungsfall in einem Skript und führen Sie es nach der Änderung erneut aus.

Häufig gestellte Fragen (FAQ)

1. Muss MCP Python verwenden?

   NEIN. Das offizielle SDK unterstützt Python und TypeScript und die Node-Umgebung verwendet „@modelcontextprotocol/sdk“.

2. Kann ich dieses Tutorial verwenden, wenn ich keine lokale GPU habe?

   fähig. Das LLM in diesem Tutorial verwendet eine API, nur große Modellinferenzen erfordern Rechenleistung und nur einfache Tooldienste werden lokal ausgeführt.

3. Was soll ich tun, wenn der Agent das Tool nie aufruft?

Überprüfen Sie zunächst, ob die Toolbeschreibung die Auslösebedingung „Wann aufzurufen“ enthält, bestätigen Sie zweitens, dass das Modell über Funktionsaufruffunktionen verfügt, und verwenden Sie schließlich eine einfachere Eingabeaufforderung zum Testen.

4. Wie wird MCP Server in einer Produktionsumgebung bereitgestellt?

   Der Server kann als unabhängiger Prozess/Container bereitgestellt werden, der streambaren HTTP-Transport anstelle von stdio verwendet und auf eine einheitliche Authentifizierung zugreift.

5. Beeinträchtigen sich mehrere Tools gegenseitig?

   Jedes Tool verfügt über einen unabhängigen Namespace und Schema. Solange die Beschreibung klar ist und die Berechtigungen auf ein Minimum beschränkt sind, kommt es in der Regel nicht zu Störungen. Es wird empfohlen, den Fluss in Szenarien mit hoher Parallelität zu begrenzen.

Weiterentwicklung und Erweiterung

• Multi-Agent-Orchestrierung: Verwenden Sie die Zustandsmaschine von LangGraph, um „Planung-Ausführung-Überprüfung“ in mehrere Rollen aufzuteilen.
• MCP Registry: Erstellen Sie ein internes Tool-Registrierungscenter, um Versionen und Berechtigungen zu vereinheitlichen.
• Bewertungssatz: Überführen Sie Geschäftsanwendungsfälle in eine automatisierte Regression, um Verhaltensabweichungen zu verhindern.
• Privatisierung: Ersetzen Sie LLM durch ein lokales Bereitstellungsmodell (z. B. Ollama), um einen Full-Link-Intranet-Betrieb zu erreichen.