Underthesea - Vietnamese Agentic AI Toolkit
Zero-dependency multi-provider AI agent framework with built-in Vietnamese NLP capabilities.
Evidence shows: Agent default tools include shell and python exec, which are high-privilege, but no least-privilege configuration or user confirmation mechanism is provided; data flow transparency is limited, only mentioning automatic tracing to ~/.underthesea/traces/, but not detailing data flow; sensitive data handling is not specified; dependency security lacks lock files or audits; external effects include network requests and file writes, but user confirmation is not mentioned; rollback mechanism is not mentioned; source attribution is only via author info, unverified. Deductions: lack of permission control, user confirmation, data flow transparency, sensitive data handling, dependency security, external effect control, rollback mechanism.
Evidence shows: README and pyproject.toml descriptions are consistent; Agent module claims zero external dependencies, and pyproject's agent optional dependency is empty, consistent with the claim; dependency availability: core dependencies like requests, PyYAML are common, but no locked versions; failure messages are not documented. Deductions: failure messages not documented, dependency versions not locked.
Evidence shows: README clearly targets developers, provides multiple usage scenarios (quick start, streaming, tool calling, multi-session, tracing, serving); capability boundaries are explained via tool list and architecture diagram; trigger precision: tool calling examples are clear, but trigger conditions are not specified; environment fit: supports Python 3.10+, multiple OS, but specific environment requirements are not detailed. Deductions: trigger precision not detailed.
Evidence shows: Information architecture is clear, README has a table of contents; installation instructions are simple; naming is stable, version number is clear; examples are rich, with quick start and tool calling examples; known limitations are not explicitly listed; license is Apache-2.0; version changelog is not provided; maintenance responsibility is indicated via author and contributing guide. Deductions: known limitations not listed, version changelog missing.
Evidence shows: Output usability: examples show clear output formats; marginal value: multi-provider support and built-in tools provide unique value; cost-benefit: zero external dependencies reduce installation cost, but no performance data. Deductions: no performance or cost data.
Evidence shows: Claims in README (e.g., zero external dependencies) can be partially verified in pyproject.toml; cross-source corroboration is limited, relying only on README and pyproject; fact-inference separation: README distinguishes feature descriptions and examples, but does not explicitly mark inferences. Deductions: insufficient cross-source corroboration, unclear fact-inference separation.
- Default tools include shell and python exec, which are high-privilege; use with caution.
- No user confirmation mechanism; Agent may automatically execute high-privilege operations.
- Data flow transparency is limited; automatic tracing may record sensitive information.
- Dependencies are not version-locked, posing supply chain risks.
- No rollback mechanism; operations may be irreversible.
What does this agent do, and when should you use it?
Underthesea is an open-source Agentic AI toolkit that bundles Vietnamese natural language processing modules. It offers AI agent functionality with no external dependencies, communicating with major LLM providers using only Python's standard library (urllib and json). The toolkit includes an Agent class, multi-session support via Session, and Tool calling. It provides 12 built-in tools like calculator, web search, and file I/O. Agents can be exposed over the A2A protocol with AgentCard and an optional chat UI. Additionally, it includes a full Vietnamese NLP pipeline: word segmentation, POS tagging, NER, sentiment analysis, and more. All agent calls are automatically traced to local files.
This repository implements a Python library for building and running AI agents. It supports configuring multiple providers (OpenAI, Azure OpenAI, Anthropic, Gemini) via environment variables or API keys. The Agent class handles LLM API communication, tool calling, and streaming. The Session class enables long-running agents with context reset and task handoff. Agents can be served over the A2A protocol (JSON-RPC over HTTP+SSE) with an optional web UI. It also provides a suite of Vietnamese NLP functions such as word_tokenize, pos_tag, ner, sentiment, and more, directly usable in Python code.
- Developers needing to integrate multiple LLM providers (OpenAI, Anthropic, etc.) with easy switching.
- Teams building long-running multi-session agents, e.g., research assistants that retain context over time.
- Organizations wanting to expose agents as HTTP services for async requests via the A2A protocol.
- Developers preferring a lightweight agent library with zero external dependencies, using only Python stdlib.
- Researchers and developers working with Vietnamese text, leveraging pre-built NLP functions for segmentation, NER, and sentiment.
What are this agent's strengths and limitations?
- Zero external dependencies, using only Python standard library, reducing install footprint.
- Support for multiple major LLM providers with easy switching.
- Built-in A2A protocol serving for integration with existing systems.
- Integrated Vietnamese NLP capabilities, ideal for Vietnamese-language applications.
- Automatic tracing for debugging and monitoring.
- Only supports the specified providers; does not support others like Cohere.
- A2A server requires additional dependencies (agent-server extra).
- Multi-session requires manual progress file management.
- Advanced features like Langfuse tracing require extra installation.
- Documentation may be sparse; relies on README and NLP.md.
How do you install or deploy this agent?
Install via pip: pip install underthesea. Supports Python 3.10 to 3.14. For server features, install the extra: pip install 'underthesea[agent-server]' (adds uvicorn, starlette, and httpx).
How do you use this agent?
Set environment variables (e.g., OPENAI_API_KEY or ANTHROPIC_API_KEY) or pass API keys directly. Then create an Agent and call it:
from underthesea.agent import Agent, LLM
agent = Agent(name="assistant", provider=LLM())
agent("Hello!")For streaming, use agent.stream(). To enable tools, define functions and wrap with Tool, passing to Agent. For multi-session, create a Session and run tasks.
How does this agent compare with similar options?
Compared to Anthropic's harness patterns it provides similar long-running agent features but focuses on multi-provider support and NLP integration.