Ein Symfony AI Agent darf bei Johannes Wachter Notizen schreiben, und trotzdem kann er kaum etwas kaputt machen. Johannes ist Core Developer bei Sulu, Mitglied im Symfony AI Core Team und ein guter Freund von Never Code Alone. Für den Symfony AI Hackathon baut er gerade ein kleines zweites Gehirn namens Synapse und erklärt jeden Schritt auf seinem Blog. Im ersten Teil seiner Serie geht es um einen Agent, der Text bekommt und selbst entscheidet, wo er hingehört. Wir fassen seine Kernideen zusammen und sagen, was Teams davon mitnehmen können.
Symfony AI im Team lernen
Agents mit klaren Grenzen bauen, das üben wir mit eurem Team direkt am eigenen Code und gemeinsam an der NCA Funktastatur:
- Tool Calling: PHP Klassen als Werkzeuge für den Agent
- Guardrails: Regeln im Code, die auch ohne Modell testbar sind
- Für Teams: remote oder inhouse, aktuelle Termine auf Anfrage
Was der Notiz Agent genau macht
Das Ziel klingt klein. Ihr gebt einem Konsolenbefehl ein Stück Text, und am Ende liegt eine Markdown Datei im richtigen Ordner. Ein grober Gedanke landet in inbox/. Klares Wissen, zum Beispiel eine Entscheidung, wird zur strukturierten Notiz in brain/.
Eine Datenbank braucht das Projekt nicht. Das Gehirn ist ein Ordner voller Markdown Dateien im Open Knowledge Format, jede mit einem kleinen YAML Kopf. Die Inbox ist dabei eine bewusste Designentscheidung. Ein Modell, das unsicher ist, bekommt einen Platz für Material, das noch nicht als Wissen gilt.
Johannes sagt selbst, dass Synapse kein Produkt ist, das er nutzen würde. Es ist ein kompaktes Beispiel dafür, wie Agents, Tools, das AI Bundle und das MCP SDK zusammenspielen. Der Hackathon dazu soll laut Johannes vor dem 1.0 Release zeigen, was im echten Einsatz noch bricht. Mehr dazu steht in seinem Beitrag zu Beta und Hackathon.
Wie ihr einem KI Agent sicher Schreibrechte gebt
Das ist für uns der wichtigste Teil des Artikels. Der Agent bekommt keine Funktion, mit der er frei auf Pfade zugreift. Alles, was eine Datei berührt, läuft durch eine einzige Klasse namens Vault. Sie kennt genau ein Wurzelverzeichnis und genau eine Regel für gültige Pfade.
Die Sicherheit steckt damit in mehreren Schichten. Nur die erste hängt vom Urteil des Modells ab.
| Schicht | Was sie tut | Hängt vom Modell ab |
|---|---|---|
Prompt und list_notes | Agent prüft vor dem Schreiben, ob es das Thema schon gibt | Ja |
| Pfadregel im Vault | Erlaubt nur .md Dateien in brain/ und inbox/, prüft auch Symlinks | Nein |
| Exklusives Anlegen | Bestehende Notizen lassen sich nicht überschreiben | Nein |
| Format Validator | Weist Notizen ab, die den Regeln nicht entsprechen | Nein |
| Git und Status draft | Jede Änderung ist ein Diff, freigeben kann nur ein Mensch | Nein |
Genau dieses Denken fehlt uns bei vielen Agent Setups. Was rund um das Modell passiert, entscheidet oft mehr als das Modell selbst. Das haben wir auch in unserem Beitrag zum Agent Harness beschrieben.
Wie Tools in Symfony AI aussehen
Ein Tool ist eine normale PHP Klasse mit dem Attribut #[AsTool]. Name und Beschreibung liest das Modell. Die Konstruktor Parameter kommen per Autowiring. Aus den @param Zeilen im Docblock werden die Beschreibungen der Argumente. Wie das im Detail läuft, zeigt unser Glossar Eintrag zu Tool Calling in Symfony AI.
Der Notiz Agent kommt mit fünf Tools aus:
- list_notes zeigt, welche Notizen es schon gibt
- read_note liest eine einzelne Notiz
- save_to_inbox legt rohes Material ab
- describe_format erklärt dem Modell, wie eine gute Notiz aussieht
- save_to_brain schreibt fertiges Wissen und erzeugt den YAML Kopf selbst
Das letzte Detail ist klug. Das Modell muss nie von Hand gültiges YAML produzieren, also kann es dort auch keinen Fehler machen.
Warum der Agent Fehler als Text zurückbekommt
Wirft ein Tool eine Exception, fängt die Toolbox von Symfony AI sie ab und macht weiter. Das Modell erfährt dann aber nur, dass etwas schiefging, und den Grund nicht. Darum geben die Tools bei Johannes den Fehler als Text zurück:
try {
return 'Gespeichert: '.$this->brain->saveToInbox($slug, $text);
} catch (\InvalidArgumentException $e) {
return 'Fehler: '.$e->getMessage();
}Die Meldungen sind für das Modell geschrieben. Sie sagen, wie ein gültiger Pfad aussieht oder welcher Abschnitt in einer Notiz fehlt. Meist reicht das, damit sich der Agent beim nächsten Aufruf selbst korrigiert. Laut Johannes gibt es auf dem Entwicklungszweig von Symfony AI inzwischen eine ToolErrorException, mit der ein späteres Release das sauberer lösen kann.
Auch die Formatregeln liegen an genau einem Ort, in einer YAML Datei. Der Validator liest sie zum Prüfen, das Tool describe_format liest sie zum Erklären. So können Prompt und Code nicht auseinanderlaufen. Dieses Muster würden wir in jedem Agent Projekt übernehmen.
Symfony AI Agent einrichten und der Stolperstein bei der Beta
Johannes arbeitet mit PHP 8.4, Symfony 8.1, Symfony AI 1.0.0-BETA1 und einem Cohere API Key. Der Agent selbst ist nur Konfiguration in YAML plus eine Prompt Datei, dazu kommt ein kleiner Konsolenbefehl als Oberfläche. Die Liste der erlaubten Tools steht direkt in der Konfiguration, genau wie eine Obergrenze für Tool Aufrufe.
Gestolpert ist Johannes über die Composer Einstellung. Solange das AI Bundle eine Beta ist, lässt es sich mit dem Standard stable nicht installieren, und der Hinweis steht weit hinten in der Fehlermeldung. Diese Zeile löst das Problem:
composer config minimum-stability betaDen kompletten Code findet ihr im Branch 01-write-agent von wachterjohannes/synapse-tutorial. Jeder weitere Teil der Serie bekommt dort einen eigenen Branch.
Was der Test mit dem echten Modell zeigt
Johannes hat drei Eingaben gegen das echte Modell laufen lassen. Eine vage Idee landete in der Inbox. Eine klare Entscheidung wurde zur Notiz vom Typ Decision, mit Status draft und einem neuen Eintrag im Log. Dieselbe Entscheidung ein zweites Mal führte zu keiner neuen Datei, weil der Agent die erste Notiz vorher gefunden hatte.
Johannes verlässt sich auf dieses Urteil nicht allein. Der Vault würde das Überschreiben auch dann ablehnen, wenn das Modell es versucht. Und diese Regeln lassen sich ganz ohne Modell prüfen. Ein kleines Skript schickt ungültige Pfade an den Vault und meldet, ob alle abgewiesen werden.
Für uns ist das der stärkste Punkt. Tests, die ohne API Key laufen, passen in jede Pipeline. Sie kosten keine Tokens und sie geben bei jedem Lauf dasselbe Ergebnis.
Wo der Agent an seine Grenzen kommt
Johannes benennt die Schwächen offen. Der Agent kann Notizen auflisten und lesen, aber nicht nach Bedeutung suchen. Eine doppelte Notiz mit anderer Formulierung rutscht also durch. Genau dort setzt später Retrieval an, das er in seiner RAG Serie erklärt.
Der zweite Punkt betrifft die Sicherheit. Wer dem Agent Text schicken darf, kann damit auch sein Verhalten beeinflussen.
„captured text is also input“
Johannes Wachter, An agent that files your notes
Auf Deutsch: Auch der erfasste Text ist eine Eingabe an das Modell. Das Tutorial geht darauf bewusst nicht tiefer ein. In einem echten Projekt gehört diese Frage ganz nach vorne, vor allem wenn Mails oder Webseiten in den Agent laufen.
Was wir Teams daraus mitgeben
Das Muster geht weit über Notizen hinaus. Es passt auf jeden Agent, der Tickets anlegt, Inhalte in ein CMS schreibt oder Daten ändert. Unsere Checkliste dazu:
- Kleine Schreibfläche: Der Agent bekommt fachliche Tools und keinen allgemeinen Zugriff.
- Harte Regeln im Code: Was nie passieren darf, prüft PHP und kein Prompt.
- Hilfreiche Fehler: Meldungen sagen dem Modell, was es besser machen soll.
- Tests ohne Modell: Die Regeln laufen in der Pipeline, gern mit Rector und statischer Analyse daneben.
- Menschliche Freigabe: KI Ergebnisse bleiben Entwürfe, bis jemand sie prüft.
Das Modell ist dabei die austauschbare Stelle. Cohere passt für das Tutorial, weil ein kostenloser Test Key reicht. Für euer Projekt prüft ihr selbst, welcher Anbieter zu euren Daten passt. Unser Eintrag zu Model Inference in Symfony AI erklärt die gemeinsame API, und Ollama lokal in Symfony anbinden zeigt den Weg zu einem lokalen Modell. Ob das bei Tool Calls mithält, seht ihr, wenn ihr dieselben Eingaben noch einmal laufen lasst.
Den ganzen Artikel mit allem Code lest ihr im Original auf johanneswachter.dev. Die Fortsetzungen sammelt Johannes auf seiner Synapse Übersicht.
Mehr zu Symfony AI und Agents
Einen Überblick über alle Bausteine gibt unser Glossar für Symfony AI. Wie Johannes zu Symfony AI kam, erzählen wir in Symfony Mate, wie die Idee im Zug entstand. Wenn ihr Agents statt Notizen mit einer laufenden App verbinden wollt, helfen Symfony AI Mate und das Symfony MCP Bundle. Was das neue Framework Release bringt, steht in Symfony 8.2 neue Features erklärt. Johannes arbeitet außerdem im Core Team von Sulu, das erklärt unser Glossar für Sulu CMS. Hängt euer Projekt noch auf einem alten Stand, ist ein PHP Update der erste Schritt.
Agents mit Guardrails für euer Team
Ein Agent mit Schreibrechten braucht Grenzen, die im Code stehen. Wir erarbeiten mit eurem Team Tools, Regeln und Tests im eigenen Symfony oder Sulu Projekt. Direkt an eurem Code, gemeinsam an der Funktastatur.
Remote oder inhouse, aktuelle Termine auf Anfrage. Das Vorgespräch ist kostenlos.
Häufige Fragen zum Symfony AI Agent
Was ist ein Symfony AI Agent 2026?
Ein Symfony AI Agent verbindet ein Sprachmodell mit einem Prompt und mit Tools, also PHP Klassen, die das Modell aufrufen kann. Ihr konfiguriert ihn über das AI Bundle in YAML und injiziert ihn wie einen normalen Service. Das Modell entscheidet, welches Tool es wann nutzt.
Was ist Synapse von Johannes Wachter 2026?
Synapse ist ein kleines zweites Gehirn, das Johannes Wachter als Tutorial für den Symfony AI Hackathon baut. Der erste Teil sortiert Text per Agent in Markdown Notizen ein. Spätere Teile ergänzen Suche, einen MCP Server und Berechtigungen. Als fertiges Produkt ist es nicht gedacht.
Wie begrenze ich die Schreibrechte eines KI Agenten 2026?
Gebt dem Agent fachliche Tools und keinen freien Dateizugriff. Prüft Pfade, Formate und Überschreiben im PHP Code an einer zentralen Stelle. Haltet Änderungen in Git nachvollziehbar und lasst Ergebnisse von Menschen freigeben. So bleibt ein Fehler des Modells begrenzt und schnell rückgängig zu machen.
Warum lässt sich Symfony AI 2026 nicht installieren?
Häufig liegt es an der Composer Einstellung. In der Beta Phase passt das AI Bundle nicht zum Standardwert stable bei minimum-stability. Setzt den Wert im Projekt auf beta. Beachtet auch, dass symfony/ai-agent ein eigenes Paket ist und zusätzlich installiert werden muss.
Muss ich für Symfony AI Agents 2026 Cohere nutzen?
Nein. Johannes nutzt Cohere im Tutorial, Symfony AI bindet aber viele Anbieter über eine gemeinsame Plattform Schicht an, darunter auch lokale Modelle über Ollama. Prüft bei einem Wechsel, ob das gewählte Modell Tool Calls zuverlässig beherrscht und zu euren Daten passt.
Wo finde ich den Code zum Notiz Agent?
Der Code liegt im GitHub Repository wachterjohannes/synapse-tutorial im Branch 01-write-agent. Jeder weitere Teil der Serie hat einen eigenen Branch. Die ausführliche Erklärung schreibt Johannes Wachter auf seinem Blog johanneswachter.dev.
