# TnsAI Framework > Java framework for building production-grade AI agents. > Multi-module monorepo (12 modules: core, llm, intelligence, > coordination, quality, evaluation, mcp, tools, channels, > integration, server, bom). Annotation-driven, SPI-extensible, > Maven Central published as `io.github.tansuasici:tnsai-bom`. Version: 0.12.0 — see /docs/help/changelog ## Overview - [TnsAI Framework](https://tnsai.dev/docs) - [Agents](https://tnsai.dev/docs/agents): Everything about building a single agent — from the first Agent instance to advanced cognitive composition. - [Capabilities](https://tnsai.dev/docs/capabilities): Pluggable building blocks that give an agent power beyond raw LLM calls. - [Channels](https://tnsai.dev/docs/channels): The Channels module (TnsAI.Channels) is a multi-channel messaging gateway that connects TnsAI agents to external messaging platforms. It uses an adapter pattern with SPI discovery so new platforms can be added without modifying the core routing logic. - [Evaluation](https://tnsai.dev/docs/evaluation): The Evaluation module provides a three-layer system for measuring agent quality: evaluators that score responses, a benchmark engine that runs test datasets, and reporting tools for quality gates, trend analysis, and regression detection. - [Help](https://tnsai.dev/docs/help): Support content: fix problems, look up answers, upgrade between versions. - [Integrate](https://tnsai.dev/docs/integrate): Bridges between TnsAI and other protocols or frameworks. - [MCP](https://tnsai.dev/docs/mcp): Model Context Protocol — client, server, transports, registry. - [Multi-Agent](https://tnsai.dev/docs/multi-agent): Build systems of cooperating agents. - [Observability](https://tnsai.dev/docs/observability) - [Reference](https://tnsai.dev/docs/reference): Lookup material. You know what you want — find it fast. - [Sampling](https://tnsai.dev/docs/sampling): Production agents emit thousands of events per second — chat chunks, tool calls, memory writes, hook invocations. Sending all of them to a log aggregator buys a bigger Elasticsearch cluster every quarter; dropping everything to ERROR-only makes debugging impossible. The sampling SPI in tnsai-quality.sampling lets operators decide per-event whether to capture, drop, or down-sample, with policy choices that scale from "dev — capture everything" to "production — errors always, INFO 1%". - [Security](https://tnsai.dev/docs/security): Control what agents can do, encrypt sensitive data, and defend against prompt injection. - [Server](https://tnsai.dev/docs/server): Run TnsAI as a backend — WebSocket API, session management, human-in-the-loop tool approval. - [Sona](https://tnsai.dev/docs/sona): Sona is the personal AI assistant the TnsAI maintainers run for themselves. It is the first concrete consumer of the framework — every TnsAI module that can't carry Sona's workload is a feature we haven't finished. - [Start Here](https://tnsai.dev/docs/start): New to TnsAI? This section gets you from zero to a running agent in under 10 minutes. - [Tutorials](https://tnsai.dev/docs/tutorials): End-to-end walkthroughs. Each tutorial takes a real scenario and builds a working agent from scratch. - [Validation and Invariants](https://tnsai.dev/docs/validation): The Quality module provides multi-agent parallel validation (ParallelValidationExecutor), runtime invariant checking (InvariantChecker), conditional rule evaluation (RuleEngine), and input validation (ValidationService). ## Start - [Architecture Overview](https://tnsai.dev/docs/start/architecture-overview) - [Installation](https://tnsai.dev/docs/start/installation): Add TnsAI to your project. The recommended path is via the BOM — one version number covers every module. - [Module Overview](https://tnsai.dev/docs/start/module-overview) - [Quickstart](https://tnsai.dev/docs/start/quickstart): Build your first TnsAI agent in 5 minutes. Prerequisites: Installation. ## Agents - [Advanced Agent Features](https://tnsai.dev/docs/agents/advanced): Beyond the basic Agent lifecycle (create, chat, stop), TnsAI.Core provides specialized subsystems for cognitive support, streaming, ensemble execution, hierarchy management, and chat orchestration. These are internal components extracted from the Agent class for cohesion; most are accessed through the Agent public API rather than directly. - [Behavior](https://tnsai.dev/docs/agents/behavior): How your agent talks, streams, and remembers. - [Memory](https://tnsai.dev/docs/agents/behavior/memory): TnsAI.Core provides a pluggable memory system for agent conversation history. The MemoryStore interface defines storage, retrieval, pruning, and search operations. Four implementations cover different persistence and sharing requirements. The AgentBuilder.memoryStore() method wires a store into an agent. - [Output Parsing & Serialization](https://tnsai.dev/docs/agents/behavior/output-parsing): TnsAI provides type-safe output parsing for converting raw LLM responses into structured Java objects, and a multi-format serialization system for producing structured output. - [Prompt Strategies](https://tnsai.dev/docs/agents/behavior/prompt-strategies): TnsAI includes a prompt enhancement system that applies proven prompting techniques to improve LLM response quality. The system is built around the PromptStrategy enum, PromptEnhancer builder, and EnhancedPrompt output. - [Streaming](https://tnsai.dev/docs/agents/behavior/streaming): TnsAI supports three streaming modes for real-time token delivery from LLM providers. - [Agent Variants](https://tnsai.dev/docs/agents/behavior/variants): Agent variants let you trade off between response quality, execution speed, and token cost. A single agent can switch variants at runtime -- per task or per action. - [Fundamentals](https://tnsai.dev/docs/agents/fundamentals): The core moving parts of a single agent. This page covers the Agent class itself — construction, chat, memory, lifecycle. See the other pages in this section for Roles, the Action System, Capabilities, and Events. - [Action System](https://tnsai.dev/docs/agents/fundamentals/action-system): The action system is the execution backbone of TnsAI. When an LLM decides to call a function, or an agent needs to perform work, the request flows through ActionExecutor, which routes it to the appropriate executor based on the action's ActionType. - [Capabilities](https://tnsai.dev/docs/agents/fundamentals/capabilities): Capabilities are reusable, body-less action contracts. A @Capability interface carries one or more @ActionSpec-annotated methods that describe what the capability does; the framework dispatches the call at runtime. A role gains the capability by implements-ing the interface — without writing any method bodies. - [Event System](https://tnsai.dev/docs/agents/fundamentals/events): The event system provides full observability into the agent lifecycle. Events use a sealed interface hierarchy with 20+ event types, enabling type-safe pattern matching. - [Roles](https://tnsai.dev/docs/agents/fundamentals/roles): A Role defines what an agent can do. Each role has an identity (name, goal, domain), a set of responsibilities, and discoverable actions. Roles generate the system prompt that instructs the LLM. Actions are methods annotated with @ActionSpec — they are discovered at runtime via reflection and routed to one of four executor types. - [Reliability](https://tnsai.dev/docs/agents/reliability): Making agents survive the real world. - [Error Handling](https://tnsai.dev/docs/agents/reliability/error-handling): TnsAI.Core provides a structured exception hierarchy rooted in TnsAIException. Every exception carries an error code, retryability flag, and suggested retry parameters, enabling automated recovery decisions across the framework. - [Long-Running Runs](https://tnsai.dev/docs/agents/reliability/long-running-runs): Multi-hour and multi-day agent executions need a categorically different runtime than minute-scale interactive sessions. Process crashes, runtime upgrades, transient API failures, and operator-initiated pauses all happen — the framework's reliability layer makes them survivable rather than catastrophic. - [Resilience](https://tnsai.dev/docs/agents/reliability/resilience): TnsAI.Core provides a declarative resilience framework built on top of Resilience4j. The @Resilience annotation configures retry, circuit breaker, rate limiting, bulkhead isolation, timeout, and fallback policies for actions and roles. The ResilienceExecutor applies these policies in a layered pipeline and tracks terminal failures in a dead-letter queue. - [Schema, Identity, and Enums](https://tnsai.dev/docs/agents/reliability/schema-identity): TnsAI.Core provides typed schemas for LLM tool definitions, agent identity and communication style modeling, decentralized identifiers (DIDs), and a set of enums that control agent behavior. ## Capabilities - [Intelligence](https://tnsai.dev/docs/capabilities/intelligence): Give agents planning, reasoning, state machines, and learning capabilities. - [Advanced Intelligence Patterns](https://tnsai.dev/docs/capabilities/intelligence/advanced): Advanced cognitive capabilities in TnsAI.Intelligence for reasoning, memory consolidation, output validation, and iterative refinement. - [Context Management](https://tnsai.dev/docs/capabilities/intelligence/context): Context window management, decision tracing, session history, knowledge extraction, automatic memory consolidation, and auto-summarization. These components help agents operate effectively within token limits and learn from past interactions. - [Finite State Machine](https://tnsai.dev/docs/capabilities/intelligence/fsm): Deterministic state machine for bounded agent autonomy. Provides guard-based transitions, entry/exit actions, automatic transitions, event payloads, listeners, and visualization to Mermaid and Graphviz DOT. - [Learning and Refinement](https://tnsai.dev/docs/capabilities/intelligence/learning): Feedback-driven learning, normative constraint enforcement, iterative refinement loops, prompt optimization, and structured output validation. These components enable agents to improve over time and produce higher-quality outputs. - [Planning](https://tnsai.dev/docs/capabilities/intelligence/planning): Goal-oriented planning for AI agents. TnsAI provides three planner implementations: annotation-driven backward chaining, utility-based scoring, and LLM-powered dynamic planning with human-in-the-loop approval and adaptive replanning. - [Reasoning](https://tnsai.dev/docs/capabilities/intelligence/reasoning): Advanced reasoning strategies for complex problem solving. TnsAI provides multiple reasoning executors based on recent AI research, from simple chain-of-thought to graph-based reasoning with merging and refinement. - [LLM](https://tnsai.dev/docs/capabilities/llm): Configure providers, route between models, cache responses, and track cost. - [Advanced LLM Patterns](https://tnsai.dev/docs/capabilities/llm/advanced): Advanced capabilities in TnsAI.LLM for observability, structured output, resilience, caching, intelligent routing, and cost management. - [Audio & Speech](https://tnsai.dev/docs/capabilities/llm/audio): The WhisperClient provides speech-to-text capabilities powered by OpenAI's Whisper model. It supports transcription in multiple languages and translation of non-English audio to English. - [LLM Caching](https://tnsai.dev/docs/capabilities/llm/caching): Reduce latency and cost with semantic response caching. The cache uses similarity matching so that near-identical prompts return cached responses without hitting the API. - [Cost Tracking](https://tnsai.dev/docs/capabilities/llm/cost-tracking): Monitor and control LLM spending across providers with built-in cost tracking, budget management, and model pricing data for 100+ models. - [LLM Observability](https://tnsai.dev/docs/capabilities/llm/observability): Capture every LLM call as a typed LLMCallLog event — prompt, response, token usage, cost, streaming timing, errors, full context. One publish call per request, decorator-shaped so any provider works without modification. - [LLM Providers](https://tnsai.dev/docs/capabilities/llm/providers): The LLM module provides a unified interface to 30+ language-model providers. Every provider implements the same LLMClient interface, so switching providers means changing one line — the model name and provider key — not your agent code. - [LLM Routing](https://tnsai.dev/docs/capabilities/llm/routing): Route requests across multiple LLM providers with built-in strategies. Routing enables failover, cost optimization, latency reduction, and capability-based model selection. - [RAG](https://tnsai.dev/docs/capabilities/rag): Retrieval-Augmented Generation — from knowledge base setup to production pipelines. - [Knowledge Base & RAG](https://tnsai.dev/docs/capabilities/rag/knowledge-base): TnsAI provides a built-in Retrieval-Augmented Generation (RAG) system through the KnowledgeBase interface, Document model, and @KnowledgeSource annotation. Agents can retrieve relevant context from vector databases, files, URLs, or in-memory stores before making LLM calls. - [RAG Pipeline](https://tnsai.dev/docs/capabilities/rag/pipeline): The server provides a per-session Retrieval-Augmented Generation pipeline that indexes local codebases, chunks source files by language boundaries, and retrieves relevant context using hybrid BM25 + vector search with Reciprocal Rank Fusion. - [RAG Strategy SPI](https://tnsai.dev/docs/capabilities/rag/strategies): TnsAI.Intelligence provides a pluggable Retrieval-Augmented Generation (RAG) framework with three built-in strategies and a composable pipeline. Package: com.tnsai.intelligence.rag. - [Skills](https://tnsai.dev/docs/capabilities/skills): On-demand modular knowledge between role and tools. The framework's answer to: how do I keep multi-step procedures and domain knowledge out of the always-on system prompt without losing them when they're actually relevant? - [Registration](https://tnsai.dev/docs/capabilities/skills/registration): How to wire a SkillStore and SkillResolver into an AgentBuilder, swap the defaults, and integrate skill activation with the rest of the framework. - [SKILL.md format](https://tnsai.dev/docs/capabilities/skills/skill-format): A SKILL.md file is a YAML frontmatter block followed by a markdown body. The framework's parser (SkillMdParser) accepts the same shape Claude Code's parser does, so a skill authored once works in both environments. - [Tools](https://tnsai.dev/docs/capabilities/tools): Use the shipped POJO toolkit catalog, write custom @Tool methods, and control how the LLM dispatches them. - [Tools — Advanced](https://tnsai.dev/docs/capabilities/tools/advanced): The function-shape POJO model deliberately keeps the tool surface small: a method, an annotation, a registry. Most "advanced" features that older docs covered (manifest generators, contract validators, security enforcers, parameter validators, retry/cache wrappers) were retired together with the legacy Tool interface in v0.6.0 / v0.7.0. Cross-cutting concerns now live one layer up — on the @ActionSpec annotation, on the agent's setToolCallFilter / setToolCallListener hooks, or on the dispatcher itself. - [Tool Catalog](https://tnsai.dev/docs/capabilities/tools/catalog): tnsai-tools ships 59 function-shape POJO toolkits exposing roughly 206 @Tool-annotated methods across 29 categories. Each toolkit is a plain class with public methods annotated @Tool; the framework discovers them reflectively via ToolMethodRegistry and dispatches calls through ToolMethodDispatcher (the same path used for any user POJO registered with AgentBuilder.toolPojos(...)). - [Custom Tools](https://tnsai.dev/docs/capabilities/tools/custom-tools): A custom tool in TnsAI is a plain Java class with public methods annotated @Tool. The framework discovers them reflectively and exposes each method as a function the LLM can call. There is no base class to extend, no SPI to register, no Tool interface to implement — just an instance you hand to AgentBuilder.toolPojos(...). - [Tool Use Examples](https://tnsai.dev/docs/capabilities/tools/examples): Tool use examples are concrete input/output pairs (and counter-examples) that travel alongside a tool definition to the LLM. They teach the model the call patterns the tool expects — including patterns that look reasonable from a language standpoint but break the contract. - [Idempotency](https://tnsai.dev/docs/capabilities/tools/idempotency): When a tool gets retried — by @Resilience(retry = …), by an upstream gateway, by a flaky network — the framework needs a way to make sure the side effect happens once. @Idempotent plus an IdempotencyStore is that mechanism. - [Multimodal Tools](https://tnsai.dev/docs/capabilities/tools/multimodal): Three aggregator toolkits in tnsai-tools give an agent text→image, text→speech, and speech→text capability without the consumer having to write provider plumbing. Each toolkit is a function-shape POJO (RFC #188) that exposes one @Tool-annotated method per backend provider, so the LLM can pick a provider at call time based on quality, latency, or cost. - [Tool Integration](https://tnsai.dev/docs/capabilities/tools/registration): A "tool" in TnsAI is a Java method annotated @Tool. Methods are grouped on POJO classes (toolkits); the framework discovers them reflectively at agent build time and exposes each as a function the LLM can call. Two registration paths share the same underlying ToolMethodRegistry: - [Advanced Tool Features](https://tnsai.dev/docs/capabilities/tools/registration-advanced): Beyond the basic registration paths covered in Tool Integration, the dispatcher layer exposes a small number of advanced surfaces: filter / listener composition, tool introspection, and direct invocation of tools outside the LLM loop. ## Multi-Agent - [Advanced Patterns](https://tnsai.dev/docs/multi-agent/advanced): Advanced coordination patterns in TnsAI.Coordination for production multi-agent systems. - [AutoTeamBuilder](https://tnsai.dev/docs/multi-agent/auto-team): TnsAI.Intelligence provides LLM-driven automatic team composition. Given a task description, AutoTeamBuilder decomposes it into subtasks, generates agent configurations, and selects the optimal coordination topology. Package: com.tnsai.autoteam. - [Agent Communication](https://tnsai.dev/docs/multi-agent/communication): TnsAI agents communicate through structured, immutable messages following established multi-agent protocols. The communication system supports direct messaging, Contract Net Protocol (CNP) for task allocation, group membership management, and leader election. - [Council and Voting](https://tnsai.dev/docs/multi-agent/council-voting): TnsAI.Coordination provides two complementary systems for group decision-making: CouncilExecutor for multi-model deliberation with peer review, and ConsensusBuilder / GroupDecisionFramework for agent voting. - [Judge Agent Pattern](https://tnsai.dev/docs/multi-agent/judge): TnsAI.Coordination provides a judge agent pattern for evaluating and selecting the best output from multiple agents. A judge applies a policy to score candidate outputs and pick a winner. Package: com.tnsai.coordination.judge. - [Negotiation](https://tnsai.dev/docs/multi-agent/negotiation): TnsAI.Coordination provides a pluggable negotiation framework with 4 built-in protocols, configurable concession strategies, and a unified NegotiationExecutor that resolves the correct protocol from configuration. - [Communication Protocols](https://tnsai.dev/docs/multi-agent/protocols): TnsAI provides annotation-driven inter-agent communication through ProtocolManager. Annotate your agent class with one or more communication paradigms and the framework auto-configures handlers, transports, and discovery. - [Group Topologies](https://tnsai.dev/docs/multi-agent/topologies): TnsAI.Coordination provides 8 group topologies for structuring multi-agent collaboration. Each topology has a dedicated builder and follows the lifecycle: create -> start -> execute -> stop. - [Workflows](https://tnsai.dev/docs/multi-agent/workflows): TnsAI.Coordination provides two workflow executors: DAGExecutor for parallel dependency-graph execution and SagaExecutor for sequential execution with compensation (rollback) on failure. ## Reference - [Annotations Reference](https://tnsai.dev/docs/reference/annotations): TnsAI ships its declarative annotation surface grouped by purpose — BDI (Belief-Desire-Intention), Gaia (roles + environment), channels, pipelines, security, observability, and core dispatch. The full catalog below documents every annotation, its fields, and example usage. Counts drift between releases; the catalog is the authoritative list. - [Semantic Annotation Framework](https://tnsai.dev/docs/reference/annotations/catalog) - [Configuration Reference](https://tnsai.dev/docs/reference/configuration): A consolidated reference for the knobs you can set on TnsAI from outside the code (env vars) or through builders. This page indexes the canonical sources rather than duplicating them — the goal is to tell you where to look, not to mirror state that will drift. - [Glossary](https://tnsai.dev/docs/reference/glossary): Quick lookup for the abbreviations and TnsAI-specific terms that appear in the rest of the documentation. Linked terms go to the page that explains the concept in depth. - [TnsAI as a Large Action Model (LAM) Framework](https://tnsai.dev/docs/reference/lam-pattern) - [SPI Reference](https://tnsai.dev/docs/reference/spi): TnsAI.Core uses Java's ServiceLoader mechanism extensively for cross-module extensibility. SPI interfaces define contracts in the core module; implementations live in optional modules and are discovered at runtime via META-INF/services/ registration. - [Tool Catalog Reference](https://tnsai.dev/docs/reference/tool-catalog) ## Tutorials - [Tutorial: Agent with Tool Approval](https://tnsai.dev/docs/tutorials/agent-with-tool-approval): A full code walkthrough is still being written. In the meantime this page describes the shape and points at the framework pieces you can wire up today. Open a discussion if you start the implementation and hit something missing. - [Tutorial: Reusable Capabilities](https://tnsai.dev/docs/tutorials/capability-pattern): Build an editorial agent that can summarise, translate, and classify sentiment — without writing a single body for those action methods. This tutorial walks through the @Capability pattern, showing composition, override, and the common mistakes the framework prevents. - [Tutorial: Customer Support Bot](https://tnsai.dev/docs/tutorials/customer-support-bot): A full code walkthrough for this tutorial is still being written. In the meantime this page describes the shape of the system and links to the framework pieces you'd compose to build it. If you start the implementation and hit something missing, open a discussion — concrete questions accelerate the write-up. - [Tutorial: Declarative input/output guardrails](https://tnsai.dev/docs/tutorials/declarative-guardrails): Validate, sanitise, and bound every action's parameters and return value through annotations alone — no per-action if (input.length() > N) throw … plumbing in your Role. The framework's InputGuardrailEnforcer and OutputGuardrailEnforcer enforce the contract at dispatch time, before and after the action body runs. - [Tutorial: Declarative RAG with @KnowledgeSource and @Retrieval](https://tnsai.dev/docs/tutorials/declarative-rag): Wire knowledge sources to a Role and retrieve from them on every action call — through annotations alone. No manual Embedding embed = ...; vectorStore.search(query, k) plumbing in your role; the framework binds and dispatches. - [Tutorial: Declarative resilience with @Traced, @Metered, and @Fallback](https://tnsai.dev/docs/tutorials/declarative-resilience): Wrap every action dispatch with structured tracing, latency + counter metrics, and automatic recovery on failure — through annotations alone. The framework's ActionExecutor applies the decorators in canonical order; your action body stays focused on the business logic. - [Tutorial: Multi-Agent Research Team](https://tnsai.dev/docs/tutorials/multi-agent-research-team): A full code walkthrough is still being written. In the meantime this page describes the topology and points at the framework pieces you can wire up today. Open a discussion if you start the implementation and hit something missing. - [Tutorial: Research Agent](https://tnsai.dev/docs/tutorials/research-agent): Build an agent that takes a research question, searches the web, reads PDF sources, and produces a cited summary. - [Tutorial: REST API actions with @WebService](https://tnsai.dev/docs/tutorials/web-service-action): Bind any REST endpoint to an LLM-callable action through annotations alone — no OkHttpClient plumbing, no manual JSON parsing, no per-call retry loops in your Role. The framework's WebServiceExecutor handles the wire-format work; your Role just declares what to call. ## Help - [Changelog](https://tnsai.dev/docs/help/changelog): Release notes for the TnsAI framework. Newest version first; each section covers what changed, why, and what consumers need to do to upgrade. - [FAQ](https://tnsai.dev/docs/help/faq) - [Migration](https://tnsai.dev/docs/help/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. - [Troubleshooting](https://tnsai.dev/docs/help/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. ## Evaluation - [Advanced Evaluation](https://tnsai.dev/docs/evaluation/advanced): This guide covers the specialized evaluator families introduced in 0.3.0: RAG evaluators for retrieval-augmented generation pipelines, multi-turn evaluators for conversation quality, safety evaluators for harmful content detection, and the trace-eval bridge that connects observability with evaluation. ## Integrate - [Agent ecosystem integration](https://tnsai.dev/docs/integrate/agent-ecosystem): How TnsAI fits into the wider agent + tooling landscape: which protocols TnsAI speaks natively, how it's consumed by IDEs and other agent runtimes, and what conventions help LLMs use the framework directly. - [SCOP Bridge](https://tnsai.dev/docs/integrate/scop): The Integration module connects TnsAI with SCOP — a separate Java multi-agent development and experimentation framework — via reflection-based discovery. No compile-time dependency on SCOP is required; detection happens at runtime. The bridge also provides an HTTP fallback transport for 11 LLM providers when Core's native SPI implementations are unavailable. ## Mcp - [MCP Advanced Features](https://tnsai.dev/docs/mcp/advanced): Composio integration, database MCP clients, Goose interoperability, Stripe payments, testing utilities, and OAuth authentication. - [MCP Client](https://tnsai.dev/docs/mcp/client): The McpClient connects to any MCP-compatible server and exposes its tools, resources, and prompts. - [MCP Registry](https://tnsai.dev/docs/mcp/registry): The MCP module provides a unified registry that aggregates MCP server entries from 4 public sources, with deduplication, caching, and protocol version filtering. It also includes a testing toolkit for MCP server development. - [MCP Server](https://tnsai.dev/docs/mcp/server): The McpServer exposes TnsAI tools, resources, and prompts to MCP clients. - [MCP Transports](https://tnsai.dev/docs/mcp/transports): The MCP module provides 5 transport implementations plus an OAuth decorator and an auto-detection utility for connecting to MCP servers over stdio, HTTP, SSE, and bidirectional streaming. ## Security - [Accountability](https://tnsai.dev/docs/security/accountability): Verifiable identity, audit-grade liability records, reputation, and agent-to-agent settlement. The framework's answer to: who is responsible for what an agent did, can it be re-verified later, and can it transact across trust boundaries? - [Security & Approvals](https://tnsai.dev/docs/security/approvals-and-annotations): TnsAI provides a layered security model for agent actions: approval tokens for human-in-the-loop gating, AG-UI interrupts for blocking agent execution until a user responds, input/output guardrails for validation and sanitization, and a declarative @Security annotation that combines audit, access control, and encryption policies in one place. - [Code Review Harness](https://tnsai.dev/docs/security/code-review-harness): Agent-driven, idempotent, fan-out-safe security review pipeline (TNS-291). Takes a codebase, runs static matchers as a pre-filter, invokes an LLM agent on each candidate file, and produces structured ReviewFindings exportable as SARIF, JSON, or Markdown. - [Cost Governance](https://tnsai.dev/docs/security/cost-governance): Cap LLM spend per tenant, agent, or capability with declarative budgets backed by a pluggable spend store. Pairs with LLM observability — every captured LLMCallLog carries a cost estimate; the cost-governance layer reads cumulative spend and enforces a policy when a budget is exhausted. - [Encryption](https://tnsai.dev/docs/security/encryption) - [Security](https://tnsai.dev/docs/security/enforcement): The Quality module provides a layered security framework: annotation-driven access control and encryption (SecurityEnforcer), content moderation (PatternBasedModerator), prompt injection detection (PromptInjectionDetector), sandboxed execution, audit logging, and input validation (ValidationService). - [Prompt Injection Defense](https://tnsai.dev/docs/security/prompt-injection) - [Redaction](https://tnsai.dev/docs/security/redaction): The Quality module ships a pluggable redaction layer that scrubs PII and secrets out of every framework boundary that could leak — log lines, trace attributes, memory writes, captured LLM prompts, agent events. Redaction is always-on when the decorator is wired in; opt-out is per-tenant per-sink, never the default. - [Sandbox](https://tnsai.dev/docs/security/sandbox): Run untrusted code through a lightweight, isolated, fast primitive. The framework's answer to: how do I run LLM-generated code or untrusted shell commands without giving them access to the host's filesystem, network, or unbounded resources? - [Server Hardening](https://tnsai.dev/docs/security/server-hardening): tnsai-server exposes the framework over HTTP + WebSocket. Every input — HTTP body, WS frame, query param — is potentially attacker-controlled if the listener is reachable. The hardening surface in com.tnsai.server.security (TNS-302) is built on five concentric defences, every one of which is ## Server - [Server Advanced Features](https://tnsai.dev/docs/server/advanced): Declarative hooks, agent factory, idle shutdown management, and the RAG pipeline (indexing, chunking, retrieval). - [Tool Approval](https://tnsai.dev/docs/server/tool-approval): The server implements a risk-based tool approval system that classifies tool calls by danger level, checks them against the session's autonomy setting, and either auto-approves or blocks the agent's virtual thread until the user responds via WebSocket. - [WebSocket Protocol](https://tnsai.dev/docs/server/websocket): The Server module is a Javalin-based backend that bridges frontends (CLI, IDE, web) to the TnsAI agent framework via WebSocket. It provides multi-agent sessions, real-time streaming, risk-based tool approval, hybrid RAG search, and an audit trail. ## Sona - [Channels](https://tnsai.dev/docs/sona/channels): A channel is one way humans talk to Sona. The framework's tnsai-channels module defines the SPI; each adapter is one implementation that translates a platform-specific transport into the gateway's UnifiedMessage / UnifiedResponse records. - [CLI](https://tnsai.dev/docs/sona/channels/cli): The CLI channel turns your terminal into a Sona client. Two modes: - [Email](https://tnsai.dev/docs/sona/channels/email): Sona's email channel polls an IMAP inbox for new mail and replies through an SMTP server. It's the right pick when you want Sona reachable from any device a person already uses email on — phones, work laptops, shared accounts — without installing a new app. - [Telegram](https://tnsai.dev/docs/sona/channels/telegram): Telegram is Sona's default channel. The adapter long-polls the Bot API, so you don't need a public IP, a tunnel, or a webhook server — Sona pulls updates over an outbound HTTPS connection. - [How Sona Works](https://tnsai.dev/docs/sona/how-it-works): Sona is mostly routing. The LLM, the tool calls, the streaming — all of that is tnsai-core doing its job. Sona's contribution is deciding which agent should hear an inbound message, keeping a session for each (channel, sender) pair, and enforcing a pairing policy so strangers can't burn your LLM budget. - [Machine-readable mode](https://tnsai.dev/docs/sona/json-mode): Every non-streaming sona command accepts --json and emits a single-line envelope. Streaming commands (chat) emit one envelope per chunk (ndJSON). This is the surface you wire orchestrators, CI pipelines, and parent agents against — no scraping of human text, no fragile regex. - [Sona Quickstart](https://tnsai.dev/docs/sona/quickstart): Five minutes from a fresh shell to a Telegram message round-tripping through your own agent. You need: