TnsAI is an open-source Java 21 framework for building production AI agents. It has 13 runtime modules that share one version through one Maven BOM (dev.tnsai:tnsai-bom:0.18.7), published to https://repo.tnsai.dev/maven2. The license is Apache 2.0.

How do I install TnsAI?

Import the Maven BOM dev.tnsai:tnsai-bom:0.18.7 (group dev.tnsai), then add the modules you need without writing their versions. It needs Java 21 or newer. See https://tnsai.dev/docs/start/install.

Does TnsAI support MCP?

Yes. The tnsai-mcp module can use tools from other Model Context Protocol servers and offer its own, over stdio, SSE or streamable HTTP. Docs: https://tnsai.dev/docs/mcp.

v0.18.7 · Apache 2.0 · Java 21+

Java framework for building AI agents.

Describe the agent in one Java class: what it reads, what it does and the rules it must follow. It runs wherever Java runs.

Get started

You ask

What does the 2023 review say about sleep and memory?

The agent answers

Sleep after learning helps people keep what they learned. Memories replayed in deep sleep are the ones that last.

Source: sleep-review-2023.pdf, p. 12

Also searched the web: 2 newer studies, from 2025.

Switch a stop off to see what that part does.

01 — What it is

An AI agent is a program that takes a question, looks things up, asks a language model and answers. TnsAI lets you build one in plain Java.

0runtime modules

0LLM providers, one interface

0ready-made toolkits

0tools an agent can call

tnsai-core
tnsai-llm
tnsai-intelligence
tnsai-rag
tnsai-coordination
tnsai-quality
tnsai-evaluation
tnsai-mcp
tnsai-tools
tnsai-channels
tnsai-payments
tnsai-integration
tnsai-server

Apache 2.0v0.18.7Every module ships on the same version number.

02 — Anatomy

An agent is a Java class.

This one answers questions from a folder of papers. @Knowledge says where the papers are. @ActionSpec says what the agent does and the rules it must follow. TnsAI enforces those rules; if it cannot, it stops with an error instead of answering. Watch one question go through it; afterwards, hover any part of the class to see what it does.

ResearchAssistant.java

@RoleSpec(knowledge = @Knowledge(        name = "papers",        path = "library/papers"))public class ResearchAssistant extends Role {     @Override    public RoleIdentity getIdentity() {        return new RoleIdentity("research-assistant", "Answer from the papers", "research");    }     @ActionSpec(            type = ActionType.LLM,            description = "Answer a question about the papers",            mustAlways = {"cite the paper the answer comes from"},            mustNever = {"cite a paper that is not in the library"},            knowledge = @Knowledge(name = "papers"))    public String ask(String question) {        return question;    }}

The question arrives as the method's String parameter. TnsAI runs the search, the model and the rule checks around it. The run shown is illustrative.

03 — What it takes over

What you stop writing by hand.

pom.xmlby hand

<version>2.3.1</version>
<version>0.9.4</version>
<version>1.12.0</version>

<artifactId>tnsai-bom</artifactId>

3 lines → one line

Versions

One BOM sets the version of every module.

Without TnsAI: A model client, a search library and tool code from separate projects, kept in step by hand.

Assistant.javaby hand

prompt += "Always cite a source.";
// hope the model listens

mustAlways = {"cite the paper the answer comes from"}

2 lines → one line

Rules

The rule sits on the action, and TnsAI checks every answer against it.

Without TnsAI: A rule like "always cite a source" sits in a prompt you hope the model follows.

Assistant.javaby hand

var hits = index.search(question, 5);
prompt = context(hits) + question;

knowledge = @Knowledge(name = "papers")

2 lines → one line

TnsAI searches your documents before it calls the model.

Without TnsAI: You write the document search yourself, before every model call.

Channels.javaby hand

new SlackBot(token, handler);
new TelegramBot(token, handler);
new DiscordBot(token, handler);

WebSlackTelegramDiscordWhatsAppEmailTerminal

3 lines → one agent

Channels

The same agent answers wherever people write to it.

Without TnsAI: Every place people talk to the agent is one more integration to build.

04 — Why TnsAI

Why teams pick it.

research-assistant · ask()example

›How does short sleep affect memory?

Short sleep weakens how well new memories hold, most of all in the first night.

papers/sleep-review-2023.pdf · p. 12

mustAlways cite the paper

Trace

Answers you can trace

@Knowledge points an agent at your own papers, notes or data. An action can be told to cite what it used, and TnsAI holds it to that on every answer.

eval · llm-judgeexample

prompt v10 / 100

prompt v20 / 100

40 runs · same questionsv2 +23

