KI-Agenten mit smolagents: Wann sich Python-Aktionen lohnen

Für KI-Agenten, die Tools und Berechnungen flexibel in Python kombinieren sollen, ist smolagents eine gute Wahl – vorausgesetzt, der erzeugte Code bekommt eine kontrollierte Ausführungsumgebung. Hugging Face bietet dafür 2 Agentenklassen: CodeAgent und ToolCallingAgent. Der Unterschied liegt darin, ob das Modell seine nächste Aktion als Python-Code oder als strukturierten Tool-Aufruf formuliert. Der schlanke Ansatz hilft bei klar abgegrenzten Aufgaben. Die Verantwortung für dauerhaft gespeicherte Workflow-Zustände, Berechtigungen und Isolation bleibt dennoch bei der Anwendung.

Am 31. Oktober 2026 anhand der aktuellen Dokumentation von Hugging Face, LangChain und OpenAI geprüft. Die folgenden Empfehlungen vergleichen, wie sich Aktionen zusammensetzen, Workflows steuern und Ausführungsgrenzen ziehen lassen. Es handelt sich um Architekturentscheidungen, nicht um Leistungsbenchmarks.

Wie smolagents KI-Agenten mit Python steuert

smolagents ist eine quelloffene Python-Bibliothek von Hugging Face für Agenten, deren Aktionen aus ausführbarem Code bestehen können. Ein Agent durchläuft eine vom Modell gesteuerte Schleife: Er wählt eine Aktion, wertet das Ergebnis aus und entscheidet über den nächsten Schritt. CodeAgent formuliert die Aktion in Python, ToolCallingAgent als strukturierten Tool-Aufruf. Beide erhalten ein Modell und einen Satz Tools. Agentenreferenz von Hugging Face.

CodeAgent lässt sich mit einem Rechercheassistenten vergleichen, der zwischen seinen Beobachtungen kurze Skripte schreiben darf. Er kann über ein freigegebenes Tool Datensätze abrufen, die Ergebnisse umformen und daraus eine Antwort berechnen. Fähigkeiten und Grenzen gibt die Anwendung vor; das Modell übernimmt einen Teil der Logik, die beides verbindet.

Das unterscheidet ihn von einem Assistenten, der eine Codedatei zur Prüfung abliefert. Hier ist der generierte Code selbst das Mittel, mit dem der Agent seine nächste Aktion ausführt.

Für den Vergleich ist entscheidend, welcher Teil der Anwendung flexibel sein muss:

Die letzten beiden Zeilen beschreiben die dokumentierten Schwerpunkte von LangGraph und dem OpenAI Agents SDK, keine exklusiven Fähigkeiten. Die Wahl hängt davon ab, an welcher Stelle das Framework Struktur vorgeben soll.

smolagents CodeAgent: Das Modell stellt Aktionen zusammen

CodeAgent lohnt sich, wenn sich die Zwischenschritte leichter in Python ausdrücken lassen als mit einer festen Auswahl an Aufrufen. Hugging Face nennt Schleifen, Bedingungen und die Kombination mehrerer Tools als Stärken. Zugleich müssen Syntaxfehler, Ausnahmen und unerwartetes Verhalten abgefangen werden. Einführung in die Funktionsweise.

Ein Beispiel ist die Suche nach Widersprüchen in Bestandsdaten. Ein Entwickler stellt dafür ein Tool bereit, das passende Datensätze ausschließlich lesend abruft. Der Agent muss möglicherweise Namen vereinheitlichen, ähnliche Einträge gruppieren und ein Feld aufsummieren, bevor er entscheidet, welche Datensätze einen weiteren Abruf erfordern. Solche Zwischenschritte lassen sich gut in Python ausdrücken.

Das Ausführungsergebnis bildet die Grundlage für die nächste Entscheidung des Modells. Eine fehlgeschlagene Berechnung ist eine Beobachtung, auf die der Agent reagieren kann. Sie belegt nicht, dass er den Fehler erfolgreich selbst beheben wird.

ToolCallingAgent: Aktionen bleiben in einem festen Rahmen

ToolCallingAgent ist der bessere Ausgangspunkt, wenn die verfügbaren Operationen bereits klar definierte Schnittstellen haben. Er erzeugt strukturierte JSON-Aufrufe mit Tool-Namen und Argumenten statt Python-Aktionen. Vergleich von Hugging Face.

Für einen Supportassistenten, der eine Bestellung nachschlägt und eine Richtlinie abruft, kann das ausreichen. Vorhersehbare Datenumformungen übernimmt gewöhnlicher Anwendungscode. Wenn ein Workflow bereits sauber in definierte Funktionen passt, schafft generiertes Python eine zusätzliche Fehlerquelle ohne erkennbaren Nutzen.

