FAQ
Which modules do I need for a simple agent?
tnsai-core plus tnsai-llm. Core gives you the agent runtime (roles, actions, capabilities, tool dispatch); LLM gives you the provider clients (Anthropic, OpenAI, Gemini, Ollama, and the others — see the LLM provider matrix, or tnsai-llm README on GitHub). Everything else (channels, MCP, intelligence, coordination, quality, evaluation) is opt-in once you actually need the capability.
→ Module Overview for the full map.
Can I use TnsAI without annotations?
Yes. AgentBuilder accepts every part of the agent configuration programmatically — roles, tools, LLM clients, capabilities — so you can wire things up entirely from code if your project doesn't want annotation-driven discovery. Annotations are idiomatic and shorter, but they're not load-bearing for the runtime.
→ Reference → Annotations for the full reference.
Does TnsAI require Java 21?
Yes. The framework leans on virtual threads, records, sealed types, and switch-on-sealed pattern matching that all landed in Java 21 LTS. The toolchain (Maven compiler plugin, surefire) is pinned to release 21 — there's no LTS-bridging build profile, and one isn't planned.
Is TnsAI production-ready?
The framework is pre-1.0, which means the public API can shift between minor versions and there are no long-lived @Deprecated shims. We use it in production internally (see the Sona project, which is fully dogfooded on the framework), and the test coverage gate is 80% per module. But if your project can't absorb the occasional 30-minute upgrade when a minor version lands, hold off until 1.0.
In practice: read the changelog before bumping versions, and lean on the migration roadmap for releases that ship breaking changes.
How does TnsAI compare to LangChain / LlamaIndex / Spring AI / etc.?
Different shape. TnsAI is Java 21, single-tenant-by-default, lockstep-versioned, and built around explicit roles + capabilities rather than chained DSL pipelines. The closest neighbour in spirit is Spring AI; the closest in feature set is LangChain's Java port. If you want a side-by-side comparison, the Sona page on tnsai.dev has a table that's kept current with each release.
More questions?
If a question keeps coming up that isn't covered here, open a discussion and we'll add it. For bug reports use the issue tracker; for "how do I..." questions discussions are the right home.
Troubleshooting
A short, opinionated checklist for the failure modes that come up most often when picking up the framework. If your symptom isn't here, open a discussion — the next pass updates this page.
Migration
TnsAI is pre-1.0, so the public API can shift between minor versions. The framework deliberately does not ship long-lived @Deprecated shims — when a replacement lands, the old surface goes in the same release. That means every upgrade is potentially a small surgical step rather than a sprawling deprecation cleanup, but it also means you have to read the right release notes to know what to change.