smolagents - Code-First-KI-Agenten-Spickzettel

smolagents - Code-First-KI-Agenten-Spickzettel

smolagents ist eine minimale, Code-First-Agenten-Bibliothek von Hugging Face. Die zentrale Idee: Statt dass das Modell Tool-Aufrufe als JSON-Blobs emittiert, schreibt ein CodeAgent und führt Python-Code direkt aus. Das Ausdrücken von Aktionen als Code ermöglicht einen einzelnen Schritt, um mehrere Tools aufzurufen, Schleifen und Variablen zu verwenden und Logik zu ketten — was die Anzahl der LLM-Round-Trips reduziert (etwa ~30% weniger) und die Leistung bei komplexen Aufgaben verbessert. Es ist modell-agnostisch, unterstützt Sandbox-Ausführung und bleibt bewusst klein und hackbar.

Installation

Methode	Befehl
pip	pip install smolagents
Mit Tools-Extras	pip install "smolagents[toolkit]"
Sandbox-Extras	pip install "smolagents[e2b]" (oder [docker])
Modell-Schlüssel setzen	export HF_TOKEN=... oder Provider-Schlüssel
Verifizieren	python -c "import smolagents; print('ok')"

Kernkonzepte

Begriff	Bedeutung
CodeAgent	Agent, der Python-Aktionen schreibt (Standard)
ToolCallingAgent	Agent, der klassische JSON-Tool-Aufrufe emittiert
Tool	Ein aufrufbares, das der Agent verwenden kann (mit Schema)
Modell	Das LLM-Backend (HF, OpenAI, LiteLLM, lokal)
Sandbox	Wo generierter Code ausgeführt wird (lokal, E2B, Docker, Modal)

Ein minimaler CodeAgent

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

agent = CodeAgent(
    tools=[WebSearchTool()],
    model=InferenceClientModel(),   # HF Inference API
)

agent.run("How many seconds would it take a cheetah to cross the Golden Gate Bridge?")

Objekt	Rolle
CodeAgent(tools=[...], model=...)	Der Agent
agent.run("task")	Führe eine Aufgabe von Anfang bis Ende aus
WebSearchTool()	Ein eingebautes Tool
InferenceClientModel()	HF-gehostetes Modell-Backend

Modelle

Backend	Klasse
HF Inference API	InferenceClientModel
Lokale Transformers	TransformersModel
Jeder Provider via LiteLLM	LiteLLMModel(model_id="openai/gpt-4o")
OpenAI-kompatibler Server	OpenAIServerModel(...)
vLLM / lokale Endpoints	via LiteLLM / OpenAI-compatible

Tools definieren

from smolagents import tool

@tool
def get_weather(city: str) -> str:
    """Return the weather for a city.

    Args:
        city: The city to look up.
    """
    return f"Sunny in {city}"

agent = CodeAgent(tools=[get_weather], model=InferenceClientModel())

Mechanismus	Verwendung
@tool-Dekorator	Wandle eine typierte Funktion in ein Tool um
Tool-Subklasse	Mehr Kontrolle über Schema/Verhalten
Tool-Sammlungen	Sätze von Tools importieren (z.B. vom Hub)
MCP-Tools	Model Context Protocol-Server verbinden

Sandboxed Execution (Wichtig)

Da CodeAgents generierten Python ausführen, isolieren Sie ihn in der Produktion.

Sandbox	Wie
Lokal (Standard)	Läuft im Prozess — in Ordnung nur für vertrauten Dev
E2B	executor_type="e2b" (Remote-Sandbox)
Docker	executor_type="docker"
Modal	Remote-Sandbox-Ausführung
Erlaubte Imports	Einschränken, welche Module generierter Code importieren darf

agent = CodeAgent(tools=[...], model=..., executor_type="e2b")

Multi-Agent & Retrieval

Muster	Wie
Verwaltete Agenten	Gib einem Agent andere Agenten als Tools
Retrieval/RAG	Ein Retriever-Tool für begründete Antworten hinzufügen
Planung	Periodische Planungsschritte für schwierige Aufgaben aktivieren
Handoffs	Spezialist unter einem Manager-Agent komposieren

Häufige Workflows

# Ein Recherche-Agent, der in Code durchsucht und berechnet
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
agent = CodeAgent(tools=[WebSearchTool()], model=InferenceClientModel(),
                  executor_type="docker")
agent.run("Compare the population growth of Tokyo and Delhi since 2000.")

smolagents im Vergleich zu anderen Agent-Frameworks

Aspekt	smolagents	LangGraph	Pydantic AI
Aktionsformat	Python-Code	Graph/State-Machine	Typisierte Tool-Aufrufe
Größe/Philosophie	Minimal, hackbar	Vollständige State-Orchestrierung	Type-Safe, FastAPI-Style
LLM-Effizienz	Weniger Anrufe (Code)	Hängt ab	Standard
Best für	Single-Agent-Code-Schleifen	Langlebige State-Agenten	Type-Safe-Produktions-Agenten

Ressourcen

• GitHub-Repository
• Offizielle Dokumentation
• Guided Tour