Java framework for building AI agents.
TnsAI is a Java framework for writing AI agents. You add it to your own codebase, describe the agent in Java — the tools it may use, the documents it can read, the rules it has to follow — and run it on the JVM you already operate.
dev.tnsai:tnsai-bom:0.16.4
What TnsAI is.
For people who write agents, and the people who use them.
An AI agent is a loop: read a message, reason with a model, call tools, answer. On the JVM, building that loop meant wiring together a dozen libraries — a model client, tool dispatch, retrieval, coordination — and owning the glue forever. Python had cohesive frameworks for this. The JVM did not.
TnsAI is the cohesive platform. One reactor, one version, one BOM. Twelve runtime modules cover models, tools, retrieval, multi-agent coordination, chat channels, payments and serving — one dependency import, no plugin ceremony.
An agent is a Java class.
The annotation is the contract. @KnowledgeSource mounts the documents, @Retrieval runs before the model sees the prompt, and @ActionSpec names what the action must always — and must never — do. The dispatcher enforces it, or it fails loud.
@KnowledgeSource(name = "product-docs", path = "knowledge/products")
public class SupportAgent extends Role {
@Override
public RoleIdentity getIdentity() {
return new RoleIdentity("support", "Answer product questions", "support");
}
@ActionSpec(
type = ActionType.LLM,
description = "Answer a customer question",
mustAlways = {"cite the retrieved source"},
mustNever = {"invent a policy"})
@Retrieval(strategy = Strategy.HYBRID, topK = 5)
public String answer(String question) {
return question;
}
}The query is the action's first String parameter — the runtime binds it, not the method body.
How it works.
01
Declare
02
Dispatch
03
Run
Why teams use it.
Accountability built in
Every agent wires a principal, a liability sink and an authority scope. Who answers for an action is part of the wiring, not a policy document.
Formal multi-agent roots
Coordination follows the BDI architecture, the Gaia methodology and FIPA protocols — topologies, negotiation, voting and trust, not an ad-hoc message bus.
Migrations that run themselves
Breaking changes ship with OpenRewrite recipes. One Maven goal moves your code to the new API — no deprecation graveyard, no shims.
Agents that can pay
x402 micropayments are a module, not a hack. When a paid resource answers HTTP 402, the agent can settle in USDC on Base and carry on.
Twelve runtime modules.
Depend on what you use. The BOM keeps them lockstep. Rewrite and the BOM itself are not in this grid.
Agent lifecycle, roles, action dispatch and the tool registry — the runtime everything else builds on.
One client interface over 31 LLM providers, with streaming, caching, routing and cost tracking.
Planning, reasoning, FSMs, context compaction and the retrieval strategies behind RAG.
Groups of cooperating agents — eight topologies, negotiation, voting and trust.
Guardrails, validation and OpenTelemetry observability for agent runs.
Scoring, LLM judges, benchmarks and release gates for agent quality.
MCP client and server, over stdio and HTTP.
The built-in tool catalog — 63 toolkits, from web and files to fintech.
Chat channel adapters — Telegram, Slack, Discord, WhatsApp, email and CLI.
Micropayments over x402 — an agent settles in USDC when a resource answers HTTP 402.
Cross-module integration tests and the SCOP bridge.
Serve agents over HTTP and WebSocket — the Javalin runtime, with a Docker image.
Start with the quickstart.
The quickstart takes you from a Java project to a running agent.