Mein Agent Dev: KI-Agenten dazu bringen, echte Dinge zu tun

Die Idee ist einfach: Erstelle eine dünne Abstraktionsschicht um jede SDK-Funktion, die dein Agent verwenden muss. Dieser Wrapper sollte:

• Allgemeine, agentenfreundliche Argumente akzeptieren (z.B. `event_details`, `project_name`, `task_description`).
• Alle SDK-spezifischen Initialisierungen, Authentifizierungen und Datenübersetzungen übernehmen.
• Ein standardisiertes Ergebnis zurückgeben (z.B. `success: bool`, `message: str`, `data: dict`).
• SDK-spezifische Fehler erfassen und als allgemeinere Ausnahmen weitergeben oder sie intern behandeln.

Beispiel: Wrapping des GitHub SDK (PyGithub)

Angenommen, dein Agent muss neue GitHub-Issues erstellen. Anstatt direkt `repo.create_issue(…)` aus dem Kern deines Agenten aufzurufen, würdest du einen Wrapper erstellen.

# tools/github_tools.py
from github import Github, Auth
from github.GithubException import GithubException

class GitHubTools:
 def __init__(self, token: str):
 # GitHub-Client einmal initialisieren
 self.auth = Auth.Token(token)
 self.g = Github(auth=self.auth)

 def _get_repo(self, repo_owner: str, repo_name: str):
 try:
 return self.g.get_user(repo_owner).get_repo(repo_name)
 except GithubException as e:
 raise ValueError(f"Repository {repo_owner}/{repo_name} konnte nicht gefunden werden: {e}")

 def create_issue(self, repo_owner: str, repo_name: str, title: str, body: str = "", labels: list = None):
 """
 Erstellt ein neues GitHub-Issue im angegebenen Repository.
 Args:
 repo_owner (str): Der Besitzer des Repositorys.
 repo_name (str): Der Name des Repositorys.
 title (str): Der Titel des Issues.
 body (str, optional): Der Text/die Beschreibung des Issues. Standardmäßig "".
 labels (list, optional): Eine Liste von anzuwendenden Labels. Standardmäßig None.
 Returns:
 dict: Ein Wörterbuch, das den Erfolg und die Details des erstellten Issues angibt.
 Raises:
 ValueError: Wenn das Repository nicht gefunden wird oder die Erstellung des Issues fehlschlägt.
 """
 try:
 repo = self._get_repo(repo_owner, repo_name)
 issue = repo.create_issue(title=title, body=body, labels=labels if labels else [])
 return {
 "success": True,
 "message": f"Issue '{issue.title}' erfolgreich erstellt.",
 "issue_url": issue.html_url,
 "issue_number": issue.number
 }
 except GithubException as e:
 raise ValueError(f"Erstellung des GitHub-Issues fehlgeschlagen: {e}")
 except Exception as e:
 raise RuntimeError(f"Ein unerwarteter Fehler ist aufgetreten: {e}")

# In dem Haupt-Skript deines Agenten oder bei der Tool-Registrierung:
# github_token = os.getenv("GITHUB_TOKEN")
# github_manager = GitHubTools(token=github_token)
# agent_tools = [github_manager.create_issue] # Oder übergebe den gesamten Manager und lasse den Agenten die Methoden auswählen

Nun muss dein Agent nichts über `GithubException` oder die genaue Signatur von `repo.create_issue` wissen. Er ruft einfach `create_issue` mit einem klaren Satz von Argumenten auf und erhält eine konsistente Antwort. Wenn du später entscheidest, von PyGithub zu einem benutzerdefinierten HTTP-Client zu wechseln, bleibt die Kern-Logik deines Agenten unangetastet.

Strategie 2: Das „Tool Manifest“ für dynamisches Laden

Wenn dein Agent wächst und Zugriff auf mehr Tools benötigt, wird es mühsam, jeden SDK-Wrapper manuell zu importieren und zu instanziieren. Hier kommt ein „Tool Manifest“ oder „Tool-Registry“ ins Spiel. Es ist eine Möglichkeit, Tools basierend auf Konfigurationen dynamisch zu laden und zu registrieren, die oft in einer YAML- oder JSON-Datei gespeichert sind.

Dieses Muster ist besonders nützlich, wenn du Tools aktivieren oder deaktivieren möchtest, ohne deinen Agenten neu bereitzustellen, oder wenn verschiedene Instanzen deines Agenten auf unterschiedliche Werkzeugsets zugreifen müssen (z.B. ein „dev“-Agent vs. ein „prod“-Agent).

So funktioniert es:

1. Definiere eine Konfigurationsdatei, die deine verfügbaren Tools, deren Klassen und notwendige Initialisierungsparameter (wie API-Schlüssel) auflistet.
2. Erstelle eine `ToolRegistry`-Klasse, die dieses Manifest liest.
3. Bei der Initialisierung importiert die `ToolRegistry` dynamisch die angegebenen Tool-Klassen und instanziiert sie.
4. Der Agent fordert dann Tools von diesem Verzeichnis an.

Beispiel: Ein einfaches Tool Manifest und Registry

