Fgentic Architecture & Vision (formerly SPEC §1–§3, §11)¶
Retired root
SPEC.mdlives on as topic docs underdocs/— the§Nnumbering is preserved so existing references (issues, ADRs) still resolve. Positioning is sovereignty-first (self-hosted, per-cluster model choice — see design-decisions.md D16) with federation as the destination (federation.md).
1. Vision & Goals¶
- What Fgentic is. A sovereignty-first, open-source, self-hostable agent-collaboration platform: humans and AI agents co-inhabit Matrix rooms;
@mentiondelegates a task over A2A to an agent hosted on kagent, governed by agentgateway — every critical collaboration layer an open protocol or swappable OSS component, deployable out of the box on any conformant Kubernetes, with the model backend a per-cluster choice (D16). The differentiating destination is federation: organizations federate, so agents and humans from different companies collaborate in shared rooms across org boundaries without proprietary SaaS in the core room/delegation loop. Optional stock Element X background notification is a named exception: the production notification decision accepts Element's hosted gateway plus APNs/FCM as an external metadata boundary. - Why it matters. The closed platforms (Microsoft Entra Agent ID + Teams, Google's agent ecosystem, Slack AI) all shipped the same @mentionable-agent-in-channel UX — tenant-anchored and vendor-owned, every one. Large organizations (public sector, regulated industries, EU digital-sovereignty buyers) want the capability without the anchor: self-hosted, auditable, open-protocol, with a credible exit at every layer — and they struggle to even specify it. No open, production-ready alternative for cross-organization agent collaboration exists in mid-2026 either (verified: AGNTCY, NANDA, ANP are all pre-production; the A2A registry is a roadmap item). Matrix federation is the only battle-tested cross-org messaging federation in production (Germany's TI-Messenger: 150k+ healthcare orgs; NATO NI2CE; Sweden's public sector; France's Tchap; the European Commission piloting Matrix in 2026). Fgentic composes that proven fabric with the emerging agent standards (A2A, MCP) — a genuinely unoccupied niche: no other Matrix↔A2A appservice bridge exists (closest prior art: MindRoom, Beeper ai-bridge, baibot — all direct-LLM bots, none A2A).
- Adoption target (§1.3). Fgentic is independent today. Its primary foundation path is LF AI & Data Sandbox, whose published lifecycle provides an explicit early-stage route for AI and data infrastructure. CNCF Sandbox is a conditional second-credential review in 2028, only after LF AI & Data acceptance and confirmation that the foundations' asset-custody requirements are compatible; it is not a dual-hosting promise or current gate. AAIF Growth remains a later option only when its published acceptance criteria for wide production use, a TC sponsor, sustained participation, and a credible maintainership-growth plan can be evidenced. The dated evidence and claim limits are in the CNCF dossier.
- Non-goals. Not an agent framework (kagent owns that), not a gateway (agentgateway owns that), not a Matrix distribution (ESS/others own that). Fgentic is the composition: the bridge, the manifests, the federation profile, the runbooks, and the reference deployment (
fgentic.fmind.ai).
Adoption does not require an immediate replacement of an existing human chat system. The incumbent-chat coexistence guide separates agent-rooms-only deployment, selectively qualified interop, and full migration; its default is to run purpose-scoped Matrix agent rooms beside the incumbent.
1.1 Naming (decided 2026-07-10)¶
The product name is Fgentic ("federated + agentic" — the name literally encodes the value proposition); the repo/artifact slug is fgentic. The reference deployment lives at fgentic.fmind.ai (the Matrix server_name; hosts chat./matrix./auth.fgentic.fmind.ai); its GCP project is deployment-specific (set in terraform.tfvars and clusters/gcp/platform-settings.yaml, never hardcoded in shared manifests). A vendor-neutral name is also a foundation-donation prerequisite (trademark transfers to LF).
2. Architecture: current, verified state¶
The layering established by the original research record (PLAN.md, retired — see git history) stands. This matrix is the source of truth:
| Layer | Component | Verified state (2026-07-23) | Load-bearing facts |
|---|---|---|---|
| Fabric | Matrix spec | v1.19; room version 12 default since v1.16 | Room v12 is mandatory for federation (Project Hydra state-reset fix, CVE-2025-49090 class). MSC4186 (sliding sync) is de-facto standard for Element X, accepted by the SCT July 2026. |
| Homeserver | Synapse + MAS via ESS Community | chart 26.7.2 (upgraded from 26.7.0 via #1608 for the Synapse v1.157.2 security release; values revalidated against the 26.7.2 chart schema — external-Postgres password:{secret,secretKey}, appservice {secret,secretKey} entries, well-known additions as JSON strings) |
The homeserver decision + alternatives + switch triggers: §10.3. The bridge's API surface (registration, as_token, user_id masquerading) is stable-spec and MAS-proof (MSC3861 does not touch appservice tokens) — the platform is homeserver-portable by construction. |
| Delegation | A2A protocol | spec v1.0.1 (May 2026; AgentCard/service version 1.0): mTLS, OAuth2/OIDC security schemes, Signed AgentCards (JWS) |
v1.0's signed cards + mTLS are load-bearing for the federation design (§8). A2A is a standalone Linux Foundation project (not AAIF). |
| A2A SDK | a2a-go/v2 |
Bridge pins v2.4.0 | kagent negotiates wire version via header, defaulting to legacy 0.3 JSON-RPC when absent; that default is slated to change around kagent 0.11 (TODO(0.11.0) in kagent's a2a_version.go) — pinned by the contract test planned in §12. |
| Agents | kagent | v0.9.11 (CNCF Sandbox) | Requires PostgreSQL (bundled chart DB is dev-only) — provisioned as the kagent DB in CNPG. A2A contextId maps 1:1 to a persistent kagent session (SessionID = task.ContextID), which validates the bridge's threading design. Its A2A endpoint is unauthenticated by default (§7). |
| Data plane | agentgateway | v1.3.1 (Apache-2.0, hosted by AAIF since June 2026) | On the A2A hop it proxies + rewrites AgentCards + logs a2a.method only — no A2A response inspection, no per-agent RBAC (per-path CEL authorization can approximate it). Issue #39's claimed GHSA-jwm2-83f3-52xc currently has no GitHub advisory record, and v1.3.1 remains the newest stable release; do not replace it with the v1.4 alpha. A CI audit now rejects every cross-namespace backend without an exact ReferenceGrant. |
| Bridge | matrix-a2a-bridge (this repo) | mautrix/go v0.29.0 (MPL-2.0, not AGPL) + a2a-go v2.4.0; unit-tested, race-clean | Design decisions D1–D15 (§4) are implemented; behavior specified in §5–§6. Configured external-appservice namespace prefixes are classified separately and denied unless the full bridged MXID is explicitly allowed. |
| Interop | mautrix Slack + Telegram | Optional v0.2606.0 bridgev2 appservices, each pinned by multi-arch image digest and disabled in every default cluster overlay |
One reusable restricted Helm runtime; one appservice namespace, SOPS credential set, Postgres role/database, Matrix registration component, and provider gate per network. Rendering/runtime-schema tests are local evidence; provider-owner and bidirectional acceptance remain external. See interop.md. |
| State | CloudNativePG + pgvector | operator chart 0.29.0; PostgreSQL 17.10 image with pgvector 0.8.5; WAL archiving + nightly base backups to GCS via Workload Identity | instances: 1 for the reference; 3 for production. Database-per-service: synapse (C collation), mas, bridge, kagent, keycloak, plus one role/database per enabled external bridge. The knowledge database composes the same cluster with separate owner/ingestion/retrieval roles and the fixed vector(1024) grounding contract; its disabled-by-default Docling batch adds no stateful workload. |
| Delivery | Flux v2 + GitHub Actions | Apps wrapped in Flux Kustomizations; CI (ci.yml) runs the mise gates; CD (cd.yml) builds → scans → signs → pins digests |
HelmRelease.dependsOn only resolves HelmReleases — apps depend on infra via their wrapping Kustomization (D1). Images deploy by immutable digest, never latest. |
| Observability | Prometheus + OTel + Jaeger | kube-prometheus-stack 87.17.0, OTel Collector chart 0.165.0 (collector 0.156.0), and Jaeger chart 4.11.1 (Jaeger 2.19.0) are pinned; Grafana is the only public observability UI | Metrics are live-verified. The trace backend is declarative and isolated behind Grafana; bridge, kagent, and agentgateway instrumentation must still prove full mention→LLM trace continuity before that path is called complete. |
2.1 Runtime-independence proof¶
mise run test:integration continuously proves that kagent is an implementation choice rather than a bridge dependency. The disposable kind cluster installs no kagent namespace, CRD, controller, or Agent; instead, a deterministic server built directly on the official a2a-go SDK runs as the only workload in a separate restricted namespace. Its standalone non-root distroless image contains no bridge binary, and a default-deny NetworkPolicy admits the bridge integration namespace only. The bridge maps the server through the same exact url: and pinned Signed AgentCard contract used for partner agents. The real Synapse appservice path verifies reply attribution, the token-budget extension, per-sender admission, success/rate-limit metrics, and fail-closed card tampering. This proof deliberately remains a CI fixture rather than an always-on reference workload, keeping deployed clusters smaller while guarding runtime swappability on every bridge change.
3. Core Data Flow¶
The @mention → A2A → reply flow stands, amended by the async delegation model (bridge.md §6): the bridge ACKs the Matrix transaction immediately, dispatches the A2A call on a bounded per-room-ordered worker pool, and posts/edits the ghost reply when the task completes — the appservice transaction queue is never blocked and LLM concurrency is always bounded.
11. Terraform / GCP Reference (prepared; apply gated by issue #59)¶
infra/terraform/ now implements: remote state (versioned GCS bucket via the one-time bootstrap/ module + backend "gcs"), private nodes + Cloud NAT (nodes have no public IPs; the control-plane endpoint stays public but CIDR-allowlisted, never 0.0.0.0/0), the named static ingress address (pinned by Traefik — D2), the CNPG backups bucket + keyless Workload-Identity GSA, a regional toggle (zonal for the disposable reference, regional for production SLA), optional Cloud DNS A records (manage_dns + dns_zone_name), a weekly maintenance window, pd-balanced node disks, explicit legacy-metadata-endpoint disable, Workload Identity, Dataplane V2 (NetworkPolicy enforcement), and shielded nodes with a least-privilege node SA.
Deliberately not defaulted on (the "regulated-industry" tier, documented only): CMEK/etcd encryption, Binary Authorization, Backup for GKE. The opt-in Vertex profile uses a direct Workload Identity grant: Terraform gives only agentgateway-system/agentgateway-proxy the Vertex AI User role, with no Google service account, impersonation, annotation, or key. The configuration is offline-tested; live acceptance remains part of spend-gated #59.
Bootstrap order: apply bootstrap/ first (local state, creates the versioned state bucket), then terraform init -backend-config="bucket=<state_bucket_name>" -migrate-state in the main module — the bucket is deployment-specific and never committed. Bucket names are globally unique: set them via the bootstrap state_bucket_name variable and pg_backups_bucket_name (which must match infra/postgres/cluster.yaml); no personal project is hardcoded.