underthesea v9.5: vietnamesische NLP-Bibliothek mit Agenten-Runtime ohne Fremdabhängigkeiten

Zwei Produkte in einem Paket, und nur eines davon ist neu

Das Repository beschreibt sich selbst als Open-Source Agentic AI Toolkit und verweist im selben Satz auf die Vietnamese Natural Language Processing Module. Die Formulierung since v9.3.0 markiert den Bruch: Vor diesem Release war underthesea ein NLP-Paket, danach kam eine Agent-Schicht hinzu. Die Topics-Liste nennt beides nebeneinander, word-segmenter und vietnamese auf der einen Seite, agentic-ai, agents, llm und hermes-agent auf der anderen. Wer das Projekt zum ersten Mal sieht, sollte diesen Doppelcharakter ernst nehmen. Die Installation heißt weiterhin pip install underthesea und zieht die gesamte Bibliothek, unabhängig davon, welchen Teil man nutzt. Das ist keine Kleinigkeit, denn ein Team, das nur vietnamesische Texte segmentieren will, installiert damit auch die Agent-Runtime, die Tracing-Pfade anlegt und Umgebungsvariablen auswertet.

Der Agent spricht HTTP selbst, statt SDKs zu importieren

Die technisch interessanteste Entscheidung steht in einem Satz der README: Der Agent kommuniziert mit LLM-APIs ausschließlich über die Python-Standardbibliothek, urllib und json, und benötigt weder openai noch anthropic noch google-genai. Das ist ein bewusster Verzicht auf die offiziellen SDKs. Der Vorteil liegt auf der Hand: keine Versionskonflikte zwischen SDK-Abhängigkeiten, kein Nachziehen, wenn ein Anbieter sein Paket umbaut, und ein Installationsprofil, das in Umgebungen mit restriktiven Abhängigkeitsregeln durchgeht. Der Preis ist ebenso klar: Alles, was die SDKs an Komfort mitbringen, Retry-Logik, Streaming-Parser, automatische Header-Verwaltung, muss underthesea selbst abbilden, und die README zeigt nur, dass Streaming grundsätzlich funktioniert, nicht wie Fehlerfälle behandelt werden. Vier Provider-Klassen sind dokumentiert: OpenAI, AzureOpenAI, Anthropic und Gemini. Die Klasse LLM() ohne Argumente liest die passenden Umgebungsvariablen und wählt den Anbieter automatisch. Das Muster der Provider-Klassen folgt laut README explizit dem Anthropic-SDK, wer also Anthropic kennt, findet sich sofort zurecht.

Werkzeuge, Sitzungen und der Handoff zwischen langen Läufen

Der Agent nimmt eine Liste von Tool-Objekten entgegen. Das Beispiel definiert eine Funktion get_weather mit Docstring und übergibt sie als Tool(get_weather); der Docstring dient offenbar als Beschreibung für das Modell, was dem verbreiteten Muster entspricht. Zusätzlich liefert das Paket zwölf eingebaute Werkzeuge: Rechner, Datum und Uhrzeit, Websuche, Wikipedia, Datei-Ein- und -Ausgabe, Shell und Python-Ausführung. Diese Liste ist der Punkt, an dem man innehalten sollte. Shell und python exec bedeuten, dass ein Modell mit den entsprechenden Rechten Befehle auf dem Host ausführen kann. Die README behandelt das nicht als Risiko, sie listet die Werkzeuge nur auf. Für lokale Experimente mag das tragbar sein, in einer mehrstufigen Umgebung ist es eine Entscheidung, die eine eigene Isolationsschicht verlangt, und die liefert das Paket nicht mit. Für längere Läufe gibt es Session mit einer progress_file und create_task, das eine Aufgabe in Teilschritte zerlegt; run_until_complete(max_sessions=5) begrenzt die Zahl der Sitzungen. Die README verweist dazu auf Anthropics Muster für Harnesses bei lang laufenden Agenten. Das Konzept ist also übernommen, nicht neu erfunden, und die Obergrenze max_sessions ist die einzige dokumentierte Abbruchbedingung.

Tracing ist standardmäßig an und schreibt nach ~/.underthesea/traces/

Jeder Agent-Aufruf wird automatisch protokolliert. Der Ablageort ist ~/.underthesea/traces/, das Verhalten lässt sich mit UNDERTHESEA_TRACE_DISABLED=1 abschalten. Die README zeigt eine Beispielausgabe mit Generations- und Tool-Spans, Dauer in Millisekunden und Token-Zählung in der Form 100->18. Wer den Speicherort nicht kennt, wundert sich irgendwann über wachsende Dateien im Home-Verzeichnis, denn die Traces werden nicht rotiert, jedenfalls sagt die README nichts darüber. Neben dem lokalen Tracer existiert LangfuseTracer, der ein separates Paket voraussetzt (pip install langfuse). Zusätzlich gibt es einen @trace-Dekorator, mit dem verschachtelte Funktionen zu Kind-Spans werden und der den Trace-Kontext an darin erzeugte Agents weitergibt. Das ist die sauberste Idee im ganzen Agent-Teil: Der Kontext wird implizit vererbt, statt durch alle Funktionssignaturen gereicht zu werden.

A2A-Server ohne Web-Framework im Basispaket

Seit v9.5.0 lässt sich ein Agent über das A2A-Protokoll bereitstellen. serve(agent, port=8000, path="/a2a/math", ui=True) startet einen Server, der drei Endpunkte bereitstellt: eine mitgelieferte Chat-Oberfläche unter /ui, ein AgentCard-Dokument unter .well-known/agent-card.json und den eigentlichen JSON-RPC-Endpunkt, der per HTTP und Server-Sent Events streamt. Der Server ist laut README eine rohe ASGI-Anwendung ohne Web-Framework-Abhängigkeit im Basispaket. Für Bequemlichkeit gibt es das Extra underthesea[agent-server], das uvicorn, starlette und httpx nachzieht. Wer eigene Routen oder einen anderen ASGI-Server braucht, ruft make_app(agent, path="/a2a/math") auf und bekommt ein ASGI-Callable, das sich unter uvicorn oder hypercorn als module:app betreiben lässt. Das ist eine saubere Trennung, und sie erklärt, warum das Basispaket schlank bleibt. Ungewöhnlich ist der Verweis auf das AP2-Repository von google-agentic-commerce als Protokollreferenz; wer den aktuellen Stand der A2A-Spezifikation braucht, sollte dort nachsehen, nicht in der README.

Was die Dokumentation offen lässt

Die README ist ein Einstiegsdokument, keine Referenz. Sie zeigt für jede Funktion genau ein Beispiel und sagt nichts über Fehlerverhalten. Was passiert, wenn ein API-Schlüssel fehlt, wenn ein Anbieter mit 429 antwortet, wenn ein Tool eine Ausnahme wirft? Dazu findet sich kein Satz. Auch die Frage, wie das Modell ausgewählt wird, bleibt offen: In der Beispielausgabe des Tracers taucht gpt-4.1-mini auf, aber keine Stelle erklärt, wie dieses Modell zustande kommt oder wie man es ändert. Bei AzureOpenAI wird ein deployment-Parameter übergeben, bei den anderen Providern nicht, was nahelegt, dass die Modellwahl dort anders funktioniert, aber die README führt das nicht aus. Wer den Agent produktiv einsetzen will, muss diese Lücken im Quelltext schließen. Für den NLP-Teil gilt dasselbe im Kleinen: Die README verlinkt die vietnamesischen Module nur, sie beschreibt sie nicht.

Wann ein anderes Werkzeug die bessere Wahl ist

Der naheliegende Vergleich ist LangChain. Dessen Ansatz ist umgekehrt: eine breite Abstraktionsschicht über viele Anbieter und Werkzeug-Ökosysteme, mit entsprechend vielen Abhängigkeiten und einer API, die sich zwischen Versionen ändern kann. underthesea wählt den schmalen Weg und zahlt mit fehlender Breite: vier Provider, zwölf Werkzeuge, keine dokumentierte Retry- oder Fallback-Logik. Wer bereits das Anthropic SDK einsetzt, gewinnt durch einen Wechsel nichts, weil die Provider-Klassen diesem Muster ohnehin folgen. Wer dagegen in einer Umgebung arbeitet, in der zusätzliche Abhängigkeiten geprüft und freigegeben werden müssen, ist der Standardbibliothek-Ansatz ein realer Vorteil. Für vietnamesische Textverarbeitung wiederum gibt es im Python-Ökosystem wenig Vergleichbares, und das ist der eigentliche Grund, warum das Paket existiert. Die Kombination aus Segmentierung und Agent-Laufzeit ist allerdings eher zufällig gewachsen als entworfen, und wer nur den NLP-Teil braucht, sollte prüfen, ob eine ältere Version vor v9.3.0 nicht die schlankere Wahl ist.

Lizenz, Wartung und die Kosten des Mitziehens

Das Projekt steht unter Apache-2.0. Diese Lizenz erlaubt kommerzielle Nutzung, verlangt aber, dass Änderungen an den Dateien kenntlich gemacht und die Lizenzhinweise beibehalten werden; wer das Paket weiterverbreitet, muss die NOTICE-Datei mitführen, falls eine existiert. Rechtlich verbindlich ist das nicht, das ist eine Zusammenfassung des üblichen Verständnisses, keine Beratung. Wartungsseitig fällt auf, dass zwischen v9.3.0 und v9.4.0 nur etwa eine Stunde liegt, beide am 11. April 2026, während v9.5.0 rund fünf Wochen später folgte. Zwei Releases am selben Tag deuten auf nachgereichte Korrekturen hin. Solche Sprünge sind kein Qualitätsurteil, sie erschweren aber die Frage, welche Version stabil ist. Für Anwender heißt das konkret: Die Version im Deployment pinnen, statt ungeprüft zu aktualisieren, und vor einem Upgrade die Release Notes lesen, weil die Agent-Schicht sich zwischen v9.3 und v9.5 dreimal geändert hat. Die Abhängigkeitskosten bleiben dabei niedrig, solange man das Extra agent-server und Langfuse nicht installiert.

Redaktionelles Fazit

Wer vietnamesischen Text verarbeitet und dabei ohnehin Python schreibt, bekommt mit underthesea Segmentierung und Agent-Laufzeit aus einer Installation; wer bereits LangChain oder das Anthropic SDK im Einsatz hat, gewinnt durch einen Wechsel nichts, weil die Provider-Klassen bewusst dem Anthropic-Muster folgen und keinen eigenen Abstraktionsgewinn bieten. Vor dem Einsatz ist zu prüfen, ob die installierte Version tatsächlich v9.3.0 oder höher ist, denn das Agent-Modul existiert in älteren Releases nicht, und ob die zwölf default_tools, darunter shell und python exec, im Zielkontext überhaupt tragbar sind. Beide Punkte lassen sich mit einem Aufruf von underthesea.__version__ und einem Blick auf die Tool-Liste klären, bevor Code darauf aufbaut.

Offizielle Quellen

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. undertheseanlp/underthesea on GitHub