Tool Calling in Symfony AI bedeutet: Das Sprachmodell ruft deine eigenen PHP Methoden auf. Du markierst eine Klasse mit dem Attribut AsTool, legst sie in eine Toolbox und übergibst diese dem Agent. Ab dann entscheidet das Modell selbst, wann es dein Werkzeug braucht, mit welchen Argumenten es aufgerufen wird und was es mit dem Ergebnis anstellt. Alle Beispiele auf dieser Seite stammen aus dem offiziellen Cookbook, dem Symfony AI Repository und der Symfony AI Demo.

Mehr Code braucht ein erstes Tool nicht. Name und Beschreibung im Attribut sagen dem Modell, was das Werkzeug tut, die Parameterbeschreibungen kommen aus den @param Einträgen im PHPDoc. Der Rückgabewert muss kein String sein: Arrays, Objekte, Skalare und DateTimeInterface wandelt der ToolResultConverter selbst um, ein eigenes json_encode ist also überflüssig.

Never Code Alone arbeitet täglich mit Symfony AI. Wir nutzen Tool Calling intensiv und wissen deshalb, wo der Weg vom ersten AsTool Attribut bis zum belastbaren Feature wirklich lang wird. Ein Tool ist am Ende ein ganz normaler Service, der getestet, statisch geprüft und sauber injiziert gehört. Dazu kennen wir das Ökosystem drumherum aus der Praxis: Symfony AI Mate, das PHP Framework Neuron AI und Symfony selbst seit über 15 Jahren.

Wir liefern schnell. Das Setup kommt fertig: Docker für eine reproduzierbare Umgebung, ein Proxy wie LiteLLM davor für Budgets, Routing und Verbrauch pro Team, dazu CI/CD Pipelines mit PHPStan, Psalm und PHPUnit, die jedes Tool bei jedem Commit prüfen. So bekommt ein bestehendes Projekt zuverlässige AI Features auf Enterprise Level, ohne dass jemand monatelang evaluiert.

Damit das im Team hält, kommt die Schulung dazu. Wir zeigen an eurer eigenen Codebase, wie ein Tool geschnitten, beschrieben, validiert und getestet wird, und übergeben den Betrieb an eure Entwickler. Rund um das Thema helfen wir beim Vibe Coding Consulting, beim Weg vom Prototyp zur Produktion, beim Codebase Audit für KI generierten Code und beim Aufbau DSGVO konformer self hosted KI mit Ollama.

Der Ablauf ist immer gleich. Du legst deine Tools in eine Toolbox und übergibst sie dem Agent. Symfony AI schickt die Tool Beschreibungen als JSON Schema mit dem Prompt an das Modell. Braucht das Modell ein Werkzeug, antwortet es nicht mit Text, sondern mit einem Tool Call. Symfony AI ruft deine Methode auf, hängt das Ergebnis als Nachricht an und fragt das Modell erneut. Das läuft so lange, bis eine Antwort steht.

Danach reicht eine ganz normale Nachricht. Der Agent findet die verfügbaren Tools selbst, entscheidet über den Aufruf, führt ihn aus und baut das Ergebnis in seine Antwort ein.

Ein Detail lohnt den zweiten Blick: Der Agent kennt den Parameter maxToolCalls, der standardmäßig bei 50 liegt. Ein Modell kann Tool Calls verketten, das Ergebnis des einen führt zum nächsten Aufruf. Ohne Deckel wird daraus im schlechtesten Fall eine Endlosschleife auf deiner Kreditkarte. In der Produktion setzen wir diesen Wert bewusst niedrig und loggen jeden Ausreißer. Tool Calling funktioniert übrigens auch mit Streaming: Die Aufrufe laufen im Hintergrund weiter, während die Antwort Token für Token beim Nutzer ankommt.

Nicht jedes Werkzeug musst du selbst schreiben. Die Agent Component bringt fertige Tools mit, jedes als eigenes Composer Paket: Wikipedia, YouTube, SimilaritySearch, Brave und SerpApi. Die Installation ist ein Einzeiler.

Danach landet das Tool zusammen mit deinen eigenen in derselben Toolbox. Das Modell sieht schlicht eine Liste von Werkzeugen und trifft seine Wahl.