Auch strukturierte Aufrufe brauchen eine Berechtigungsprüfung. Eine formal korrekte Anfrage zur Stornierung einer Bestellung kann für den betreffenden Kunden die falsche Aktion sein. Das Schema sagt dem Programm, was angefordert wurde. Ob es erlaubt ist, entscheidet die Anwendung.

Tools und Modelle lassen sich unabhängig wählen

Das Tool-Angebot sollte eng begrenzt bleiben; das Modell lässt sich davon unabhängig auswählen. Diese Trennung macht smolagents praktisch interessant: Die Arbeitsweise des Modells lässt sich verändern, ohne jede fachliche Funktion neu zu definieren.

Tools sind Funktionen mit klarer Schnittstelle

Ein smolagents-Tool versieht eine Funktion mit einem Namen, einer Beschreibung, Metadaten zu den Eingaben und einem Ausgabetyp. Für einfache Funktionen mit Typannotationen und einem aussagekräftigen Docstring eignet sich der Dekorator @tool. Aufwendigere Tools lassen sich als Unterklasse von Tool umsetzen; ihre Ausführungslogik gehört in forward. Anleitung zu Tools.

Ein Bestandsassistent sollte beispielsweise „Datensätze im freigegebenen Katalog nachschlagen“ können, statt uneingeschränkten Datenbankzugriff zu erhalten. Mandantenprüfungen, Abfragebeschränkungen und Grenzen für die Antwortmenge gehören in die Implementierung. Ein nachdrücklich formulierter Prompt ersetzt diese Prüfungen nicht.

Tools lassen sich auch über das Model Context Protocol (MCP) einbinden, eine standardisierte Schnittstelle, die Modellanwendungen Tools bereitstellt. Hinzu kommen Adapter für LangChain-Tools und Hugging Face Spaces. Die Wiederverwendung eines Tools sagt jedoch nichts über die Vertrauenswürdigkeit seiner Implementierung aus. Beim Laden von Hub-Tools verlangt Hugging Face ausdrücklich trust_remote_code=True, weil diese eigenen Code ausführen. Dokumentation zur Einbindung und zum Laden von Tools.

Diese Entscheidung erfordert eine Codeprüfung. Bevor ein Tool dem Agenten zur Verfügung steht, sollten seine Implementierung und seine Abhängigkeiten geprüft werden.

Das Modell-Backend legt die Sandbox nicht fest

Die aktuelle Modellreferenz beschreibt mehrere Möglichkeiten:

• InferenceClientModel stellt die Verbindung über Hugging Face Inference Providers her.
• LiteLLMModel nutzt die Anbieterintegration von LiteLLM.
• TransformersModel führt ein Transformers-Modell lokal aus.
• OpenAIModel verbindet sich mit einem OpenAI-kompatiblen Modellserver.

Die Einführung behandelt außerdem Ollama für lokale Inferenz. Das sind Optionen für das Backend, keine Zusage, dass jedes Modell Codegenerierung oder Tool-Auswahl gleich gut beherrscht.

Zwei Fragen müssen getrennt bleiben: Wo läuft das Modell, und wo läuft der von ihm erzeugte Python-Code? Ein gehostetes Modell kann einen Docker-Executor steuern. Ein lokales Modell kann weiterhin unsichere Aktionen erzeugen. Wer die Inferenz auf den eigenen Rechner verlagert, schafft damit noch keine abgegrenzte Ausführungsumgebung.

Sobald es über eine Demonstration hinausgeht, sollte das Modell für reproduzierbare Abläufe ausdrücklich konfiguriert werden. Hugging Face weist darauf hin, dass sich das Standardmodell von InferenceClientModel ändern kann. Modellkonfiguration.

Ein kleines Beispiel aus der Dokumentation

Die Rechenaufgabe aus der Dokumentation zeigt den Ausführungsweg, bevor weitere Tools hinzukommen. Im Einstiegsbeispiel von Hugging Face soll der Agent mit einem leeren Tool-Satz die Zahlen von 1 bis 10 addieren. Die folgende Variante behält diese Aufgabe bei und ergänzt das Kontextmanager-Muster für Docker aus der Sandbox-Anleitung. Originalbeispiel, Einrichtung der Docker-Ausführung.

