# TnsAI Framework
**Official documentation for the TnsAI framework**
*Java framework for building AI agents on the JVM — roles, capabilities,
tools, RAG, multi-agent coordination, MCP.*
[](https://github.com/TnsAI-Framework/TnsAI.Docs/blob/main/LICENSE)
---
## Documentation Structure
This repository is organized as a learning path. Each section builds on the previous one.
### [Start Here](start/index.md)
Zero to running agent in under 10 minutes.
- [Installation](start/installation.md) · [Quickstart](start/quickstart.md) · [Architecture Overview](start/architecture-overview.md) · [Module Overview](start/module-overview.md)
### [Agents](agents/index.md)
Everything about building a single agent.
- [Fundamentals](agents/fundamentals/index.md) — Agents, roles, action system, events.
- [Behavior](agents/behavior/index.md) — Prompts, output parsing, streaming, variants, memory.
- [Reliability](agents/reliability/index.md) — Resilience, error handling, schema identity.
- [Advanced](agents/advanced.md) — Cognitive support, planner/reasoner handles, ensemble execution.
### [Capabilities](capabilities/index.md)
Pluggable building blocks that extend what an agent can do.
- [Tools](capabilities/tools/index.md) — 62 POJO toolkits (210 `@Tool` methods) across 30 categories, custom tools, registration.
- [Intelligence](capabilities/intelligence/index.md) — Planning (GOAP/HTN), reasoning (ReAct/ToT), FSM, context, learning.
- [RAG](capabilities/rag/index.md) — Knowledge base, strategies, production pipeline.
- [LLM](capabilities/llm/index.md) — Providers, routing, caching, cost tracking, audio.
### [Multi-Agent](multi-agent/index.md)
Systems of cooperating agents.
- Topologies, workflows, council & voting, negotiation, judge, protocols, communication, auto team, delegation.
### [Observability](observability.md)
OpenTelemetry traces, metrics, structured logs, structured tracing for agent runs.
### [Validation](validation.md)
Invariant checks, guardrails, schema validation, content guardrails.
### [Contracts](contracts.md)
Design-by-Contract for actions: JEXL preconditions, postconditions, and invariants (`@Contract` / `ContractSpec`).
### [Annotation Catalog](annotation-catalog.md)
Every framework annotation grouped by area, with its runtime status (wired / partial / scaffold) so you know what actually takes effect.
### [Security](security/index.md)
- [Approvals and Annotations](security/approvals-and-annotations.md) · [Enforcement](security/enforcement.md) · [Encryption](security/encryption.md) · [Prompt Injection](security/prompt-injection.md)
### [Evaluation](evaluation/index.md)
- Evaluators, benchmarks, quality gates, LLM-as-judge, evaluation hooks.
### [Server](server/index.md)
Run TnsAI as a backend.
- [WebSocket](server/websocket.md) — The v1 WebSocket protocol.
- [Tool Approval](server/tool-approval.md) — Human-gated destructive operations.
- [Advanced](server/advanced.md) — Scaling, persistence, multi-tenant.
### [MCP](mcp/index.md)
Model Context Protocol — client, server, transports, registry.
- [Client](mcp/client.md) · [Server](mcp/server.md) · [Transports](mcp/transports.md) · [Registry](mcp/registry.md) · [Advanced](mcp/advanced.md)
### [Channels](channels.md)
External messaging adapters — Telegram, CLI, Email, Slack, Discord, WhatsApp.
### [Payments](payments/index.md)
Agent-to-agent settlement via the pluggable `PaymentBroker` SPI.
- [x402 (HTTP 402 + EIP-3009)](payments/x402.md) — Coinbase-led standard for HTTP-native USDC micropayments.
### [Integrate](integrate/index.md)
Bridges to other protocols and frameworks.
- [SCOP](integrate/scop.md) — Bridge to the [SCOP framework](https://scop-framework.netlify.app/) (includes advanced topics).
### [Reference](reference/index.md)
Look it up.
- [Annotations](reference/annotations/index.md) — Annotation catalog.
- [Tool Catalog](reference/tool-catalog.md) · [SPI](reference/spi.md) · [LAM Pattern](reference/lam-pattern.md)
- [Configuration](reference/configuration.md) · [Glossary](reference/glossary.md)
### [Tutorials](tutorials/index.md)
End-to-end walkthroughs.
### [Help](help/index.md)
- [FAQ](help/faq.md) · [Troubleshooting](help/troubleshooting.md) · [Migration](help/migration.md) · [Changelog](help/changelog.md)
---
## Framework Modules
All framework modules live in the [`TnsAI`](https://github.com/TnsAI-Framework/TnsAI) monorepo and ship at the same lockstep version via the [BOM](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-bom).
| Module | Source | Description |
|--------|--------|-------------|
| Core | [tnsai-core](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-core) | Agent lifecycle, Role, Action, tool dispatch, annotations |
| LLM | [tnsai-llm](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-llm) | LLMClient implementations for 31 providers |
| Intelligence | [tnsai-intelligence](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-intelligence) | FSM, planning, reasoning, RAG strategies |
| Coordination | [tnsai-coordination](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-coordination) | Multi-agent groups, topologies, voting, negotiation |
| Quality | [tnsai-quality](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-quality) | Observability, security, validation |
| Evaluation | [tnsai-evaluation](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-evaluation) | Agent evaluation and benchmarking |
| MCP | [tnsai-mcp](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-mcp) | Model Context Protocol client + server |
| Tools | [tnsai-tools](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-tools) | POJO toolkits across web · file · DB · code · media · fintech · … |
| Channels | [tnsai-channels](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-channels) | Telegram / CLI / Email / Slack / Discord / WhatsApp adapters via SPI |
| Payments | [tnsai-payments](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-payments) | Agent-to-agent settlement via the PaymentBroker SPI — x402 adapter |
| Integration | [tnsai-integration](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-integration) | Cross-module integration tests + SCOP bridge |
| Server | [tnsai-server](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-server) | Javalin HTTP/WebSocket agent server, RAG service layer |
| BOM | [tnsai-bom](https://github.com/TnsAI-Framework/TnsAI/tree/main/tnsai-bom) | Bill of Materials — consumer version pinning |
External companion repositories:
| Repository | Description |
|------------|-------------|
| [TnsAI.Web](https://github.com/TnsAI-Framework/TnsAI.Web) | Documentation website (Next.js + Fumadocs, [tnsai.dev](https://tnsai.dev)) |
| [TnsAI.Docs](https://github.com/TnsAI-Framework/TnsAI.Docs) | Official documentation (this repo) |
| [TnsAI.Papers](https://github.com/TnsAI-Framework/TnsAI.Papers) | Research publications |
## Contributing
Documentation contributions welcome. Guidelines:
- All documentation must be in **English**.
- Use clear, concise language.
- Include code examples where applicable.
- Follow the learning path: Start Here → Agents → Capabilities → Multi-Agent → Observability / Validation / Security / Evaluation → Server / MCP / Channels / Integrate → Reference.
## License
[Apache License 2.0](https://github.com/TnsAI-Framework/TnsAI.Docs/blob/main/LICENSE)
---
Part of the [TnsAI Framework](https://github.com/TnsAI-Framework) — *Building Intelligent Multi-Agent Systems*