Eigene Tools & Skills bauen – Teil 3 der Serie 'KI‑Agenten in der Praxis'

Ein KI-Agent, der nur kommuniziert, ist ein Chatbot. Erst durch Tools und Skills wird er zum handlungsfähigen Akteur, der Daten abruft, Dateien bearbeitet oder APIs ansteuert. Im dritten Teil der Serie geht es an die praktische Umsetzung: Wie Werkzeuge für OpenClaw, LangChain und das Model Context Protocol (MCP) gebaut werden – inklusive konkreter Code-Beispiele.

Auf einen Blick

• OpenClaw Skills: Nutzen Markdown-Dateien mit YAML-Frontmatter. Der Zugriff lässt sich laut offizieller Dokumentation gezielt über Umgebungsvariablen oder System-Binaries steuern.
• LangChain Tools: Basieren auf einem @tool-Decorator in Python. Type-Hints definieren das Schema für das LLM, während die ToolRuntime den Kontext liefert.
• MCP Tools: Folgen dem offenen Model Context Protocol. Sie nutzen standardisierte Endpunkte für Discovery und JSON-Schemata für die Parameter-Validierung.

Einsatzszenarien für eigene Tools

Vorgefertigte Tools decken Standard-Szenarien ab. Die eigentliche Stärke eines Agenten zeigt sich jedoch erst, wenn er die spezifische Business-Logik eines Unternehmens versteht. Eigene Tools sind wichtig, um interne APIs wie CRM- oder Ticket-Systeme anzubinden, Systemintegrationen wie Datenbankabfragen durchzuführen oder branchenspezifische Compliance-Checks zu automatisieren. So wird der Agent vom reinen Textgenerator zum System-Operator.

OpenClaw Skills: Die dateibasierte Lösung

OpenClaw nutzt AgentSkills-kompatible Ordnerstrukturen. Jeder Skill besteht aus einem Verzeichnis mit einer SKILL.md-Datei, die YAML-Frontmatter und die eigentlichen Anweisungen für das LLM enthält.

Basis-Struktur einer SKILL.md

---
name: weather-check
description: Hole aktuelle Wetterdaten für eine Stadt
metadata:
  {
    "openclaw": {
      "requires": { "env": ["OPENWEATHER_API_KEY"] },
      "primaryEnv": "OPENWEATHER_API_KEY"
    }
  }
---

Verwende dieses Tool, um aktuelle Wetterdaten für eine bestimmte Stadt abzurufen.

## Parameter
- `city` (string): Stadtname, z.B. "Berlin" oder "Hamburg"
- `units` (string, optional): Einheit – "metric" (Celsius) oder "imperial" (Fahrenheit)

## Rückgabe
String mit Temperatur, Bedingungen und Luftfeuchtigkeit.

Ein zentrales Konzept bei OpenClaw ist das Gating: Skills lassen sich über metadata.openclaw.requires filtern, beispielsweise nach vorhandenen Umgebungsvariablen oder installierten Programmen. Workspace-Skills überschreiben dabei Projekt- oder Personal-Skills. Laut OpenClaw-Spezifikation muss bei der Nutzung mit einem Basis-Token-Overhead von 195 Zeichen plus etwa 97 Zeichen pro Skill gerechnet werden. Über ClawHub lassen sich diese Skills bei Bedarf als Pakete verteilen.

Praxis-Beispiel: Ein CSV-Analyse-Skill

---
name: csv-analyzer
description: Analysiere CSV-Dateien – Summe, Durchschnitt, Anzahl
metadata:
  {
    "openclaw": {
      "requires": { "bins": ["python3"] }
    }
  }
---

Analysiere eine CSV-Datei mit grundlegenden Statistiken.

## Parameter
- `filepath` (string): Pfad zur CSV-Datei
- `column` (string): Spaltenname für die Analyse
- `operation` (string): "sum", "average" oder "count"

## Beispiel
`/csv-analyzer filepath=data.csv column=revenue operation=sum`

LangChain Tools: Das Framework-agnostische Modell

Im LangChain-Ökosystem verwandelt der @tool-Decorator reguläre Python-Funktionen in Agenten-Werkzeuge. Type-Hints sind hierbei zwingend erforderlich, da das Framework daraus das Input-Schema für das LLM generiert.

Einfaches Tool mit @tool

from langchain.tools import tool

@tool
def get_weather(city: str, units: str = "metric") -> str:
    """Hole aktuelle Wetterdaten für eine Stadt.
    
    Args:
        city: Stadtname
        units: "metric" (Celsius) oder "imperial" (Fahrenheit)
    """
    # API-Aufruf implementieren
    return f"22°C in {city}, sonnig"

Für komplexere Anforderungen empfiehlt die LangChain-Dokumentation die Nutzung von Pydantic-Modellen zur sauberen Validierung der Eingabedaten.

Erweitertes Tool mit Pydantic-Schema

