# Einführung
In einem aktuellen Artikel Basierend auf Machine Studying Mastery haben wir einen Device-Calling-Agenten entwickelt, der die Anforderungen erfüllt nach außendas heißt Wetter, Nachrichten, Wechselkurse und Zeit aus öffentlichen APIs. In diesem Artikel wurde die Synthesehälfte des Musters intestine behandelt, aber die interessantere Hälfte blieb auf dem Tisch: ein Agent, der über seine eigene Umgebung nachdenkt, seine eigene Maschine inspiziert und Logik auslagert, deren Ausführung er sich nicht zutraut. Man könnte argumentieren, dass dies eher einer wirklichen „agenten Wirkung“ entspricht.
Dieser Artikel knüpft dort an, wo dieser aufgehört hat. Wir geben Gemma 4 zwei neue Instruments – einen lokalen Dateisystem-Explorer mit Sandbox und einen eingeschränkten Python-Interpreter – und beobachten, wie das Modell selbst entscheidet, wann es sich umschaut und wann es berechnet.
Zu den Themen, die wir behandeln werden, gehören:
- Warum „agentische“ Toolaufrufe mehr als nur Net-APIs benötigen, um interessant zu sein
- So erstellen Sie ein Dateisystem-Inspektionstool mit harten Pfaddurchquerungswächtern
- So verbinden Sie ein Python-Interpreter-Device mit dem Modell, ohne ihm die Schlüssel zu Ihrer Maschine zu übergeben
- Wie die gleiche Orchestrierungsschleife von zuvor auf diese neuen Funktionen verallgemeinert wird
Ich kann es Ihnen wärmstens empfehlen Lesen Sie zuerst diesen Artikel bevor es weitergeht.
# Vom Gespräch zur Agentur
Wenn die einzigen Instruments, die Sie einem Sprachmodell zur Verfügung stellen, schreibgeschützte Net-APIs sind, haben Sie im Grunde immer noch einen Chatbot, wenn auch einen mit potenziellem Zugriff auf bessere Informationen. Das Modell erhält eine Eingabeaufforderung, entscheidet, welche API gepingt werden soll, und fügt die JSON-Antwort in einen Absatz ein. Es gibt keine wirkliche Vorstellung davon Umfeldkein zu untersuchender Zustand, keine Konsequenz, über die man nachdenken könnte; Es ist ein Szenario, das eher dem ähnelt Abruf erweiterte Era als echte Agentur.
Agentur, im praktischen Sinne des Praktikers, zeigt sich, wenn ein Modell beginnt, mit dem System zu interagieren, auf dem es läuft. Das kann bedeuten, aus einem lokalen Dateisystem zu lesen, Code auszuführen, Dateien zu ändern, andere Prozesse aufzurufen oder eine beliebige Kombination davon. Sobald ein Device etwas anderes tun kann, als einen sauberen String von einem Distant-Dienst zurückzugeben, muss das Modell mit der Nachfrage beginnen um selbst: Welche Dateien existieren, was bedeutet diese Nummer eigentlich, was befindet sich in diesem Ordner, bevor ich behaupte, dass er etwas enthält.
Die Gemma 4-Familie und insbesondere die gemma4:e2b Die von uns verwendete Edge-Variante ist klein genug, um lokal auf einem Laptop computer zu laufen, und gleichzeitig kompetent genug bei der strukturierten Ausgabe, um diese Artwork von Schleife zuverlässig zu steuern. Diese Kombination macht das lokal-agentische Muster überhaupt erst interessant. Der vollständige Code für dieses Tutorial finden Sie hier.
# Die architektonische Wiederverwendung
Die Orchestrierungsschleife aus dem vorherigen Tutorial ändert sich nicht. Wir definieren Python-Funktionen, machen sie über das JSON-Schema verfügbar, übergeben die Registrierung zusammen mit der Benutzeraufforderung an Ollama und fangen alle ab tool_calls Blockieren Sie die Antwort, führen Sie die angeforderte Funktion lokal aus und hängen Sie das Ergebnis als an instrument-role-Nachricht und fragen Sie das Modell erneut ab, damit es eine endgültige Antwort synthetisieren kann. Das gleiche call_ollama Helfer, das Gleiche TOOL_FUNCTIONS Wörterbuch, das gleiche available_tools Alle Schema-Arrays aus dem vorherigen Tutorial werden angezeigt.
Was sich ändert, ist die Artwork der Werkzeuge selbst. Während es bei der vorherigen Cost ausschließlich um Skinny Shoppers über Distant-APIs ging, führen die, die wir jetzt erstellen, beide Code auf dem Laptop aus. Dadurch verschiebt sich das Designproblem von „Wie analysiere ich diese Antwort“ zu „Wie stelle ich sicher, dass das Modell nicht einmal versehentlich etwas tun kann, was es nicht tun sollte.“
# Device 1: Ein Sandbox-Dateisystem-Explorer
Das erste Werkzeug, list_directory_contentsgibt dem Modell die Möglichkeit zu sehen, welche Dateien in einem bestimmten Ordner vorhanden sind. Das klingt trivial, bis Sie sich daran erinnern os.listdir akzeptiert jede Zeichenfolge, einschließlich /, ~Und ../../and many others. Eine naive Implementierung könnte die „Neugier“ des Modells problemlos direkt auf Ihre API-Schlüssel übertragen.
Die Entwurfswahl hier besteht darin, beim Skriptstart ein sicheres Basisverzeichnis anzuheften und alle Anfragen abzulehnen, die außerhalb dieses Verzeichnisses aufgelöst werden:
# Safety: confine list_directory_contents to this base listing and its descendants
# Set to the present working listing when the script begins
SAFE_BASE_DIR = os.path.abspath(os.getcwd())
def list_directory_contents(path: str = ".") -> str:
"""Lists recordsdata and directories inside a path, constrained to the protected base listing."""
strive:
# Resolve to an absolute path and confirm it sits inside SAFE_BASE_DIR
# This blocks traversal makes an attempt like '../../and many others' or absolute paths like "https://www.kdnuggets.com/"
requested = os.path.abspath(os.path.be part of(SAFE_BASE_DIR, path))
if not (requested == SAFE_BASE_DIR or requested.startswith(SAFE_BASE_DIR + os.sep)):
return (
f"Error: Entry denied. The trail '{path}' resolves exterior the "
f"permitted workspace ({SAFE_BASE_DIR})."
)
...Das Muster ist einfach, aber es lohnt sich, weiter darüber nachzudenken. Wir vertrauen niemals der Saite, die das Modell produziert hat. Wir verbinden es mit dem Basisverzeichnis, lösen es vollständig auf (so .. wird wegnormalisiert) und überprüfen Sie dann, ob der aufgelöste Pfad immer noch mit der Foundation beginnt. Beide /and many others/passwd Und ../../someplace Reduzieren Sie die Pfade auf Pfade, die diese Präfixprüfung nicht bestehen und zuvor abgelehnt wurden os.listdir wird jemals aufgerufen.
Der Relaxation der Funktion dient der Verwaltung: Bestätigen Sie, dass der Pfad existiert und ein Verzeichnis ist, pay attention Sie seinen Inhalt auf und formatieren Sie jeden Eintrag als einen der beiden (DIR) oder (FILE) mit einer Bytegröße. Die zurückgegebene Zeichenfolge ist im Klartext und weist eine Struktur auf, die das Modell im zweiten Durchgang analysieren kann:
entries = sorted(os.listdir(requested))
if not entries:
return f"The listing '{path}' is empty."
strains = (f"Contents of '{path}' ({len(entries)} merchandise(s)):")
for identify in entries:
full = os.path.be part of(requested, identify)
if os.path.isdir(full):
strains.append(f" (DIR) {identify}/")
else:
strive:
dimension = os.path.getsize(full)
strains.append(f" (FILE) {identify} ({dimension} bytes)")
besides OSError:
strains.append(f" (FILE) {identify}")
return "n".be part of(strains)Das JSON-Schema, das wir dem Modell übergeben, ist auf der Parameterseite bewusst freizügig – path ist elective und verwendet standardmäßig das Arbeitsbereichsstammverzeichnis, da sich die nützlichsten ersten Fragen auf den aktuellen Ordner beziehen:
{
"sort": "operate",
"operate": {
"identify": "list_directory_contents",
"description": (
"Lists recordsdata and subdirectories inside a path throughout the person's workspace. "
"Use this to examine the atmosphere earlier than answering questions on native recordsdata."
),
"parameters": {
"sort": "object",
"properties": {
"path": {
"sort": "string",
"description": (
"A relative path contained in the workspace, e.g. '.', 'information', or 'src/utils'. "
"Defaults to the workspace root."
)
}
},
"required": ()
}
}
}Beachten Sie, dass die Beschreibung einen kleinen Teil der Eingabeaufforderungstechnik durchführt: „Verwenden Sie dies, um die Umgebung zu überprüfen, bevor Sie Fragen zu lokalen Dateien beantworten.“ Dieser Satz bringt Gemma 4 dazu, das Device aufzurufen, wenn der Benutzer eine vage Frage zu „meinen Dateien“ stellt, anstatt zu erraten, was dort sein könnte.
# Device 2: Ein eingeschränkter Python-Interpreter
Das zweite Werkzeug, execute_python_codeist das gefährlichere und pädagogisch interessantere von beiden. Die Prämisse ist, dass Sprachmodelle, insbesondere kleine, bei präziser Arithmetik, exakter String-Manipulation und allem, was mehr als ein paar Schritte der Verzweigungslogik umfasst, unzuverlässig sind. Ein Device, mit dem das Modell ein deterministisches Snippet schreiben und ausführen kann, ist eine viel bessere Antwort auf diese Probleme, als es in natürlicher Sprache durchdenken zu lassen.
Die Implementierung verwendet exec() mit einem bewusst reduzierten integrierten Namensraum:
def execute_python_code(code: str) -> str:
"""Executes a snippet of Python code and returns no matter was printed to stdout.
It is a learning-only sandbox. exec() is basically unsafe; don't expose this instrument
to untrusted customers or networks. The restrictions under cease the informal circumstances, not a
decided attacker.
"""
strive:
# A minimal restricted atmosphere. We strip __builtins__ right down to a small
# whitelist in order that, e.g., open(), eval(), and __import__ aren't immediately
# out there from the snippet's international scope.
safe_builtins = {
"abs": abs, "all": all, "any": any, "bool": bool, "dict": dict,
"divmod": divmod, "enumerate": enumerate, "filter": filter, "float": float,
"int": int, "len": len, "listing": listing, "map": map, "max": max, "min": min,
"pow": pow, "print": print, "vary": vary, "repr": repr, "reversed": reversed,
"spherical": spherical, "set": set, "sorted": sorted, "str": str, "sum": sum,
"tuple": tuple, "zip": zip,
}
# Pre-import a few protected, helpful modules so the mannequin does not must.
import math, statistics
restricted_globals = {
"__builtins__": safe_builtins,
"math": math,
"statistics": statistics,
}Ein paar Entscheidungen, die es wert sind, erwähnt zu werden. Wir ersetzen __builtins__ vollständig, anstatt einzelne Funktionen auf die schwarze Liste zu setzen open, eval, exec, compile, __import__, enterund alles andere, was nicht auf unserer Whitelist steht, existiert einfach nicht im Snippet. Wir importieren vor math Und statistics in die Globals des Snippets, weil das Modell ständig nach ihnen greifen wird und wir es lieber nicht zum Kampf zwingen möchten __import__ Einschränkungen. Wir erfassen Customary mit contextlib.redirect_stdout Das Modell erhält additionally genau das zurück, was sein Snippet gedruckt hat:
# Seize stdout so we will hand the printed output again to the mannequin
buffer = io.StringIO()
with contextlib.redirect_stdout(buffer):
exec(code, restricted_globals, {})
output = buffer.getvalue().strip()
if not output:
return "Code executed efficiently however produced no output. Use print() to return a worth."
return f"Output:n{output}"Der Zweig mit leerer Ausgabe ist wichtiger als er aussieht. Kleine Modelle schreiben routinemäßig Ausdrücke wie x = sum(vary(101)) und vergiss das print(x). Es wird ein bestimmter Fehler zurückgegeben, der sie zur Verwendung auffordert print() gibt der Orchestrierungsschleife die Möglichkeit, es erneut zu versuchen; Ohne sie würde das Modell eine endgültige Antwort basierend auf einer leeren Zeichenfolge synthetisieren und sicher einen Wert erfinden.
Ein letztes Wort zur Sicherheit, da der Dokumentstring des Skripts es unverblümt sagt: Dies ist eine lernende Sandbox, keine gehärtete. Ein entschlossener Gegner kann aus einem Python ausbrechen exec Sandbox auf Dutzende Arten, die meisten davon beinhalten die Selbstbeobachtung von Objekten ().__class__.__mro__. Für einen Einzelbenutzeragenten, der auf Ihrem eigenen Laptop computer nach Ihren eigenen Eingabeaufforderungen ausgeführt wird, ist die Whitelist ausreichend. Für alles andere benötigen Sie eine echte Isolationsschicht – einen Unterprozess mit seccompein Behälter, oder RestrictedPython.
# Die Orchestrierungsschleife
Die Struktur der Hauptschleife hat sich gegenüber dem vorherigen Tutorial nicht geändert. Das Modell wird mit der Benutzeraufforderung und der Device-Registrierung abgefragt und ob es mit antwortet tool_callsjeder Anruf wird gegen weitergeleitet TOOL_FUNCTIONS:
if "tool_calls" in message and message("tool_calls"):
print("(TOOL EXECUTION)")
messages.append(message)
num_tools = len(message("tool_calls"))
for i, tool_call in enumerate(message("tool_calls")):
function_name = tool_call("operate")("identify")
arguments = tool_call("operate")("arguments")
...
if function_name in TOOL_FUNCTIONS:
func = TOOL_FUNCTIONS(function_name)
strive:
consequence = func(**arguments)
...
messages.append({
"position": "instrument",
"content material": str(consequence),
"identify": function_name
})Die CLI-Formatierung für dieses Skript ist eine kleine Änderung wert. Der execute_python_code Werkzeuge code Das Argument kann eine mehrzeilige Zeichenfolge mit Zeilenumbrüchen darin sein, die bei naiver Ausgabe einen ASCII-Baum zerstören würde. Wir reduzieren und kürzen String-Argumente nur für die Anzeige; Das Modell erhält weiterhin die vollständige Zeichenfolge, wenn die Funktion ausgeführt wird:
def _short(v):
if isinstance(v, str):
flat = v.exchange("n", "n")
if len(flat) > 60:
flat = flat(:57) + "..."
return f"'{flat}'"
return str(v)
args_str = ", ".be part of(f"{ok}={_short(v)}" for ok, v in arguments.objects())Sobald jedes Device-Ergebnis wieder in den Nachrichtenverlauf eingefügt wird "position": "instrument" Bei diesem Eintrag rufen wir Ollama mit der angereicherten Nutzlast erneut auf und das Modell liefert seine fundierte endgültige Antwort. Gleiches Zwei-Durchlauf-Muster, gleiche Logik.
# Testen der Instruments
Und jetzt testen wir unseren Device-Aufruf. Ziehen gemma4:e2b mit ollama pull gemma4:e2b Wenn Sie dies noch nicht getan haben, führen Sie das Skript aus einem Ordner aus, der Ihnen nichts ausmacht, wenn das Modell einen Blick darauf wirft.
Beginnen wir mit dem Dateisystem-Device. Aus dem Projektverzeichnis:
Welche Skripte befinden sich in meinem aktuellen Ordner und welches soll für die Verarbeitung von CSVs verwendet werden?
Ergebnis:
(SYSTEM)
○ Device: execute_python_code......................(LOADED)
○ Device: list_directory_contents..................(LOADED)
○ Workspace: /Customers/matt/initiatives/gemma_agent.....(SANDBOXED)
(PROMPT)
What scripts are in my present folder, and which one appears prefer it must be used to course of CSVs?
(EXECUTION)
● Querying mannequin...
(TOOL EXECUTION)
└── Calling: list_directory_contents
├─ Args: path="."
└─ Outcome: Contents of '.' (5 merchandise(s)):
(FILE) README.md (412 bytes)
(FILE) csv_cleaner.py (1834 bytes)
(FILE) essential.py (10786 bytes)
(FILE) notes.txt (88 bytes)
(FILE) sales_report.py (2210 bytes)
(EXECUTION)
● Synthesizing outcomes...
(RESPONSE)
Your present folder comprises 5 recordsdata. The one that appears meant for CSV
processing is csv_cleaner.py — its identify strongly suggests it handles CSV enter.
sales_report.py may contact CSV information, however its identify is extra about output than
ingestion.Das Modell rief das Device auf, untersuchte die tatsächlichen Dateinamen und zog eine vernünftige Schlussfolgerung, die auf der Auflistung und nicht auf deren Gewichtungen beruhte. Das ist der Unterschied zwischen Halluzination und Beobachtung.
Als nächstes der Python-Interpreter. Eine kleine Aufgabe, die kleine Fashions zuverlässig falsch machen, wenn man sie im Kopf erledigen soll:
Wie groß ist die Standardabweichung der Zahlen 12, 18, 23, 24, 29, 31, 35, 41, 44, 47, gerundet auf vier Dezimalstellen?
Ergebnis:
(SYSTEM)
○ Device: execute_python_code......................(LOADED)
○ Device: list_directory_contents..................(LOADED)
○ Workspace: /Customers/matt/initiatives/gemma_agent.....(SANDBOXED)
(PROMPT)
What's the customary deviation of the numbers 12, 18, 23, 24, 29, 31, 35, 41, 44, 47, rounded to 4 decimal locations?
(EXECUTION)
● Querying mannequin...
(TOOL EXECUTION)
└── Calling: execute_python_code
├─ Args: code="nums = (12, 18, 23, 24, 29, 31, 35, 41, 44, 47)nprint(rou..."
└─ Outcome: Output:
11.4659
(EXECUTION)
● Synthesizing outcomes...
(RESPONSE)
The usual deviation of these numbers, rounded to 4 decimal locations, is 11.4659.Das Modell hat die Berechnung vollständig ausgelagert; es hat einen Ausschnitt geschrieben, genannt statistics.stdevrundete das Ergebnis und berichtete, was der Dolmetscher sagte. Kein Kopfrechnen, keine Näherung, keine erfundenen signifikanten Ziffern.
Zum Schluss noch der interessantere Fall: eine Eingabeaufforderung, die beide Instruments nacheinander erfordert. Das Mannequin muss den Ordner inspizieren Und Berechnen Sie etwas über das, was es findet:
Schauen Sie sich die Dateien im aktuellen Ordner an und nennen Sie mir die Gesamtgröße in Kilobyte, gerundet auf zwei Dezimalstellen.
Ausgabe:
(SYSTEM)
○ Device: execute_python_code......................(LOADED)
○ Device: list_directory_contents..................(LOADED)
○ Workspace: /Customers/matt/initiatives/gemma_agent.....(SANDBOXED)
(PROMPT)
Have a look at the recordsdata within the present folder and inform me the full dimension in kilobytes, rounded to 2 decimal locations.
(EXECUTION)
● Querying mannequin...
(TOOL EXECUTION)
┌── Calling: list_directory_contents
│ ├─ Args: path="."
│ └─ Outcome: Contents of '.' (5 merchandise(s)):
│ (FILE) README.md (412 bytes)
│ (FILE) csv_cleaner.py (1834 bytes)
│ (FILE) essential.py (10786 bytes)
│ (FILE) notes.txt (88 bytes)
│ (FILE) sales_report.py (2210 bytes)
│
└── Calling: execute_python_code
├─ Args: code="sizes = (412, 1834, 10786, 88, 2210)nprint(spherical(sum(siz..."
└─ Outcome: Output:
15.33
(EXECUTION)
● Synthesizing outcomes...
(RESPONSE)
The 5 recordsdata within the present folder whole 15.33 KB.
Zwei Instruments in der richtigen Reihenfolge, wobei die Ausgabe des einen das Argument des anderen speist – erstellt von einem 2-Milliarden-Parameter-Modell, das auf einem Laptop computer ohne GPU läuft. Das Dateisystem-Device begründet das Modell mit dem, was tatsächlich vorhanden ist; Das Dolmetschertool begründet die Antwort auf dem, was tatsächlich wahr ist. Das Modell trägt den Teil bei, in dem es wirklich intestine ist, nämlich zu entscheiden, welche Frage zu welchem Werkzeug gestellt werden soll.
Es lohnt sich auch, an den Sicherheitsvorrichtungen herumzustochern, um sich zu vergewissern, dass sie halten. Bitten Sie das Modell, den Inhalt aufzulisten /and many others“ erzeugt im Device-Ergebnis die erwartete Ablehnungsmeldung, die das Modell dann ordnungsgemäß zurückmeldet, anstatt eine Verzeichnisliste zu erstellen. Es wird zur Ausführung aufgefordert open('/and many others/passwd').learn() im Inneren erzeugt der Interpreter a NameErrorseit open ist nicht in den Whitelist-Builtins enthalten. Beide Fehler werden zu nützlichen Fehlerzeichenfolgen und nicht zu stillen Kompromissen, was genau das ist, was Sie auf dieser Ebene wollen.
# Abschluss
Das frühere Tutorial hat gezeigt, dass Gemma 4 in Ihrem Namen das Web erreichen kann. Dieses hier zeigt, dass es vorsichtig in die Maschine vordringen kann, an der Sie sitzen, wenn Sie die Sorgfalt eingebaut haben. Sobald Sie eine funktionierende Device-Aufrufschleife haben, lautet die interessante Frage nicht mehr „Kann das Modell eine Funktion aufrufen?“, sondern lautet „Was soll ich damit berühren lassen?“.
Ein dateisystembewusstes Device und ein Code-Ausführungstool bringen Sie gemeinsam auf den Weg zu etwas, das diesen Begriff wirklich verdient Agent: Es kann seine Umgebung beobachten, entscheiden, welche Berechnung wichtig ist, und diese Berechnung deterministisch ausführen, anstatt zu raten. Von da an verallgemeinert sich das Muster. Datenbankabfragen, Shell-Befehle, Git-Operationen, Dokumentenanalyse; Jedes davon ist dasselbe JSON-Schema, dieselbe Dispatch-Tabelle, dieselbe Zwei-Durchgangs-Synthese mit dem Sicherheitsumfang, der für den Explosionsradius des zugrunde liegenden Anrufs geeignet ist.
Bauen Sie zuerst den Umfang. Geben Sie dem Modell dann die Schlüssel zu allem, was sich darin befindet.
Matthew Mayo (@mattmayo13) hat einen Grasp-Abschluss in Informatik und ein Diplom in Information Mining. Als geschäftsführender Herausgeber von KDnuggets & Statistikund Mitherausgeber bei Beherrschung des maschinellen LernensZiel von Matthew ist es, komplexe datenwissenschaftliche Konzepte zugänglich zu machen. Zu seinen beruflichen Interessen zählen die Verarbeitung natürlicher Sprache, Sprachmodelle, Algorithmen für maschinelles Lernen und die Erforschung neuer KI. Seine Mission ist es, das Wissen in der Datenwissenschaftsgemeinschaft zu demokratisieren. Matthew programmiert seit seinem sechsten Lebensjahr.