1. 1

   Umgebung vorbereiten

   Laut Installationsanleitung wird Python 3.10 oder neuer benötigt; empfohlen wird eine virtuelle Umgebung. Für dieses Beispiel muss außerdem Docker installiert sein und laufen. Installationsanleitung.

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   Die Umgebungsvariable HF_TOKEN muss einen Hugging Face-Token enthalten, der zum Aufruf von Inference Providers berechtigt. InferenceClientModel kann diese Variable automatisch auslesen. Der Token gehört nicht in das Skript. Verhalten bei der Authentifizierung.

2. 2

   Die dokumentierte Aufgabe in Docker ausführen

   Folgenden Code als sum_agent.py speichern:

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   Anschließend ausführen:

   python sum_agent.py

   Der Kontextmanager räumt die Sandbox auf, sobald der Block verlassen wird. Das Beispiel ist aus der Dokumentation abgeleitet; es zeigt kein Ergebnis eines für diesen Artikel durchgeführten Tests.

3. 3

   Ergebnis und Ausführungsgrenze prüfen

   Das mathematisch erwartete Ergebnis ist 55, berechnet als 10 × 11 ÷ 2. Das Modell entscheidet selbst, welchen Python-Code es erzeugt. Ein exakt gleicher Ablauf oder identische Formulierungen sind deshalb nicht bei jedem Durchlauf zu erwarten.

   tools=[] bedeutet, dass keine eigenen Tools übergeben wurden. CodeAgent kann trotzdem Python ausführen. Erst die Executor-Einstellung verlagert den generierten Code nach Docker.

Für diese fest vorgegebene Berechnung ist gewöhnlicher Python-Code die sinnvolle Lösung in einer Anwendung. Das Beispiel soll die Mechanik des Agenten sichtbar machen. Ein Agent ist dann angebracht, wenn die Wahl der Zwischenschritte Teil des Problems ist – nicht schon deshalb, weil sich die Berechnung in natürlicher Sprache beschreiben lässt.

Agenten, die Code ausführen, brauchen eine Sandbox

Generierter Python-Code muss als nicht vertrauenswürdig gelten und in einer eigens eingerichteten Sandbox ausgeführt werden, bevor er mit nicht vertrauenswürdigen Eingaben arbeitet. Der standardmäßig verwendete lokale Executor ist ein eingeschränkter Interpreter. Er garantiert nicht, dass das Hostsystem isoliert bleibt. Hugging Face nennt Modellfehler, Prompt-Injection und gezielte Angriffsanfragen als Risiken. Sichere Codeausführung.

Der lokale Interpreter wertet den abstrakten Syntaxbaum von Python, also die geparste Programmstruktur, Operation für Operation aus. Er beschränkt Imports und Untermodule und begrenzt die Zahl der Operationen. Diese Maßnahmen verringern die Angriffsfläche. Die gesonderte Sicherheitsanleitung warnt dennoch vor den Risiken lokaler Ausführung. Jedes zusätzlich erlaubte Paket erweitert den Zugriffsspielraum des generierten Programms.

Welche Sandbox-Optionen nennt Hugging Face?

Die aktuelle Executor-API unterstützt neben dem lokalen Executor auch Blaxel, E2B, Modal und Docker. Die folgenden Konfigurationswerte entsprechen der CodeAgent-Referenz und der Executor-Referenz.

Die Wahl des Anbieters und die Einrichtung der Zugangsdaten sind von diesen Einstellungen getrennt. Die Installationsdokumentation führt die optionalen Abhängigkeiten auf. Die Installation eines Extras allein ergibt noch keine konfigurierte Bereitstellung.

Für ein internes Experiment kann Docker eine konkrete, überprüfbare Ausführungsgrenze schaffen. Bei einem Dienst, der nicht vertrauenswürdige Anfragen verarbeitet, sollte sich die Umgebung nach den erforderlichen Maßnahmen für Isolation, Lebenszyklus und Betrieb richten. Der umfassendere Vergleich von Code-Sandboxes für KI-Agenten behandelt diese Infrastrukturentscheidung.

Eine Sandbox für Codeausschnitte umfasst nicht das ganze Agentensystem

Bevor weitere Agenten hinzukommen, muss klar sein, was innerhalb der Sandbox läuft. Hugging Face unterscheidet zwischen der Ausführung generierter Codeausschnitte in einer Sandbox und der Ausführung des gesamten Agentensystems darin. Die Sicherheitsanleitung weist darauf hin, dass die auf Codeausschnitte beschränkte Variante keine verwalteten Agenten unterstützt – also Agenten, die ein anderer Agent als Helfer aufruft. Das gesamte System in die Sandbox zu verlagern, erfordert mehr Einrichtung und gegebenenfalls die Übergabe von Zugangsdaten. Sandbox-Ansätze.

