tnsai · sessionv0.13.0

the java framework for ai agents

Open-source and annotation-driven, on Maven Central. 12 modules, 55 declarative annotations, 31 LLM providers behind one LLMClient SPI, 62 tool kits (210 @Tool methods), six shipped chat channels, 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.13.0

0

modules

one BOM

0

LLM providers

one SPI

0

annotations

declarative

0

@Tool methods

62 kits

0

chat channels

shipped

providers · 31 llms · one spiLLMClient

OllamaOpenAIAnthropicGoogle GeminiGroqMistralCohereOpenRouterAzure OpenAIAWS BedrockHugging FaceZhipu AIMiniMaxCerebrasNVIDIA NIMDeepInfraFireworks AITogether AIxAI GrokIBM watsonxVertex AIReplicateDeepSeekLM StudioPerplexityDatabricks Mosaic AIAlibaba DashScopellama.cppvLLMTencent Hunyuan01.AI Yi

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?");

annotations55 shipped

declare it, don’t wire it

Retries, tracing, retrieval, guardrails and contracts are policy on the method — not plumbing inside it. The dispatcher applies them in a fixed order around your action body, which stays business logic.

ResearchRole.javaJava

@RoleSpec(name = "researcher",
    goals = @Goal(name = "cited",
        condition = "sources.size() > 0"))
public class ResearchRole extends Role {
 
  @ActionSpec(type = ActionType.LOCAL)
  @Retrieval(strategy = Strategy.HYBRID, topK = 8)
  @Resilience(maxAttempts = 3, fallback = "cached")
  @OutputGuardrail(maxChars = 4000, maskPII = true)
  @Traced @Metered(name = "summarize")
  public Summary summarize(String topic) {
    return writer.compose(topic);  // just the logic
  }
}

role & actions

@RoleSpec@ActionSpec@Capability@Goal

tools

@Tool@ToolParam@WebService@Idempotent

knowledge

@KnowledgeSource@Retrieval@Memory

reliability

@Resilience@Fallback@Contract

observability

@Traced@Metered

safety

@Security@InputGuardrail@OutputGuardrail

a selection — the full catalog lists each annotation with its runtime status, so you can tell a wired one from a scaffold before you depend on it.

architecture12 modules

12 modules · one version

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

tnsai-bomone version · v0.13.0

core

llm

intelligence

coordination

quality

evaluation

mcp

tools

channels

payments

integration

server

rewrite

tnsai-bomone version · v0.13.0

corellmintelligencecoordinationqualityevaluationmcptoolschannelspaymentsintegrationserverrewrite

apache-2.0 · maven central · BOM-pinned · JDK 21+. each module ships as io.github.tansuasici:tnsai-*:0.13.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.13.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 — parameter names and types are read straight off the method signature, so there is nothing to annotate per argument.

ResearcherRole.javaJava

public class ResearcherRole extends Role {
 
  @Override public RoleIdentity getIdentity() {
    return new RoleIdentity("researcher",
        "Find academic papers", "research");
  }
 
  @ActionSpec(type = ActionType.LOCAL)
  // param name comes from the signature (-parameters)
  public List<Paper> search(String query) {
    return arxiv.find(query);
  }
}

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 /docs-src/*.md /sitemap.xml