TnsAI Framework

---

Documentation Structure

This repository is organized as a learning path. Each section builds on the previous one.

Start Here

Zero to running agent in under 10 minutes.

• Installation · Quickstart · Architecture Overview · Module Overview

Agents

Everything about building a single agent.

• Fundamentals — Agents, roles, action system, events.
• Behavior — Prompts, output parsing, streaming, variants, memory.
• Reliability — Resilience, error handling, schema identity.
• Advanced — Cognitive support, planner/reasoner handles, ensemble execution.

Capabilities

Pluggable building blocks that extend what an agent can do.

• Tools — 62 POJO toolkits (~206 @Tool methods) across 29 categories, custom tools, registration.
• Intelligence — Planning (GOAP/HTN), reasoning (ReAct/ToT), FSM, context, learning.
• RAG — Knowledge base, strategies, production pipeline.
• LLM — Providers, routing, caching, cost tracking, audio.

Multi-Agent

Systems of cooperating agents.

• Topologies, workflows, council & voting, negotiation, judge, protocols, communication, auto team, delegation.

Observability

OpenTelemetry traces, metrics, structured logs, structured tracing for agent runs.

Validation

Invariant checks, guardrails, schema validation, content guardrails.

Contracts

Design-by-Contract for actions: JEXL preconditions, postconditions, and invariants (@Contract / ContractSpec).

Annotation Catalog

Every framework annotation grouped by area, with its runtime status (wired / partial / scaffold) so you know what actually takes effect.

Security

• Approvals and Annotations · Enforcement · Encryption · Prompt Injection

Evaluation

• Evaluators, benchmarks, quality gates, LLM-as-judge, evaluation hooks.

Server

Run TnsAI as a backend.

• WebSocket — The v1 WebSocket protocol.
• Tool Approval — Human-gated destructive operations.
• Advanced — Scaling, persistence, multi-tenant.

MCP

Model Context Protocol — client, server, transports, registry.

• Client · Server · Transports · Registry · Advanced

Channels

External messaging adapters — Telegram, CLI, Email, Slack, Discord, WhatsApp.

Payments

Agent-to-agent settlement via the pluggable PaymentBroker SPI.

• x402 (HTTP 402 + EIP-3009) — Coinbase-led standard for HTTP-native USDC micropayments.

Sona

Self-hosted personal AI assistant built on TnsAI — the first concrete consumer of the framework.

• Quickstart — Install, run, send your first Telegram message in 5 minutes.
• How It Works — Gateway, BDI loop, channel adapter SPI, skills, with Mermaid diagrams.

Integrate

Bridges to other protocols and frameworks.

• SCOP — Bridge to the SCOP framework (includes advanced topics).

Reference

Look it up.

• Annotations — Annotation catalog.
• Tool Catalog · SPI · LAM Pattern
• Configuration · Glossary

Tutorials

End-to-end walkthroughs.

Help

• FAQ · Troubleshooting · Migration · Changelog

---

Framework Modules

All framework modules live in the TnsAI monorepo and ship at the same lockstep version via the BOM.

External companion repositories:

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

---