Genau hier zahlt sich Zurückhaltung aus. Jedes Tool wird als JSON Schema mit jedem Aufruf mitgeschickt, und je größer die Auswahl, desto häufiger greift ein Modell daneben. Drei gut beschriebene Werkzeuge schlagen zehn halbgare.

Die offizielle Demo Anwendung zeigt den Alltagsfall: ein Tool, das ein eigenes Repository durchsucht. Es ist ein ganz normaler Symfony Service mit Constructor Injection. Der PHPDoc Kommentar über der Methode ist kein Beiwerk, aus ihm entsteht die Beschreibung des Parameters, an der sich das Modell orientiert.

Kein Vector Store, keine Magie, nur ein Treffer im Speicher. Auffällig ist die lange Beschreibung im Attribut: Sie sagt dem Modell nicht nur, was das Tool tut, sondern auch, wie es die Ergebnisse weiterverwenden soll. Der Rückgabewert darf ein Array oder ein JsonSerializable Objekt sein, Symfony AI wandelt das selbst in JSON um. Eine Klasse kann außerdem mehrere Tools tragen: Das Wikipedia Tool aus dem Repository trägt AsTool zweimal und verweist über den Parameter method auf die Methoden search und article.

In einer Symfony Anwendung übernimmt das AI Bundle die Verdrahtung. Du definierst deinen Agent in der Konfiguration und listest die Tools auf, die er nutzen darf. Die Toolbox baut das Bundle daraus selbst, inklusive Dependency Injection. Das ist der Auszug aus der offiziellen Demo Konfiguration:

Zwei Wege stehen nebeneinander. Eine Klasse mit AsTool Attribut wird einfach als Klassenname eingetragen. Ein bestehender Service ohne Attribut, hier die Symfony Clock, bekommt Name, Beschreibung und Methode direkt in der Konfiguration. Der System Prompt ist dabei Teil der Absicherung: Der Satz, nie auf das eigene Gedächtnis zu vertrauen und nie Filme zu erfinden, hält das Modell in den Werkzeugen. Für einzelne Aufrufe lässt sich die Auswahl zusätzlich einschränken, indem beim call nur bestimmte Tool Namen übergeben werden.

Die Argumente eines Tool Calls kommen aus einem Sprachmodell. Sie sind damit Nutzereingaben, nicht mehr und nicht weniger. Symfony AI kennt dafür das Schema Attribut direkt am Methodenargument. Das offizielle Wetter Tool zeigt es an der Vorhersage, die nur zwischen einem und sechzehn Tagen erlaubt ist:

Ein Punkt wird dabei gern übersehen: Das Schema allein beschreibt nur, es erzwingt nichts. Erst der ValidateToolCallArgumentsListener weist einen Aufruf mit falschen Argumenten zurück, bevor deine Methode überhaupt läuft. Im AI Bundle ist dieser Listener automatisch registriert, im Standalone Betrieb musst du ihn selbst am Event Dispatcher anmelden. Bei Backed Enums als Argumenttyp passiert die Prüfung ganz ohne Attribut, weil das Schema die erlaubten Werte bereits kennt.

Symfony AI feuert rund um jeden Tool Call Events. Damit lässt sich die Kette steuern, ohne ein einziges Tool anzufassen. Das offizielle Beispiel bricht nach dem Wetter Tool sofort ab und gibt das Ergebnis strukturiert zurück, statt es noch einmal durch das Modell zu schicken:

Das zweite Event ist für die Absicherung noch wichtiger. ToolCallRequested feuert vor der Ausführung. Ein Listener kann den Aufruf dort mit deny und einer Begründung blockieren oder mit setResult ein eigenes Ergebnis unterschieben, ohne dass deine Methode je läuft. Genau das ist der Platz für eine menschliche Freigabe bei Tools, die löschen, stornieren oder Geld bewegen. Welche Tools eine Bestätigung brauchen, hinterlegst du sauber im Metadata Feld des AsTool Attributs, statt Namen im Listener zu pflegen. Für Laufzeitfehler gibt es zusätzlich die FaultTolerantToolbox, die Exceptions abfängt und dem Modell eine lesbare Fehlermeldung statt eines Absturzes liefert.