from pydantic import BaseModel, Field
from langchain.tools import tool

class WeatherInput(BaseModel):
    """Input für Wetter-Abfragen."""
    city: str = Field(description="Stadtname oder Koordinaten")
    units: str = Field(default="metric", description="'metric' oder 'imperial'")
    include_forecast: bool = Field(default=False, description="5-Tage-Vorhersage einbeziehen")

@tool(args_schema=WeatherInput)
def get_weather_advanced(
    city: str, 
    units: str = "metric", 
    include_forecast: bool = False
) -> str:
    """Hole detaillierte Wetterdaten."""
    # Implementierung
    return f"Wetter in {city}: 22°C"

Wenn das Tool auf den internen Zustand des Agenten oder auf Langzeit-Speicher zugreifen muss, kommt die ToolRuntime ins Spiel.

Kontext-Zugriff mit ToolRuntime

from langchain.tools import tool, ToolRuntime

@tool
def get_user_balance(account_id: str, runtime: ToolRuntime) -> str:
    """Hole Kontostand für einen Nutzer."""
    # Zugriff auf Kontext-Daten
    user_id = runtime.context.user_id
    store = runtime.store
    
    # Langzeit-Speicher abfragen
    balance = store.get(("balances",), account_id)
    return f"Kontostand: {balance.value if balance else 'Nicht gefunden'}"

MCP: Der offene Standard

Das Model Context Protocol etabliert einen Standard für die Integration von LLMs mit externen Datenquellen. Es trennt den Tool-Provider, also den Server, architektonisch sauber von der LLM-Anwendung als Client.

MCP Tool-Definition

{
  "name": "github_create_issue",
  "description": "Erstelle ein GitHub-Issue",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "body": { "type": "string" },
      "labels": { 
        "type": "array", 
        "items": { "type": "string" } 
      }
    },
    "required": ["title"]
  }
}

Da MCP oft in verteilten Systemen eingesetzt wird, ist eine strikte Validierung aller Parameter gegen das definierte JSON-Schema essenziell. Authentifizierung, Autorisierung und sauberes Audit-Logging der Tool-Aufrufe gehören hier zur grundlegenden Architektur. Fehler sollten außerdem strukturiert im Result-Objekt zurückgegeben werden, um Protokoll-Abbrüche auf Client-Seite zu vermeiden.

Entscheidungsmatrix

Die Wahl des passenden Ansatzes hängt stark von der bestehenden Infrastruktur ab. OpenClaw Skills eignen sich für isolierte OpenClaw-Umgebungen, in denen eine einfache Verteilung über ClawHub und integrierte Gating-Mechanismen gefragt sind. Wer ohnehin tief im LangChain- oder LangGraph-Ökosystem arbeitet und komplexes State-Management in Python benötigt, greift zu nativen LangChain Tools. MCP spielt seine Stärken aus, wenn Werkzeuge für mehrere unterschiedliche Clients bereitgestellt werden sollen und eine klare Server-Client-Trennung nach offenen Protokollstandards gefordert ist.

Best Practices für die Tool-Entwicklung

Unabhängig vom gewählten Framework gelten für robuste Agenten-Werkzeuge einige gemeinsame Regeln:

• Atomare Operationen: Ein Tool erfüllt genau eine Aufgabe, zum Beispiel „Nutzer erstellen“ statt „Nutzer verwalten“. Das reduziert Halluzinationen bei der Parameterübergabe.
• Sprechende Fehlerbehandlung: Das LLM benötigt konkrete Hinweise wie „API-Schlüssel ungültig“ oder „Datei nicht gefunden“ statt generischer HTTP-Fehlercodes, um sein Verhalten selbstständig zu korrigieren.
• Security-First: Inputs müssen validiert, Dateipfade bereinigt und Rate-Limits implementiert werden, um Missbrauch durch unvorhergesehene LLM-Aufrufe zu verhindern.
• Präzise Dokumentation: Die Tool-Beschreibung wird vom LLM gelesen und interpretiert. Je genauer die Instruktion, desto zielgerichteter der Einsatz.

Integration in der Praxis

Der Einstieg in die Tool-Entwicklung gelingt iterativ. Den Anfang machen Read-Only-Tools wie Wetter-APIs oder Datenbankabfragen, da hier das Risiko von Fehlmanipulationen gering ist. Im zweiten Schritt folgen Write-Operations wie Datenexporte oder POST-Requests. Sobald diese stabil laufen, können zustandsbehaftete Tools für Session-Management oder Multi-Step-Workflows integriert werden. Die höchste Stufe bilden orchestrierte Workflows, die mehrere Tools kombinieren, etwa Daten importieren, transformieren und als Report versenden.

Werkzeuge übersetzen die analytischen Fähigkeiten der KI in messbaren geschäftlichen Nutzen. Im vierten Teil der Serie geht es darum, wie diese Tools in robusten Multi-Agenten-Systemen orchestriert werden.