Erweitern wir unser GitHub-Beispiel und stellen uns vor, wir hätten auch ein „Slack-Benachrichtigungs“-Tool.

# config/tools.yaml
tools:
 - name: github_issue_creator
 class_path: tools.github_tools.GitHubTools
 init_params:
 token_env_var: GITHUB_TOKEN # Sagt dem Registry, dass nach GITHUB_TOKEN in den Umgebungsvariablen gesucht werden soll
 methods:
 - create_issue
 - name: slack_notifier
 class_path: tools.slack_tools.SlackNotifier
 init_params:
 webhook_url_env_var: SLACK_WEBHOOK_URL
 methods:
 - send_message

# core/tool_registry.py
import yaml
import importlib
import os

class ToolRegistry:
 def __init__(self, config_path: str = "config/tools.yaml"):
 self.tools = {}
 self._load_tools_from_config(config_path)

 def _load_tools_from_config(self, config_path: str):
 with open(config_path, 'r') as f:
 config = yaml.safe_load(f)

 for tool_conf in config.get('tools', []):
 tool_name = tool_conf['name']
 class_path = tool_conf['class_path']
 init_params = tool_conf.get('init_params', {})
 methods_to_register = tool_conf.get('methods', [])

 module_name, class_name = class_path.rsplit('.', 1)
 module = importlib.import_module(module_name)
 tool_class = getattr(module, class_name)

 # Umgebungsvariablen für Initialisierungsparameter auflösen
 resolved_init_params = {}
 for param_key, param_value in init_params.items():
 if param_key.endswith('_env_var'):
 env_var_name = param_value
 resolved_init_params[param_key.replace('_env_var', '')] = os.getenv(env_var_name)
 if resolved_init_params[param_key.replace('_env_var', '')] is None:
 print(f"Warnung: Umgebungsvariable '{env_var_name}' für das Werkzeug '{tool_name}' nicht gesetzt.")
 else:
 resolved_init_params[param_key] = param_value
 
 tool_instance = tool_class(**resolved_init_params)
 
 # Registriere spezifische Methoden der Werkzeuginstanz
 self.tools[tool_name] = {}
 for method_name in methods_to_register:
 method = getattr(tool_instance, method_name, None)
 if method and callable(method):
 self.tools[tool_name][method_name] = method
 else:
 print(f"Warnung: Methode '{method_name}' nicht gefunden oder nicht aufrufbar im Werkzeug '{tool_name}'.")

 def get_tool_method(self, tool_name: str, method_name: str):
 """
 Ruft eine spezifische Methode von einem registrierten Werkzeug ab.
 """
 if tool_name in self.tools and method_name in self.tools[tool_name]:
 return self.tools[tool_name][method_name]
 return None

 def get_all_callable_tools(self):
 """
 Gibt eine flache Liste aller registrierten aufrufbaren Werkzeugmethoden zurück.
 Nützlich für die Übergabe an agentische Frameworks.
 """
 all_methods = []
 for tool_obj in self.tools.values():
 for method in tool_obj.values():
 all_methods.append(method)
 return all_methods

# Im Hauptskript Ihres Agenten:
# tool_registry = ToolRegistry()
# create_github_issue = tool_registry.get_tool_method("github_issue_creator", "create_issue")
# send_slack_message = tool_registry.get_tool_method("slack_notifier", "send_message")

# Oder für Frameworks wie LangChain:
# available_tools = tool_registry.get_all_callable_tools()
# agent = AgentExecutor.from_agent_and_tools(agent=llm_agent, tools=available_tools, verbose=True)

Dieser Ansatz bietet Ihnen viel mehr Flexibilität. Sie können neue Werkzeuge hinzufügen, indem Sie einfach die `tools.yaml` aktualisieren und sicherstellen, dass die entsprechenden Python-Dateien in Ihrem `PYTHONPATH` vorhanden sind. Es trennt auch sauber die Definition der Werkzeuge von der Kernlogik Ihres Agenten.

Strategie 3: Konsistente Werkzeugbeschreibung für LLMs

Gut, jetzt haben Sie Ihre SDKs gekapselt und dynamisch geladen. Großartig. Aber wie weiß Ihr von LLM unterstützter Agent tatsächlich, welches Werkzeug er verwenden und welche Argumente er übergeben soll? Hier kommen die Werkzeugbeschreibungen ins Spiel.

Die meisten agentischen Frameworks verlassen sich darauf, dem LLM eine detaillierte Beschreibung jedes Werkzeugs bereitzustellen, einschließlich seines Namens, Zwecks und der Parameter, die es akzeptiert. Dies geschieht häufig in Form eines Pydantic-Modells oder eines JSON-Schemas, das das LLM „lesen“ kann und dann basierend auf seinem Verständnis der Anfrage des Benutzers einen Aufruf generiert.

Der Schlüssel hierbei ist Konsistenz. Wenn Ihr `create_issue` Werkzeug `repo_owner`, `repo_name`, `title` und `body` erwartet, stellen Sie sicher, dass Ihre Werkzeugbeschreibung dies genau widerspiegelt. Unklarheiten hier führen schnell zu `tool_execution_error`-Nachrichten.