Das hat Folgen für die Architektur. Muss ein später ergänzter Spezialagent innerhalb der Ausführungsumgebung ein Modell aufrufen, reicht das ursprüngliche Muster „Code senden, Ergebnis empfangen“ möglicherweise nicht mehr aus. Bei einer veränderten Bereitstellung müssen daher auch der Ablageort der Zugangsdaten und die Abhängigkeiten der Tools erneut geprüft werden.

Bei einem Dienst für Kunden müssen erlaubte Dateien, Netzwerkziele und aufrufbare Operationen feststehen, bevor der Agent startet. Jeder Durchlauf sollte nur die Zugriffsrechte erhalten, die seine Aufgabe erfordert. Zeitüberschreitungen, Abbruch und Aufräumen gehören zu den regulär vorgesehenen Ausführungspfaden – auch dann, wenn das Modell nicht zum Abschluss kommt.

Wann sich der schlanke Ansatz lohnt – und wann nicht

Die schwierigste Steuerungsaufgabe der Anwendung sollte die Framework-Wahl bestimmen. Ein kurzer Initialisierungsaufruf ist praktisch. Wichtiger ist aber, wie viel Code die Anwendung darum herum noch braucht.

smolagents oder LangGraph: flexible Aktionen oder persistente Abläufe?

LangGraph ist der bessere Ausgangspunkt, wenn ein Prozess anhand expliziter fachlicher Zustände gespeichert, angehalten und wieder aufgenommen werden muss. Die Orchestrierungslaufzeit bietet grundlegende Bausteine für zustandsbehaftete Workflows, einschließlich Persistenz und menschlicher Eingriffe. Sie kann deterministische mit modellgesteuerten Schritten kombinieren und setzt LangChain nicht voraus. Überblick zu LangGraph.

Ein Beschaffungsprozess sammelt etwa Belege, wartet auf eine Führungskraft und läuft nach deren Freigabe weiter. Im Mittelpunkt stehen hier der Erhalt des Prozesszustands und die Durchsetzung zulässiger Zustandsübergänge. Wenn diese Anforderungen das Produkt bestimmen, ist LangGraph ein sinnvoller Einstieg.

Der Aufwand liegt im Workflow-Entwurf, der selbst zu leisten bleibt: Zustände, Übergänge, Persistenz und die genaue Bedeutung einer Schrittwiederholung. Für den Beschaffungsprozess ist dieser Aufwand gerechtfertigt. Für einen klar begrenzten Recherchehelfer, der Daten liest, eine Antwort berechnet und danach stoppt, kann er unnötige Struktur schaffen.

smolagents passt, wenn vor allem unklar ist, welche Python-Operationen die Aufgabe lösen. LangGraph passt, wenn die entscheidende Frage lautet, wie der Prozess sicher durch dauerhaft gespeicherte Zustände geführt wird. Das ist eine Empfehlung für den Entwurf, keine Aussage, dass eines der Frameworks ausschließlich für eine bestimmte Art von Aufgabe geeignet wäre.

OpenAI Agents SDK: Übergaben, Prüfungen und Traces

Das OpenAI Agents SDK ist die passendere Standardwahl, wenn die Koordination spezialisierter Agenten und Prüfungen im Betrieb den Kern der Anwendung bilden. Bei Handoffs geht die Verantwortung für das Gespräch an einen anderen Agenten über. Mit dem Agents-as-Tools-Muster kann dagegen ein steuernder Agent für die Antwort verantwortlich bleiben. Dokumentation zur Orchestrierung.

Bei einem Kundensupportassistenten lässt sich die Übernahme eines Gesprächs durch einen Abrechnungsspezialisten unter Umständen klarer abbilden als durch einen allgemeinen Python-Problemlöser. Das integrierte Tracing protokolliert Modellaufrufe, Tool-Aufrufe, Handoffs und Guardrails. Guardrails führen automatisierte Prüfungen durch; Mechanismen für menschliche Kontrolle halten sensible Aktionen an, bis eine Entscheidung vorliegt. Tracing, Guardrails und Freigaben.

Die Richtlinien der Anwendung bleiben selbst zu bestimmen: Welche Aktionen brauchen eine Freigabe, wie wird ein Tool korrekt implementiert und wie geht das System mit unterbrochener Arbeit um? Diese Bausteine nehmen solche Entscheidungen nicht ab. Das SDK dokumentiert zudem Muster für Sandbox-Agenten; Codeausführung ist also kein Alleinstellungsmerkmal von smolagents.

