tnsai · sessionv0.12.0

the java framework for ai agents

Open-source and annotation-driven, on Maven Central. 13 modules, 31 LLM providers behind one LLMClient SPI, 62 tool kits (200+ @Tool methods), multi-agent coordination, MCP, and native Anthropic prompt caching.

read the docs source on github

add to your pom.xml

io.github.tansuasici:tnsai-bom:0.12.0

0

modules

one BOM

0

LLM providers

one SPI

0

annotations

declarative

0+

@Tool methods

62 kits

0

tests

JUnit 5

providers · 31 llms · one spiLLMClient

AnthropicOpenAIGoogle GeminiMistralAWS BedrockAzure OpenAICohereGroqOpenRouterOllamaHugging FaceDeepSeekTogether AIFireworks AIPerplexityxAI GrokCerebrasNVIDIA NIMReplicatewatsonxVertex AIvLLM

examples03

three shapes of agent code

Same builder, same lifecycle — conversational, retrieval-augmented, and a multi-agent council.

01agents

conversational agent

A Role declares identity and duties; AgentBuilder wires it to an LLMClient. Streaming, tool routing, and history are built in.

read the docs

ChatAgent.javaJava

// AssistantRole extends Role — identity + duties
Agent agent = AgentBuilder.create()
  .role(new AssistantRole())
  .llm(AnthropicClient.builder()
    .model("claude-sonnet-4").build())
  .build();
 
agent.start();
String reply = agent.chat("Hi!");

02rag

rag over your docs

HybridRAGStrategy fuses BM25 keyword search with vector retrieval. RAGPipeline composes the full retrieve-then-generate flow.

read the docs

DocsAgent.javaJava

// Hybrid = BM25 + vector store
RAGStrategy strategy = new HybridRAGStrategy(
  new BM25Index(corpus), vectorStore);
 
RAGPipeline pipeline = RAGPipeline
  .builder(strategy).build();
 
String answer = pipeline.execute(
  "What is BDI?");

03coordination

multi-agent council

CouncilExecutor runs Karpathy's 3-stage llm-council — parallel deliberation and a skeptical chair, not a role-play pipeline.

read the docs

Council.javaJava

// Karpathy 3-stage llm-council
CouncilExecutor council =
  CouncilExecutor.builder()
    .members(List.of(gpt4, claude, gemini))
    .chairman(gemini)
    .anonymize(true)
    .build();
 
CouncilResult r = council.deliberate(
  "How should we architect auth?");

architecture13 modules

13 modules · one version

Lockstep release. Pull tnsai-bom, depend on what you use — no per-module version juggling.

tnsai-bomone version · v0.12.0

core

llm

intelligence

coordination

quality

evaluation

mcp

tools

channels

payments

integration

server

rewrite

tnsai-bomone version · v0.12.0

corellmintelligencecoordinationqualityevaluationmcptoolschannelspaymentsintegrationserverrewrite

apache-2.0 · maven central · BOM-pinned · JDK 21+. each module ships as io.github.tansuasici:tnsai-*:0.12.0.

quickstart3 steps

three steps

1

add the bom

One Maven import pins every tnsai-* module to the same version. Depend on what you use without naming versions twice.

pom.xmlXML

<dependencyManagement>
  <dependency>
    <groupId>io.github.tansuasici</groupId>
    <artifactId>tnsai-bom</artifactId>
    <version>0.12.0</version>
    <type>pom</type><scope>import</scope>
  </dependency>
</dependencyManagement>

2

define a role

A role extends Role and declares its identity and actions. @ActionSpec methods become tools the agent can call; @Param maps tool arguments to method parameters.

ResearcherRole.javaJava

public class ResearcherRole extends Role {
 
  @Override public RoleIdentity getIdentity() {
    return new RoleIdentity("researcher",
        "Find academic papers", "research");
  }
 
  @ActionSpec(type = ActionType.LOCAL)
  public List<Paper> search(@Param(name="q") String q) {
    return arxiv.find(q);
  }
}

3

build, start, chat

AgentBuilder runs pre-flight validators at build() time — missing role, missing LLM, capability mismatches — so misconfigurations throw before the first message goes out.

Main.javaJava

Agent agent = AgentBuilder.create()
    .role(new ResearcherRole())
    .llm(AnthropicClient.builder()
        .model("claude-sonnet-4")
        .withPromptCaching()      // −75% input cost
        .build())
    .build();                      // throws on misconfig
 
agent.start();
String reply = agent.chat("Find papers on RAG eval.");

need more depth? installation guide · agent concepts · quickstart

resourcestnsai

humansdocs github ↗maven central ↗

machines/llms.txt /llms-full.txt /sitemap.xml