# TnsAI Framework

> Java framework for building production-grade AI agents.
> Multi-module monorepo (12 framework modules: core, llm, intelligence,
> coordination, quality, evaluation, mcp, tools, channels, payments,
> integration, server), plus OpenRewrite migration tooling and a BOM.
> Annotation-driven, SPI-extensible,
> Maven Central published as `dev.tnsai:tnsai-bom:0.16.4`.

Version: 0.16.4 — see /docs/help/changelog

Raw markdown for any page below is served at the same path under https://tnsai.dev/docs-src/ — e.g. https://tnsai.dev/docs/agents/fundamentals → https://tnsai.dev/docs-src/agents/fundamentals/index.md

## 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.
- [Contracts (`@Contract`)](https://tnsai.dev/docs/contracts): @Contract brings Design by Contract to actions: JEXL preconditions, postconditions, and invariants that the framework enforces around every action invocation. Preconditions reject bad input (including parameters an LLM hallucinated) before the method runs; postconditions catch incorrect results or corrupted state after it runs.
- [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)
- [Payments](https://tnsai.dev/docs/payments): TnsAI agents talk to other agents. Sometimes the other agent charges. The PaymentBroker SPI is the framework's answer to "how does an agent settle a payment without you, the human, in the loop?" — same surface for free internal calls (PaymentBroker.noOp()), real on-chain micropayments (X402PaymentBroker), or your own custom rail.
- [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.
- [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)
- [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.
- [Actions vs Tools](https://tnsai.dev/docs/agents/fundamentals/actions-vs-tools): TnsAI has three overlapping extension points. They are not interchangeable.
- [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 observability into an agent run. Events implement the sealed TnsAIEvent hierarchy in com.tnsai.events. You cannot add a custom implementation: only the permitted records below exist.
- [Roles](https://tnsai.dev/docs/agents/fundamentals/roles): A Role defines what an agent can do. Each role has an identity (name, goal, domain) and discoverable actions. Safety constraints live on those actions (@ActionSpec.mustNever / mustAlways), not on the role itself. 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 JSON parameter schemas for LLM tools, agent identity and communication style modeling, decentralized identifiers (DIDs), and 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.
- [External LLM Configuration](https://tnsai.dev/docs/capabilities/llm/configuration-sources): An agent's provider, model and tuning normally come from annotations, which are compiled into the artifact. LLMConfigurationSource adds a layer above them that an operator can change without recompiling: one JSON file per agent, or a set of environment variables.
- [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 31 concrete language-model providers (every non-abstract *Client under com.tnsai.llm.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)
- [Agent-level action RAG](https://tnsai.dev/docs/capabilities/rag/agent-knowledge): @AgentSpec.knowledge() and @AgentSpec.retrieval() are the annotation counterparts of AgentBuilder.addKnowledgeSource and AgentBuilder.retrieval. Both members are @since 0.14.0 in TnsAI 0.14.0 (TnsAI@c2bb5306). They ship in Maven Central 0.14.1.
- [RAG diagnostics](https://tnsai.dev/docs/capabilities/rag/diagnostics): com.tnsai.intelligence.rag.binding.RagDiagnostics is @since 0.15.0 (TnsAI@32e17445, PR #199 / TAN-5888). It ships in 0.15.0 and later — see Installation for the coordinates.
- [Embedding prefixes](https://tnsai.dev/docs/capabilities/rag/embeddings): EmbeddingFunctions.matryoshka derives a shorter, L2-normalized prefix from any EmbeddingFunction. The helper and EmbeddingDimensionMismatchException are @since 0.14.0 in TnsAI 0.14.0 (TnsAI@c2bb5306). They ship in Maven Central 0.14.1.
- [File formats and ingestion](https://tnsai.dev/docs/capabilities/rag/formats): KnowledgeType.FILE says where documents come from (a path). DocumentFormat says how their bytes are interpreted. They are not the same field.
- [KnowledgeTools as GraphRAG](https://tnsai.dev/docs/capabilities/rag/graph-knowledge-tools): KnowledgeToolsGraphStoreProvider is the bundled GraphStoreProvider that serves live KnowledgeTools triples to @Retrieval(strategy = GRAPH). The provider is @since 0.14.0 in TnsAI 0.14.0 (TnsAI@c2bb5306). It ships in Maven Central 0.14.1.
- [Graph stores](https://tnsai.dev/docs/capabilities/rag/graph-stores): TnsAI 0.14.0 (TnsAI@34454153, TAN-3091 / PR #130) ships two GraphStoreProvider adapters for @Retrieval(strategy = GRAPH). Both are @since 0.14.0. They ship in Maven Central 0.14.1.
- [Hybrid graph stream](https://tnsai.dev/docs/capabilities/rag/hybrid-graph): In TnsAI 0.14.0 (TnsAI@4b9aff80), HybridRAGStrategy can RRF-fuse a third knowledge-graph ranking with BM25 and vector. The strategy name stays hybrid. The three-argument constructor and HybridGraphStream are @since 0.14.0. They ship in Maven Central 0.14.1.
- [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.
- [pgvector vector index](https://tnsai.dev/docs/capabilities/rag/pgvector): TnsAI 0.14.0 (TnsAI@816ed1b9, TAN-3096 / PR #141) ships an optional pgvector backend for VectorMemoryStore. The types are @since 0.14.0. They ship in Maven Central 0.14.1.
- [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.
- [Qdrant vector index](https://tnsai.dev/docs/capabilities/rag/qdrant): TnsAI 0.14.0 (TnsAI@01fba8ef, TAN-3101 / PR #131) ships an optional Qdrant backend for VectorMemoryStore. The types are @since 0.14.0. They ship in Maven Central 0.14.1.
- [Vectorless reasoning retrieval](https://tnsai.dev/docs/capabilities/rag/reasoning): Retrieval.Strategy.REASONING descends a document tree with a model choosing the branch. It does not score fragments, so there is no embedding and no similarity on the path. The strategy and the TreeNavigator SPI are @since 0.14.0 in TnsAI 0.14.0 (TnsAI@c2bb5306). They are in Maven Central 0.14.1.
- [Smart document segmentation](https://tnsai.dev/docs/capabilities/rag/segmentation): com.tnsai.intelligence.rag.segment.SmartDocumentSegmenter splits a long paper on headings and returns com.tnsai.intelligence.rag.segment.DocumentSegment records. Both are @since 0.14.0 in TnsAI 0.14.0 (TnsAI@609a661d, TAN-3651). They ship in Maven Central 0.14.1.
- [Selective re-embed index](https://tnsai.dev/docs/capabilities/rag/selective-reembed): com.tnsai.intelligence.rag.vector.SelectiveReembedIndex is a local vector index that re-embeds only chunks whose content hash changed. It is @since 0.14.0 in TnsAI 0.14.0 (TnsAI@1291fe9e, TAN-3660 / PR #150). It ships in Maven Central 0.14.1.
- [Ordered knowledge-unit consumption](https://tnsai.dev/docs/capabilities/rag/sequential-consumption): @Sequential, SequentialConfig, and SequentialUnitReader are @since 0.15.0. They first landed on framework main at TnsAI@933756d1 (PR #222 / TAN-5880). They ship in 0.15.0 and later — see Installation for the coordinates.
- [RAG Strategy SPI](https://tnsai.dev/docs/capabilities/rag/strategies): TnsAI 0.14.1 provides eight retrieval strategies in com.tnsai.intelligence.rag. You can construct them directly for an application-owned pipeline or select the matching mode through @Retrieval. Those entry points share strategy names, but they do not share every default or provider requirement.
- [Controlled RAG write-back](https://tnsai.dev/docs/capabilities/rag/write-back): TnsAI 0.14.0 (TnsAI@4b57a851, TAN-3009 / PR #151) ships a package-private, default-disabled write-back overlay in com.tnsai.intelligence.rag.binding.ControlledWriteBackStore. It is in Maven Central 0.14.1. There is no public constructor, no RetrievalEngine write method, and no @since on a published type.
- [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.
- [Actions vs Tools](https://tnsai.dev/docs/capabilities/tools/actions-vs-tools): Three names sit next to each other in TnsAI. They are not interchangeable.
- [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 63 function-shape POJO toolkits exposing 209 @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(...).
- [Docling](https://tnsai.dev/docs/capabilities/tools/docling): Shipped in 0.14.0 (TAN-3648, framework PR #153, commit eeb16b48). DoclingTools is the 63rd POJO toolkit and contributes one @Tool method.
- [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 generates a configured multi-agent team from a natural-language task. AutoTeamBuilder decomposes the task, writes per-agent prompts, picks a formation, and instantiates the agents. 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): JudgeCoordinator wraps a coordination cycle with a JudgePolicy. After each attempt the policy returns a JudgeVerdict of APPROVE, RETRY, or REJECT. This is cycle-end quality control for one agent's output, not a tournament that ranks several candidates. 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.
- [Topology selection](https://tnsai.dev/docs/multi-agent/topology-selection): tnsai-coordination ships eight groups/ topologies. The trap is picking the one that matches an org chart. For a novel problem that needs continuous reasoning, that choice is usually wrong: each hop compresses context, and the whole drifts even when every node looks fine in isolation.
- [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 — roles, actions, resilience, communication, coordination, memory, security, contracts, lifecycle, channels, skills, fallback, and observability. 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): Use this page as an annotation lookup and index. Topic pages remain the teaching source for complete declarative/programmatic examples, precedence, and field status. The first parity pilots are RAG and Memory; later topic conversions should replace duplicated teaching prose here with links in the same way.
- [Annotation Runtime Status](https://tnsai.dev/docs/reference/annotations/runtime-status): A reference of the annotations TnsAI exposes in com.tnsai.annotations, grouped by area, with each one's runtime status so you know what actually takes effect.
- [Configuration Reference](https://tnsai.dev/docs/reference/configuration): Use this page when you need the exact environment variable or programmatic entry point for a TnsAI runtime. Values passed to constructors or builders take precedence over environment variables unless a linked API says otherwise.
- [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 Language-Action Model (LAM)](https://tnsai.dev/docs/reference/lam-pattern): Industry writing calls this a Large Action Model: an LLM that does not stop at text, but selects and runs typed actions. In TnsAI that mapping is @ActionSpec methods plus registered tools. The chat loop is LLM + tools, not a BDI interpreter — see Roles.
- [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 Action RAG](https://tnsai.dev/docs/tutorials/declarative-rag): Use @KnowledgeSource to declare a corpus and @Retrieval to ground a specific action. TnsAI loads the corpus lazily, retrieves matching documents before the action executor runs, and adds the formatted context to the request sent by an ActionType.LLM action.
- [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

- [Migrate 0.11 → 0.12](https://tnsai.dev/docs/help/0.11-to-0.12): This is the combined 0.11.0 → 0.12.0 path. Source of truth is the framework CHANGELOG [0.12.0] - 2026-06-04 (published via Changelog). The current lockstep line is 0.14.0 — after this page, read 0.13.0 and 0.14.0.
- [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 current published Maven Central release is listed on Installation. 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.
- [Bilingual embedding bench](https://tnsai.dev/docs/evaluation/embedding-bench): tnsai-evaluation ships an opt-in multilingual retrieval bench (EmbeddingBenchRunner, @since 0.14.0 on TnsAI@c28d8783). It is in Maven Central 0.14.1. Default mvn test stays offline and does not call a model host.

## 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.

## Payments

- [x402 Payments](https://tnsai.dev/docs/payments/x402): x402 is a Coinbase-led standard for HTTP-native micropayments. A server signals "this resource costs money" with a real HTTP 402; the client signs a one-time USDC transfer authorisation (EIP-3009), replays the request with the signature in a header, and the server validates and serves the response. Settlement happens on Base (EVM L2) at fractions of a cent per call.

## 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).
- [Guardrails — three different things](https://tnsai.dev/docs/security/guardrails): TnsAI uses the word guardrail for three distinct APIs in three modules. They are not interchangeable: different types, different call sites, different imports. Pick by when you need to gate something.
- [PII input guardrails](https://tnsai.dev/docs/security/pii-input-guardrails): TnsAI 0.14.0 (@since 0.14.0). TnsAI PR #168 (81b2fb95, TAN-3016) adds executable @InputGuardrail validators and sanitizers, including built-in PII detection. This ships in Maven Central 0.14.1.
- [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 enabled by default:

## 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.