smolagents ist vorzuziehen, wenn das flexible Zusammensetzen von Python-Aktionen die benötigte Funktion ist und eine kleine Agentenschleife genügt. Das Agents SDK passt besser, wenn seine Bausteine für Koordination und Prüfung den Anforderungen der Anwendung entsprechen. Das Etikett „schlank“ allein entscheidet diesen Vergleich nicht.

Eine größere Auswahl bietet der Vergleich von Frameworks für KI-Agenten. Wer eine fertige Agentenanwendung installieren möchte, statt eine Anwendung um eine Bibliothek herum zu bauen, findet im Leitfaden zu quelloffenen KI-Agenten einen Einstieg.

Was bei Code-Agenten übertrieben wird

Ein kleines Framework macht eine unberechenbare Aufgabe nicht berechenbar. Python ist ausdrucksstark. Daraus folgt aber nicht, dass das Modell die richtigen Datensätze ausgewählt, eine Einheit korrekt interpretiert oder eine Geschäftsregel eingehalten hat.

Aus der Kombinierbarkeit von Aktionen lässt sich kein allgemeiner Geschwindigkeitsvorteil ableiten. Werden Operationen zusammengefasst, kann sich der Ablauf verändern. Über das Ergebnis entscheiden weiterhin Modell, Aufgabe, Tool-Verhalten und Ausführungsumgebung. Eine Entscheidung nach Leistung erfordert Messungen an der eigenen Aufgabe.

Eine konkrete Grenze sollte dabei bekannt sein: max_steps hat in der aktuellen Agenten-API den Standardwert 20. Dieser begrenzt die Zahl der Agentenschritte, nicht den Ressourcenverbrauch einer einzelnen Python-Aktion. Die API bietet außerdem Callbacks, verwaltete Agenten und Prüfungen der endgültigen Antwort. Minimalismus bedeutet hier also nicht, dass es keine Kontrollmöglichkeiten gibt. Agentenreferenz.

Für den Betrieb müssen Ausführungszeit und Ressourcenverbrauch deshalb separat begrenzt werden. Eine maximale Schrittzahl ersetzt keine Sandbox-Richtlinie, und eine Sandbox garantiert kein korrektes Ergebnis.

Ein sinnvoller Einstieg für die nächste Woche

Am Anfang sollte eine klar begrenzte, ausschließlich lesende Aufgabe stehen, deren Ergebnis unabhängig überprüfbar ist. Wer smolagents als Python-Entwickler erproben möchte, könnte einen von sensiblen Daten bereinigten Bestandsexport und ein eng begrenztes Nachschlage-Tool verwenden. Die vom Agenten gemeldeten Unstimmigkeiten lassen sich anschließend mit bekannten Beispielen vergleichen.

Zu erfassen ist, ob der Agent die richtigen Datensätze auswählt, Tools korrekt nutzt, nach erwartbaren Fehlern weiterarbeiten kann und innerhalb der gesetzten Grenzen stoppt. Eine deterministische Vergleichslösung sollte erhalten bleiben. Folgt die Aufgabe immer demselben Ablauf, gehört dieser in gewöhnlichen Code. Auch Hugging Face empfiehlt, nach Möglichkeit deterministische Funktionen einzusetzen. Leitfaden zum Bau guter Agenten.

CodeAgent lohnt sich, sobald das dynamische Zusammensetzen von Python-Aktionen seine zusätzliche Komplexität rechtfertigt. ToolCallingAgent genügt, wenn eine definierte Auswahl an Tools ausreicht. Erfüllt der bestehende Workflow bereits seine Anforderungen, kann die Migration warten. Werden dauerhaft gespeicherte Freigabeprozesse oder Übergaben an spezialisierte Agenten zentral, sollte die Framework-Wahl erneut geprüft werden.

Installation und Kompatibilität

Wie wird smolagents mit pip installiert?

Die Kernbibliothek wird mit pip install smolagents installiert. Hinzu kommen die Extras, die für Tools, Modelle oder die Ausführungsumgebung benötigt werden. Das Beispiel verwendet smolagents[docker].

Was gilt für HfApiModel in smolagents?

Für neuen Code ist die Schnittstelle InferenceClientModel aus der aktuellen Dokumentation maßgeblich. Bevor Imports aus älteren Beispielen übernommen werden, sollten sie mit der aktuellen Modellreferenz abgeglichen werden.

Wie lässt sich smolagents mit Docker nutzen?

Docker installieren und starten, das Docker-Extra installieren und executor_type="docker" wählen. Die Ausführungsgrenze muss passend zur jeweiligen Aufgabe konfiguriert werden. Die Einstellung allein bildet noch keine vollständige Sicherheitsrichtlinie.

Praktische Tipps zur Entwicklung mit KI im Newsletter erhalten.