Measure

Measured, not guessed

The evaluation module scores runs with LLM judges and benchmarks, so you compare models and prompts with numbers instead of impressions.

team · contract-netexample

Teams

Built on agent research

Agent teams follow the Gaia methodology and the FIPA protocols: team shapes, negotiation, voting and trust, instead of an improvised message bus.

research-assistant · recordexample

09:41:02ask()acts for ana · may read papers
09:41:03knowledgeread sleep-review-2023.pdf
09:41:05rulecite the paper · held

Record

A record of who did what

Agents built with AgentBuilder know who they act for and what they may do, and can keep a record of each action. Useful when you must show how a result was reached.

05 — Modules

Thirteen runtime modules.

Add only the modules you need. They share one version number, so they always fit together.

Run an agent and reach a model

pom.xml
<artifactId>tnsai-core</artifactId>
core
The agent runtime
Roles, actions and tools: the part every other module builds on.
pom.xml
<artifactId>tnsai-llm</artifactId>
llm
Language models
One interface to 31 LLM providers, with streaming, caching and cost tracking.
pom.xml
<artifactId>tnsai-mcp</artifactId>
mcp
Model Context Protocol
Use MCP tools from other servers, or offer your own, over stdio and HTTP.
pom.xml
<artifactId>tnsai-server</artifactId>
server
Web server
Serves agents over HTTP and WebSocket. A Docker image is included.

Read, plan and call tools

pom.xml
<artifactId>tnsai-rag</artifactId>
rag
Search over documents
Finds the right passages in your files with vector, keyword, graph and time-aware search. Reads PDF, Word, Markdown and more.
pom.xml
<artifactId>tnsai-intelligence</artifactId>
intelligence
Planning
Breaks a task into steps, reasons over them and keeps long conversations short enough for the model.
pom.xml
<artifactId>tnsai-tools</artifactId>
tools
Built-in tools
A ready tool catalog: 63 toolkits, from web search and files to finance.

Work together, stay safe, get scored

pom.xml
<artifactId>tnsai-coordination</artifactId>
coordination
Agent teams
Several agents working together, with eight team shapes, negotiation, voting and trust.
pom.xml
<artifactId>tnsai-quality</artifactId>
quality
Safety and tracing
Checks on what goes in and comes out, validation, and tracing with OpenTelemetry.
pom.xml
<artifactId>tnsai-evaluation</artifactId>
evaluation
Scoring and benchmarks
Scores answers with LLM judges and benchmarks, and can stop a release that scores too low.

Reach people, payments and other systems

pom.xml
<artifactId>tnsai-channels</artifactId>
channels
Chat apps
Talk to the agent on Telegram, Slack, Discord, WhatsApp, email or in a terminal.
pom.xml
<artifactId>tnsai-payments</artifactId>
payments
Payments
Lets an agent pay for a paid web resource in USDC, using the x402 standard.
pom.xml
<artifactId>tnsai-integration</artifactId>
integration
Integration tests
Tests that run the modules together, and the bridge to SCOP.

06 — FAQ

Questions people ask.

07 — Quickstart

From a Java project to a running agent.

Four steps, the same four the quickstart walks through.

Open the quickstart

Step 1

Add the repository and the BOM

TnsAI is published to its own Maven repository. Import the BOM once and every TnsAI module you add takes the same version.

pom.xml

<repositories>
  <repository>
    <id>tnsai</id>
    <url>https://repo.tnsai.dev/maven2</url>
  </repository>
</repositories>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>dev.tnsai</groupId>
      <artifactId>tnsai-bom</artifactId>
      <version>0.18.7</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Step 2

Write a role

A role says who the agent is and what it can do. Each @ActionSpec method is one thing it can do; this one runs locally, without a model.

AssistantRole.java

public final class AssistantRole extends Role {
    @Override
    public RoleIdentity getIdentity() {
        return new RoleIdentity("assistant", "Friendly conversational agent", "support");
    }

    @ActionSpec(type = ActionType.LOCAL, description = "Greet the user by name")
    public String greet(String name) {
        return "Hello, " + name + "!";
    }
}

Step 3
Build the agent
AgentBuilder puts the role together with a model client, the principal the agent acts for and what it may do. Here it may do anything for an hour.
Main.java
Agent agent = AgentBuilder.create() .llm(new AnthropicClient(model)) .role(role) .principal(principal) .authorityScope(AuthorityScope.unrestricted(Duration.ofHours(1))) .build();
Step 4
Run it
Start the agent and send it a message. The answer comes back as a String.
Main.java
agent.start(); String response = agent.chat("Hi, my name is Alice");