Wie man Werkzeuge beschreibt (wenn man Pydantic nicht direkt verwendet):

Wenn Sie einen benutzerdefinierten Agenten erstellen oder einfach mehr Kontrolle wünschen, können Sie Ihre Werkzeugwrapper mit einem `description` Attribut oder einer Methode erweitern, die ein strukturiertes Schema zurückgibt. Dies ist oft notwendig für Frameworks, die Python-Funktionen in Werkzeugbeschreibungen für das LLM umwandeln.

# tools/github_tools.py (fortgesetzt)
# ... innerhalb der GitHubTools-Klasse ...

 def create_issue(self, repo_owner: str, repo_name: str, title: str, body: str = "", labels: list = None):
 # ... (bestehende Implementierung) ...
 pass

 create_issue.description = {
 "name": "create_github_issue",
 "description": "Erstellt ein neues Issue in einem angegebenen GitHub-Repository.",
 "parameters": {
 "type": "object",
 "properties": {
 "repo_owner": {"type": "string", "description": "Der GitHub-Benutzername oder der Name der Organisation des Repository-Besitzers."},
 "repo_name": {"type": "string", "description": "Der Name des GitHub-Repositorys."},
 "title": {"type": "string", "description": "Der Titel des neuen GitHub-Issues."},
 "body": {"type": "string", "description": "Die detaillierte Beschreibung für das GitHub-Issue (optional)."},
 "labels": {"type": "array", "items": {"type": "string"}, "description": "Eine Liste von Labels, die auf das Issue angewendet werden sollen (optional)."}
 },
 "required": ["repo_owner", "repo_name", "title"]
 }
 }

Dieses `description` Attribut (oder ein ähnlicher Mechanismus, je nach Ihrem Framework) ist das, was das LLM sieht. Je besser und genauer es ist, desto zuverlässiger wird Ihr Agent die richtigen Werkzeuge mit den richtigen Argumenten aufrufen.

Handlungsanweisungen für Ihren nächsten Agentenbau

Also, wir haben das Einwickeln von SDKs, dynamisches Laden und klare Beschreibungen behandelt. Hier ist eine schnelle Zusammenfassung dessen, was Sie noch heute tun können:

1. SDK-Logik isolieren: Lassen Sie niemals rohe SDK-Aufrufe oder SDK-spezifische Fehlerbehandlung in Ihre Kernagentenlogik eindringen. Erstellen Sie dedizierte Wrapper-Funktionen oder Klassen für jede externe Interaktion.
2. Eingaben/Ausgaben standardisieren: Gestalten Sie Ihre Werkzeugwrapper so, dass sie agentenfreundliche Argumente akzeptieren und konsistente, leicht parsbare Ergebnisse zurückgeben (z. B. ein Dictionary mit `success`, `message` und `data`).
3. Automatisches Laden von Werkzeugen: Verwenden Sie einen konfigurationsgesteuerten Ansatz (wie ein YAML-Manifest und ein Registry), um Ihre Werkzeuge dynamisch zu laden und zu registrieren. Dies macht Ihren Agenten flexibler und einfacher zu erweitern.
4. Klare Werkzeugbeschreibungen: Investieren Sie Zeit in das Schreiben präziser und eindeutiger Beschreibungen für Ihre Werkzeuge, einschließlich ihrer Parameter. Dies ist entscheidend, damit Ihr LLM sie effektiv auswählen und nutzen kann. In Erwägung ziehen, Pydantic-Modelle dafür zu verwenden, wenn Ihr Framework dies unterstützt, da es starke Typisierung und automatische Schemaerstellung bietet.
5. Solide Fehlerbehandlung: Fangen Sie in Ihren Werkzeugwrappern SDK-spezifische Ausnahmen ab und übersetzen Sie diese in allgemeinere, umsetzbare Fehler oder informative Nachrichten für den Agenten. Lassen Sie nicht einfach rohe SDK-Fehler bis in die Denkabläufe Ihres Agenten aufsteigen.
6. Über Authentifizierung nachdenken: Zentralisieren Sie, wie Ihre Werkzeuge ihre Anmeldeinformationen (API-Schlüssel, Tokens) erhalten. Umgebungsvariablen sind in der Regel ein guter Ausgangspunkt, besonders in Kombination mit einem Werkzeug-Registry, der sie auflöst.

Agenten zu bauen, die wirklich mit der Welt interagieren, macht die Sache wirklich interessant und ehrlich gesagt, auch ein bisschen chaotisch. Aber indem Sie diese architektonischen Muster anwenden, können Sie das Chaos in Schach halten und sicherstellen, dass Ihre Agenten nicht nur intelligent, sondern auch zuverlässig und wartbar sind.

Was sind Ihre größten Schmerzpunkte bei der Integration von SDKs in Ihre Agenten? Schreiben Sie mir in den Kommentaren oder auf Twitter – ich höre immer gerne, was Sie bauen!

Verwandte Artikel

• AI-Agenten mit Go bauen
• Die Fallstricke navigieren: Häufige Fehler beim Bau autonomer Agenten
• DSPy im Jahr 2026: 7 Dinge nach 3 Monaten Nutzung

🕒 Published: March 27, 2026