An open-source agentic mesh — governance, security, compliance, and observability for AI agents communicating across the enterprise.
What is Recursant?
Recursant is an enterprise-grade agentic mesh platform — Istio for AI agents. It provides governance, security, compliance, and observability for AI agent deployments where agents talk to each other (A2A protocol) and to tools (MCP).
The architecture has two planes:
- Control plane (
registry/) — Flask + React web app backed by PostgreSQL, Redis, and Kafka. The single source of truth for agent metadata, policies, certificates, and audit history. Includes a full web UI for governance workflows. - Data plane (
mesh/) — A Python sidecar process injected next to every agent pod, mediating all inter-agent traffic over mTLS via the A2A protocol.
Recursant is a runtime governance layer for any AI agent — LangChain, LangGraph, CrewAI, ServiceNow (in-flight), custom HTTP — not a framework for writing agents. Bring your own agent code; Recursant gives it identity, policy enforcement, observability, and compliance guarantees.
Why use it?
If you're running AI agents at any meaningful scale, you eventually hit the same questions:
- Who's allowed to call whom? Hub-and-spoke topologies, sovereignty zones, data classification.
- What's leaking? PII redaction, prompt-injection guardrails, chain-of-thought audit.
- How did this decision get made? Hash-chained audit trail per request, end-to-end traces.
- Is the agent safe to deploy? Automated security scans + LLM-as-judge eval suites + human approval gates.
- What is it costing me? Per-agent token consumption, model breakdown, budget thresholds.
- Did the guardrail catch the attack? Real-time effectiveness matrix, adversarial test runs, false-positive tracking.
Recursant answers all of these without requiring you to rewrite your agents.
How it works
┌────────────────────────────────────────────────────────────────────┐
│ Control Plane (Registry) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ Agent │ │ Policy │ │ Cert │ │ Observability │ │
│ │ Registry │ │ Engine │ │ Authority │ │ (Kafka + UI) │ │
│ └──────────┘ └──────────┘ └──────────────┘ └─────────────────┘ │
└──────────────────────────────────────────────────┬─────────────────┘
│ policy + identity (gRPC / REST)
┌─────────────────────────┴─────────────────────────┐
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Pod: Agent A │ │ Pod: Agent B │
│ ┌────┐ ┌─────┐ │ mTLS, JSON-RPC 2.0 │ ┌────┐ ┌─────┐ │
│ │App │◀┤Side-│◀─┼────────── A2A protocol ────────┼─▶│App │◀┤Side-│ │
│ │ │ │car │ │ │ │ │ │car │ │
│ └────┘ └─────┘ │ │ └────┘ └─────┘ │
└──────────────────┘ └──────────────────┘
Every agent pod gets a sidecar injected by a Kubernetes mutating admission webhook. The sidecar runs an interceptor pipeline — authentication, authorisation, compliance, PII redaction, guardrails, audit, rate limiting, resilience — for every inbound and outbound message. Agent code is unchanged.
For the full architecture, see ARCHITECTURE.md.
For the catalog of capabilities, see FEATURES.md.
Quick start
Recursant runs in Kubernetes (Kind for local dev, any cluster in production). The fastest path to a working demo:
# 1. Configure secrets (at minimum: an LLM API key) cp .env.sample .env $EDITOR .env # set OPENROUTER_API_KEY (or ANTHROPIC_/OPENAI_/GOOGLE_API_KEY) # 2. One command to bring everything up — Kind cluster, build all images, # deploy via Helm, smoke test ./scripts/install.sh # 3. Open the registry UI (login: admin / value of ADMIN_PASSWORD) open http://localhost:8030
Full install + deployment guide: INSTALL.md.
Try the mortgage demo
Recursant ships with a complete mortgage origination demo — a Customer Agent hub coordinating Auth, KYC (n8n workflow), Credit, Core Banking, and Compliance (CrewAI) spokes, with hub-and-spoke NetworkPolicy enforcement and a full audit trail.
# Mortgage demo UI open http://localhost:8031 # End-to-end test — walks the full mortgage application journey python3 demo/mortgage/scripts/test_e2e.py # Continuous traffic generator (great for live demos / recordings) python3 demo/mortgage/scripts/generate_demo_traffic.py --interval 8
Watch traffic animate live in the Mesh Visualiser and Observability tabs of the registry UI.
Repository layout
recursant/
├── registry/ # Control plane — Flask API + React frontend
│ ├── app/
│ │ ├── api/ # REST blueprints (agents, mesh, guardrails, ...)
│ │ ├── consumers/ # Kafka consumer services (pg-writer, ws-broadcaster, ...)
│ │ ├── models/ # SQLAlchemy models
│ │ ├── services/ # Business logic
│ │ ├── llm/ # LLM provider abstraction
│ │ └── schemas/ # Marshmallow schemas
│ ├── frontend/ # React + Vite + Tailwind UI
│ ├── test_agent/ # LangGraph test agent for evaluation
│ ├── scripts/ # Seed scripts (admin, security tests, eval suites)
│ └── migrations/ # Alembic migrations
│
├── mesh/ # Data plane — Python sidecar
│ ├── runtime/sidecar/ # Sidecar with interceptor pipeline
│ ├── runtime/gateway/ # External A2A ingress gateway
│ └── examples/ # Agent A & B example agents
│
├── demo/mortgage/ # Mortgage origination demo
│ ├── agents/ # Customer, KYC/Credit, Core Banking, Compliance
│ ├── frontend/ # Demo React frontend
│ ├── mcp_servers/ # MCP tool implementations
│ └── stubs/ # Mock banking APIs
│
├── k8s/ # Kubernetes deployment
│ ├── charts/recursant/ # Helm chart
│ ├── webhook/ # Sidecar injection webhook
│ └── scripts/ # Cluster lifecycle scripts
│
├── sdk/ # Python SDK + CLI for agent developers
├── scripts/ # Top-level install / quickstart / teardown scripts
├── ARCHITECTURE.md # System architecture deep-dive
├── FEATURES.md # Capability catalog with code references
├── INSTALL.md # Detailed installation guide
├── CONTRIBUTING.md # How to contribute
└── AUTHOR.md # About the author
Documentation
| Document | Purpose |
|---|---|
README.md |
This file |
ARCHITECTURE.md |
Two-plane architecture, sidecar internals, observability pipeline |
FEATURES.md |
Feature-by-feature catalog with code references |
INSTALL.md |
Full install guide (prerequisites, env, alternatives) |
CONTRIBUTING.md |
How to file issues and submit PRs |
AUTHOR.md |
About the author |
sdk/README.md |
Python SDK and CLI for agent developers |
Useful commands
make k8s-all # Full bring-up: cluster + build + deploy + smoke test make k8s-test # Run all integration tests make k8s-status # Pod and service status make k8s-logs # Tail registry + webhook logs make k8s-port-forward # Forward registry, frontend, mortgage demo to localhost make k8s-down # Tear down the Kind cluster
Run make help for the full list (Docker Compose, multi-cluster, individual
test suites, etc.).
Tech stack
- Backend: Python 3.11+, Flask, SQLAlchemy, Alembic, Marshmallow
- Frontend: React 18, Vite, Tailwind CSS, D3 (visualizations)
- Storage: PostgreSQL (with pgvector), Redis, Weaviate
- Streaming: Apache Kafka (KRaft mode, no ZooKeeper)
- Mesh: A2A protocol (
a2a-sdk1.0+) over mTLS, JSON-RPC 2.0 - Observability: OpenTelemetry, Socket.IO (live updates), Prometheus-compatible metrics
- Deploy: Helm 3, Kubernetes 1.27+, Calico CNI (NetworkPolicy enforcement)
License
MIT — use, fork, and adapt freely. Attribution appreciated.
Status
Recursant is an active project. The architecture is stable; APIs may evolve
before a 1.0 release. Issues and PRs welcome — see
CONTRIBUTING.md.