Tool Calling ist der Punkt, an dem echte Daten ins Spiel kommen. Ein Tool liest aus der Datenbank, und das Ergebnis geht als Nachricht an das Modell. Läuft dieses Modell bei einem US Anbieter, verlässt der Inhalt der Abfrage das Haus. Genau deshalb testen wir Tool Setups zuerst gegen lokale Modelle über Ollama. Symfony AI unterstützt Ollama als Platform, der Wechsel ist eine Zeile in der Konfiguration.

Für Tool Calling reichen kleinere Modelle oft aus, weil die Aufgabe klar umrissen ist: Werkzeug wählen, Argumente füllen, Ergebnis formulieren. Wie gut ein Modell mit Werkzeugen umgeht, ist allerdings sehr unterschiedlich. Wir haben die Kandidaten in unserem Überblick zu lokalen Modellen für Tool Calling und MCP eingeordnet.

Für Unternehmen mit Compliance Anforderungen kombinieren wir das mit gehosteter Inferenz in Deutschland. Unser Infrastruktur Partner Conversis aus Duisburg betreibt die Server dafür. Wichtig bleibt die Grundregel: In der Entwicklung arbeitet der Agent gegen eine lokale Umgebung mit Testdaten, echte Daten kommen erst dazu, wenn die Inferenz im eigenen Netzwerk läuft. Mehr dazu auf unserer Seite zu Self Hosted KI für Unternehmen.

Ein Tool ist eine gewöhnliche PHP Klasse. Es gibt also keinen Grund, es nicht zu testen. Die Methode selbst prüfst du mit einem ganz normalen Unit Test in PHPUnit: Repository mocken, Argument reinreichen, Rückgabe prüfen. Kein API Key, keine Wartezeit, keine Kosten.

Für die Ebene darüber liefert Symfony AI den MockAgent. Er beantwortet definierte Eingaben mit festen Ergebnissen und zählt dabei mit, wie oft und womit er aufgerufen wurde. So sieht das im Test des Repositories aus:

Damit lässt sich der Service testen, der den Agent nutzt, ohne dass ein Modell antworten muss. Eine unbekannte Eingabe quittiert der MockAgent mit einer Exception, was Lücken in den Testdaten sofort sichtbar macht. Zusammen mit PHPStan in der CI/CD Pipeline bleibt ein Agent Feature genauso überprüfbar wie jeder andere Teil der Anwendung.

In gewachsenen Symfony Anwendungen steckt die interessante Logik längst in Services. Tool Calling macht daraus ohne Umbau die Fähigkeiten eines Agents. Der Weg dorthin ist kurz, weil ein Tool nichts weiter braucht als ein Attribut und eine gute Beschreibung. Die Demo zeigt das an einem Repository, das vorher schon da war.

Wer weiter gehen will, veröffentlicht Tools per MCP und macht sie damit auch außerhalb der eigenen Anwendung nutzbar. Für die Entwicklungsseite deckt Symfony AI Mate genau diesen Weg ab. NCA berät zu beiden Richtungen und betreibt selbst einen MCP Server für Sulu CMS.

Die meisten Tool Setups scheitern nicht an der Technik, sondern an der Beschreibung. Ein knapper Name und ein vager Satz reichen nicht, das Modell benutzt das Werkzeug dann falsch, und niemand merkt es, weil trotzdem eine plausible Antwort herauskommt. Die Demo macht es richtig vor: Die Beschreibung von movie_search sagt nicht nur, was das Tool tut, sondern auch, wie das Ergebnis weiterverwendet werden soll. Wir gehen deshalb jedes Tool wie eine öffentliche API an.

Der zweite Punkt ist das Blast Radius Denken. Bevor ein schreibendes Tool live geht, klären wir, was im schlimmsten Fall passiert, wenn das Modell es zur falschen Zeit aufruft. Daraus entstehen Freigabe Listener, enge Validierung und getrennte Agents für lesende und schreibende Aufgaben.

Der dritte Punkt ist Tempo. Docker Setup, Proxy davor, Pipeline drumherum und ein Workshop im Team: Damit steht das erste belastbare AI Feature in Tagen statt in Quartalen, und euer Team kann das nächste selbst bauen. Mehr dazu in unserem Bereich Vibe Coding Best Practices und im Vibe Coding Consulting.

Die Fragen, die uns in Beratungsgesprächen zu Tool Calling immer wieder begegnen, kurz und ohne Umwege beantwortet.