Morgana

Index

• 01Architecture Overview3
• 02Reference Channels4
• 03Building Your Agents with Alembic5
• 04Extension Points6
• 05Security Model7
• 06Configuration Reference8
• 07Agent-to-Agent Configuration9
• 08Docker Deployment10
• 09Observability (OpenTelemetry)11
• 10Quick Reference12

Architecture Overview

Morgana is a conversational AI framework built on a multi-agent, intent-driven architecture. It is multi-channel by design: the backend intelligence (Morgana) is decoupled from the channels users actually reach it through and ships with three reference channels out-of-the-box — Cauldron (HTML / Blazor Server, rich UI over SignalR), Grimoire (TTY / Spectre.Console, rich CLI over webhook) and Rune (TTY / Spectre.Console, poor-but-honest CLI over webhook). Every channel advertises its capability budget at conversation start, Morgana adapts its outbound expressivity accordingly and each channel authenticates with its own JWT issuer.

Morgana reimagines conversational AI through 4 foundational pillars that work in harmony to deliver an orchestration framework that is powerful yet remarkably simple to configure.

System Topology

Reference Channels

Morgana ships with three reference channels out-of-the-box, chosen to populate the channel × capability matrix so the framework's multi-channel design is demonstrable without any extra work: a rich renderer in two different surfaces (HTML and TTY) plus a deliberately poor one that exercises the degradation path.

Cauldron — HTML / Blazor Server (rich)

Cauldron is a Blazor Server application providing a rich, real-time chat interface with streaming responses, quick replies, rich cards and animated feedback. It communicates with Morgana over authenticated SignalR and REST (deliveryMode=signalr), with all capability flags on. It can be depicted as the official Morgana's home.

Grimoire — TTY / Spectre.Console (rich)

Grimoire is the textual Cauldron: a Kestrel-hosted console app with a Spectre.Console Live UI that renders Morgana's full expressive surface inside the terminal — streaming responses, markdown, rich cards and quick replies, all capability flags on (MaxMessageLength=null). It uses the same webhook delivery mode (deliveryMode=webhook) as Rune, proving the framework adapts on the capability profile, not the transport. Content arrives intact and is “Spectrized” locally: markdown via a Markdig→Spectre renderer, rich cards mapped to bordered boxes, quick replies into an inline arrow-key selector.

Rune — TTY / Spectre.Console (poor)

Rune is a minimal command-line channel: a Kestrel-hosted console app with a Spectre.Console Live UI (sticky header, streaming-free rendering), exercising the webhook delivery mode (deliveryMode=webhook) with lowest capability profile (all rich features off, MaxMessageLength=500). It is the contract surface MorganaChannelAdapter is supposed to degrade toward — a working proof that the channel abstraction holds, not just a demo.

Building Your Agents with Alembic

Agents can still be authored entirely by hand—agents.json and C# against the Morgana.AI NuGet package. But the preferred path is now Alembic, Morgana's authoring workbench: an AI-conducted interview that distills a new domain from scratch, or extends an existing one, into intents, agent prose, tool contracts and working C#—ready to be compiled into a Morgana plugin.

Extension Points

Every behavioural concern in Morgana is independently overridable via Dependency Injection. The default implementations ship as sensible baselines—replace any of them without touching a single line of framework code.

Security Model

Morgana implements a defence-in-depth strategy with security at every layer. The architecture is designed so that infrastructure-level concerns (TLS, vault, WAF) remain the deployer's responsibility, while the product guarantees application-level protection.

Authentication Flow

Morgana uses a per-issuer trust model: each channel onboards with its own { Name, SymmetricKey } entry in Morgana:Authentication:Issuers[], so leaking one channel's key does not compromise the others. The same trust model covers peer consultation: an installation whose agents consult each other signs that traffic under an issuer named morgana, declared exactly like a channel. A missing, blank or still-placeholder key there is startup-fatal — without it a colleague resolves to nothing and the topology fails silently on the first conversation instead of at boot. Consulting another installation signs with the key that installation issued to this caller, held on its Morgana:AgentToAgent:OutboundSystems[] entry, so one such key opens nothing else. An installation with peer consultation enabled publishes every agent it holds, not only the ones its own agents consult: what it offers is what it can answer, so an agent modelled here is reachable by anything that speaks A2A — a sibling desk, another Morgana, an orchestrator this installation knows nothing about. The gate is the issuer and its declared reach, never the topology: publication stays whole and what narrows is admission. A caller proves who it is under Issuers[] and reaches only what its Morgana:AgentToAgent:InboundSystems[] entry allows — an entry naming Agents holding it to those, an entry naming none admitting it to all — which is how one company's several installations let each other reach only the desks that concern them. An agent that must not be answerable by a given caller is kept from it by that caller's scope, never by declining to publish it. A caller is a channel or a colleague, never both: Type is mandatory on every issuer and decides which door its key opens, because behind the A2A door a request reaches an agent's actor with none of the guard, classifier, rate limit and dust budget a channel's own path goes through. That door has ceilings of its own: an inbound system writes the name of the conversation it is served on, so how many it may open in a sliding hour is declared on its InboundSystems[] entry. What one exchange may then cost is the ordinary per-conversation budget. The A2A JSON-RPC endpoints carry the same fail-closed gate as the REST API; only the well-known agent card stays open, because discovery is what tells a caller how to authenticate — and it is now that card which says so literally: it declares the bearer scheme it requires and, through a published extension, the issuer and audience a caller must mint its token under, so the calling side configures a secret and nothing else. The IAuthenticationService extension point also allows deployers to replace JWT with any strategy (API keys, mTLS, OAuth with external IdP) without modifying the application.

Configuration Reference

Morgana and its reference channels all follow the standard ASP.NET configuration hierarchy: appsettings.json → environment variables → User Secrets. In Docker, environment variables in docker-compose.yml override everything.

Morgana (Backend)

Cauldron (HTML channel)

Grimoire (TTY rich channel)

Rune (TTY channel)

Agent-to-Agent Configuration

Peer consultation is configured in three shapes. Which one a deployment is in follows entirely from what its plugins declare with [ConsultsAgent] plus what Morgana:AgentToAgent says. Two rules run through all of them. Identity and reach are separate questions: Issuers[] answers who may knock, InboundSystems[] how far a knocker reaches and neither implies the other. And this installation never declares its own address — a published card names it from whatever Kestrel bound, so a URL is configured only for somebody else.

1 — Off

Nothing is stood up: no hosted agent, no A2A server, no route, no card. Agents never see the colleagues they declare and read not one extra token of prompt, so a deployment here is the deployment it was before any of this existed. [ConsultsAgent] attributes stay in the code and are simply not honoured. No morgana issuer is required.

2 — On, colleagues of this installation only

The ring is raised whole: every agent this installation holds is published, whether or not a sibling consults it. A local consultation leaves over HTTP signed under the morgana issuer and knocks back at this installation's own A2A door, which is why that issuer is needed at both ends. All three pieces below are checked at startup and a missing one is fatal — a topology that validates and then fails silently on the first conversation is exactly what those checks exist to prevent.

The morgana entry carries neither Agents nor MaxConversationsPerHour. Startup refuses both. Which colleagues an agent here may consult already has one author, [ConsultsAgent]; and a colleague of ours opens no conversation, it joins the one the user is already having.

3 — On, colleagues here and at another installation

The two directions are independent and neither implies the other. Outbound is what this side must bring to consult a partner: an entry naming that partner, its address and the key it issued to this caller. No Issuers[] entry is needed for a system this installation only calls. Inbound is a partner calling us. That needs both — an Issuers[] entry typed system carrying the key we issued to them, plus an InboundSystems[] entry saying how far it reaches and how often it may come back.

What each shape requires

A pure supplier — publishing its desks for a partner while its own agents consult nobody here — is the one shape needing no morgana entry at all: nothing of it ever knocks at its own door.

Docker Deployment

Morgana ships with a ready-to-use docker-compose.yml defining Morgana, Cauldron, Grimoire and Rune on a dedicated bridge network with persistent SQLite volume. docker compose up starts Morgana + Cauldron; Grimoire and Rune are TUIs that need their own terminal, so each is launched interactively on demand in a separate shell (and only one TTY channel can own stdin/stdout at a time).

Required Secrets (.env)

Observability (OpenTelemetry)

Morgana provides end-to-end distributed tracing across the entire conversation pipeline. Traces are structured to be meaningful both to IT operators (latencies, TTFT, errors) and non-technical stakeholders (intent, agent name, response preview).

Span Architecture

Exporter Configuration

Compatible with Jaeger, Grafana Tempo, Azure Monitor, Datadog and any OTLP-compliant backend.

Quick Reference