Underthesea : un agent Python sans dépendance, avec le vietnamien en héritage
Underthesea - AI Assistant
En bref
- De quoi s’agit-il ?
- La bibliothèque passe d'un outil de traitement du vietnamien à un kit d'agents multi-fournisseurs écrit uniquement avec la bibliothèque standard. Voici ce que le README permet réellement de vérifier, et ce qu'il laisse dans l'ombre.
- À qui s’adresse-t-il ?
- Underthesea convient aux équipes Python qui veulent un agent multi-fournisseurs sans installer les SDK openai, anthropic ou google-genai, et à celles qui traitent du vietnamien dans le même projet. Il ne convient pas si vous dépendez d'un framework à écosystème d'intégrations, ni si vous avez besoin d'une documentation de référence complète sur les outils intégrés : le README les liste sans les documenter un par un.
- Puis-je l’utiliser commercialement ?
- Oui. Apache-2.0 est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 1 jour.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Un outil de NLP vietnamien devenu kit d'agents
Le README situe la bascule à la version 9.3.0 : depuis cette release, Underthesea se présente comme un kit d'IA agentique open source avec des capacités de traitement du vietnamien intégrées. Le paquet conserve donc deux visages. D'un côté des modules Python pour le traitement du vietnamien, dont un segmenteur de mots mentionné dans les topics du dépôt. De l'autre un composant Agent multi-fournisseurs. Le public visé n'est pas celui d'un framework d'agents généraliste. C'est un développeur Python qui travaille sur des textes vietnamiens et qui veut ajouter une couche d'agent sans empiler les SDK propriétaires. La promesse centrale tient en une phrase du README : communiquer avec les API de LLM en n'utilisant que la bibliothèque standard, urllib et json, sans les paquets openai, anthropic ou google-genai.
Ce que signifie concrètement zéro dépendance externe
L'implémentation décrite repose sur urllib et json pour parler aux API distantes. Chaque fournisseur est une classe distincte, OpenAI, AzureOpenAI, Anthropic, Gemini, et le README indique que ce découpage suit le modèle du SDK Anthropic. La classe LLM() joue un rôle différent : elle détecte le fournisseur à partir des variables d'environnement. Cette conception a une conséquence pratique directe. Il n'y a pas de couche d'abstraction partagée fournie par un SDK tiers, donc pas de mise à jour transitive qui casse votre build un matin. En contrepartie, tout ce que le SDK officiel apporte en plus, gestion des retries, types, helpers spécifiques au fournisseur, n'est pas là sauf si le code du projet le réimplémente. Le README ne dit rien sur ce point. C'est un arbitrage classique : moins de dépendances installées, plus de surface maintenue par le projet lui-même.
Outils, sessions longues et traçage automatique
Un agent se construit avec un nom, un fournisseur, une liste d'outils et une instruction. Les outils s'obtiennent en enveloppant une fonction Python dans Tool(), la docstring servant de description. Le README donne l'exemple d'une fonction get_weather annotée avec des types, ce qui suggère que les annotations participent à la génération du schéma. Le projet fournit aussi default_tools, présenté comme 12 outils intégrés : calculatrice, datetime, recherche web, wikipedia, entrées-sorties de fichiers, shell, exécution de Python. Cette liste est un point de vigilance. Exposer un outil shell et un outil d'exécution Python dans un agent connecté à un LLM déplace le problème de sécurité vers votre configuration, et le README ne détaille pas de garde-fous. Pour les traitements longs, la classe Session accepte un progress_file et une méthode create_task avec une liste d'étapes, puis run_until_complete(max_sessions=5). Le README rattache ce mécanisme aux patterns de harnais décrits par Anthropic pour les agents de longue durée. Le traçage, lui, est actif par défaut : chaque appel écrit dans ~/.underthesea/traces/ et se désactive avec UNDERTHESEA_TRACE_DISABLED=1. Un LangfuseTracer existe si le paquet langfuse est installé, et un décorateur @trace permet d'imbriquer des fonctions comme spans enfants.
Installation et mise en service
L'installation tient en une commande : pip install underthesea. Le README annonce la compatibilité avec Python 3.10 à 3.14 via un badge. Pour l'authentification, il faut exporter une variable selon le fournisseur : OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, ou le couple AZURE_OPENAI_API_KEY et AZURE_OPENAI_ENDPOINT. Le premier agent tient en trois lignes, avec Agent(name="assistant", provider=LLM()) puis un appel direct de l'objet. Le streaming passe par agent.stream() et une boucle sur les chunks. Pour exposer un agent sur le réseau, le module underthesea.agent.server fournit serve(), avec port, path et un drapeau ui. L'exemple du README monte un agent MathAgent sur /a2a/math et publie trois points d'entrée : une interface de chat sur /ui, une AgentCard sur /.well-known/agent-card.json, et un endpoint JSON-RPC en SSE. Le serveur est une application ASGI brute, sans dépendance à un framework web dans l'installation de base. L'extra underthesea[agent-server] ajoute uvicorn, starlette et httpx. Pour un routage personnalisé, make_app() renvoie un callable ASGI à passer à uvicorn ou hypercorn.
Les zones que la documentation ne couvre pas
Le README est un document de démonstration, pas une référence. Les 12 outils intégrés sont nommés en une ligne, sans signature ni paramètre ni comportement en cas d'échec. Impossible de savoir depuis ce texte ce que fait exactement l'outil de recherche web, quel fournisseur il interroge, ni comment il gère une réponse vide. Le format des fichiers de trace n'est pas décrit non plus : on sait qu'ils atterrissent dans ~/.underthesea/traces/ avec un horodatage dans le nom, rien de plus. Le mécanisme de reprise après interruption d'une Session n'est pas expliqué au-delà du nom progress_file. Autre point : la version publiée la plus récente listée est underthesea-v9.5.0, datée du 17 mai 2026, alors que le dernier push sur le dépôt est daté du 9 septembre 2026. Le README ne permet pas de savoir ce qui a changé entre les deux. Enfin, la page d'accueil et la documentation en ligne sont liées mais leur contenu n'est pas fourni ici, donc je ne peux pas affirmer qu'elles comblent ces lacunes.
Quand choisir autre chose
Si votre besoin principal est un graphe d'agents avec orchestration complexe, persistance d'état et écosystème d'intégrations, un framework dédié comme LangGraph vise ce terrain avec une abstraction de graphe et un magasin d'état. Underthesea reste sur un modèle plus direct : un objet Agent, des outils, des sessions séquentielles. La différence n'est pas une question de qualité mais de forme. Underthesea vous laisse le contrôle du transport HTTP et ne vous impose aucune dépendance ; un framework vous donne des primitives d'orchestration que vous devriez sinon écrire vous-même. Le choix dépend de ce que vous préférez maintenir. Notez aussi que la partie NLP vietnamienne n'est pas détaillée dans le README fourni, donc si c'est votre motif principal d'adoption, il faudra consulter la documentation du projet plutôt que ce fichier.
Licence et coût de maintenance
Le dépôt est sous Apache-2.0, une licence permissive qui autorise l'usage commercial et la modification, avec une clause de brevets et l'obligation de conserver les mentions de copyright et le fichier de licence. Je ne donne pas de conseil juridique : pour un usage en entreprise, faites relire les obligations de notice par votre service compétent. Sur le coût de maintenance, le point à retenir est structurel. En réimplémentant l'accès aux API de quatre fournisseurs avec urllib, le projet assume la charge de suivre leurs évolutions. Une modification de format côté Anthropic ou Gemini se traduit par une mise à jour d'Underthesea, pas par une mise à jour d'un SDK tiers. Le rythme de publication observé, v9.3.0 et v9.4.0 le 11 avril 2026 puis v9.5.0 le 17 mai 2026, montre une activité soutenue sur cette période, mais je ne peux rien conclure sur la cadence après mai 2026 à partir des éléments fournis.
Conclusion éditoriale
Underthesea convient aux équipes Python qui veulent un agent multi-fournisseurs sans installer les SDK openai, anthropic ou google-genai, et à celles qui traitent du vietnamien dans le même projet. Il ne convient pas si vous dépendez d'un framework à écosystème d'intégrations, ni si vous avez besoin d'une documentation de référence complète sur les outils intégrés : le README les liste sans les documenter un par un. Avant d'adopter, vérifiez le contenu réel des fichiers déposés dans ~/.underthesea/traces/ et le comportement de default_tools sur un cas limite, par exemple une commande shell que vous ne voulez pas voir exécutée.
Notes de la communauté