Inbound migration from a tenant-anchored agent platform

This guide treats migration as a controlled re-establishment of identity, authorization, data, and operating evidence. It does not assume that an incumbent tenant, role, session, connector, model, or audit record can be imported as trusted state.

Start with the adopter decision brief and the relevant persona guide. Use the incumbent-chat coexistence guide when the human chat system will remain in place; moving agent work does not require migrating every conversation.

1. Migration boundary

Fgentic is the owned Matrix-to-A2A bridge, governance wiring, federation profile, manifests, and runbooks. It composes the independently operated systems that run Agents, route model and MCP traffic, store service and grounding data, and provide the Matrix fabric. The architecture non-goals and exit strategy are the authoritative boundaries.

Do not translate incumbent feature names literally. Inventory the capability, authority, data, side effects, and evidence behind each feature, then map those properties to a reviewed target boundary.

2. Concept map

Incumbent capability	Fgentic equivalent	Repository evidence	What must be re-established
Tenant and tenant-scoped principals	One operator-owned Matrix homeserver and stable server_name establish local full MXIDs; explicitly approved homeservers form a federated organization boundary.	Identity and SSO, federation §8, infra/federation/	Stable account mapping, room membership, full-MXID sender policy, lifecycle ownership, and partner trust. A tenant principal is not imported as authority.
Built-in agent chat	Purpose-scoped Matrix rooms provide the human collaboration surface; the Go appservice bridge turns an allowed @mention into A2A and returns an m.notice.	Bridge §5–§6, apps/matrix-a2a-bridge/, per-room encryption decision	Room purpose, classification, membership, plaintext notice, Agent ghost mapping, rate limits, and human review of replies.
Managed agent runtime	A kagent Agent custom resource declares prompt, model reference, tools, A2A skills, runtime identity, and resources; the bridge depends on the A2A contract rather than kagent internals.	infra/kagent/agent-zoo.yaml, runtime-independence proof	Agent source, prompt, tool authority, service account, resource bounds, tests, and new runtime sessions. Incumbent session identifiers are not portable.
Proprietary connectors and plug-ins	Reviewed MCP servers sit behind agentgateway's authenticated and pinned MCP route. Tool schemas describe calls but do not grant authority.	Governed MCP egress, mcp-surface.pin.json, infra/agentgateway/	Connector-owned credentials, source-system authorization, tool allowlists, side-effect approval, rate limits, negative tests, and data-owner acceptance.
Hosted knowledge or retrieval layer	CloudNativePG composes a knowledge database with pgvector, scoped roles, ACL metadata, and a fixed schema. Permission-aware retrieval remains separate implementation work and is not implied by the schema alone.	Grounding contract, knowledge-schema-v1.yaml, D18 status	Corpus export, parser/chunker behavior, source ACLs, embeddings, citations, retention, freshness, deletion, retrieval enforcement, and answer-quality acceptance.
Managed model endpoint	Agents use the in-cluster agentgateway route; one selected profile sends inference to a self-hosted runtime or an approved API boundary. The credential terminates at agentgateway and never enters an Agent.	Model profiles, infra/models/, infra/agentgateway/, D16	Model capability, quality, safety, latency, capacity, residency, provider/account controls, token metrics, spend limits, and credentials. Model names are not parity.
Tenant roles and agent permissions	Matrix room membership plus per-Agent bridge policy authorizes human invocation; workload credentials and NetworkPolicies protect local A2A/MCP paths; a direct cross-org A2A listener validates the partner machine identity.	D6, security §7.2–§7.4, federation §8.3	Explicit target-side grants. Do not infer a bridge, gateway, tool, document, or partner permission from an incumbent role or an identity claim alone.
Managed audit, quotas, and operations	The bridge emits content-free delegation evidence and bounds invocations; agentgateway provides workload/model metrics; Flux reconciles reviewed configuration. Each store has its own retention and identity limits.	Attribution audit, observability §9, D7, clusters/base/	Evidence retention, access, correlation limits, alert ownership, quotas, recovery objectives, incident response, and target-environment acceptance.

The model row's current concrete targets are self-hosted vLLM and the reference Vertex API profile. Naming those composed targets does not imply capability or quality parity with the incumbent model.

Own vs compose. Fgentic owns the bridge/governance/federation seam and the reference boundary tests. It does not re-implement an incumbent runtime, connector catalog, retrieval engine, guardrail service, model, database, homeserver, or gateway. kagent, MCP servers, agentgateway, CloudNativePG/pgvector, the selected model backend, and Matrix remain composed systems with their own migration and support contracts.

3. Rebuild identity and authorization

Authentication proves control of a target account; it does not preserve authority from the old tenant. Build a target authorization register before parallel operation:

D20 accepts exact IdP-group-to-room bindings reconciled by a scoped access-manager identity, but its implementation gates remain open. Until that reconciler and bridge hardening land, treat IdP group claims as input to a manually reviewed migration register—not as live runtime authorization—and retain current room membership plus bridge policy as the enforced boundary.

1. Assign each person a stable, administrator-controlled Matrix localpart under the target server_name. Record the resulting complete MXID and test new-account plus existing-account login. Do not derive authority from a display name, mutable email, or localpart alone.
2. Create purpose-scoped rooms and approve their membership, data classification, history visibility, retention, and federation posture. Choose the encryption posture per room; the current bridge refuses encrypted events until ADR 0026's staged crypto participation lands.
3. Map each local ghost to exactly one reviewed Agent. In agents.yaml, allowedServers contains homeserver names and allowedSenders contains anchored globs over full MXIDs. A foreign look-alike ghost never resolves to a local target (D6).
4. Treat the bridge's X-User-Id as asserted attribution only. kagent does not authenticate that end user; the local path instead relies on the bridge allowlist, the bridge workload credential at agentgateway, and enforced NetworkPolicies (D11).
5. For direct cross-org A2A, admit only the exact route under a verified Signed AgentCard and the configured JWT or mTLS policy. The current reference JWT path authorizes a verified machine client and reserves tokens per azp; it does not authenticate the Matrix human or turn reservations into measured usage.
6. Re-authorize every MCP server, source system, grounding corpus, model profile, and write side effect at its own enforcement point. A copied role name, group claim, AgentCard description, or MCP annotation is not a grant.

Permission-aware retrieval requires the separate typed identity-and-room-audience projection in D18. Until its tracked implementation is complete, do not present ordinary X-User-Id forwarding or the checked-in knowledge schema as document-level authorization.

4. Staged migration and rollback

Stage	Change	Acceptance before advancing	Rollback boundary
0. Inventory and freeze the contract	Record incumbent Agents, prompts, tools, connectors, data stores, users, groups, rooms, model dependencies, side effects, quotas, audit/retention, owners, and export interfaces. Classify what moves, is rebuilt, stays referenced, or is intentionally abandoned.	Every item has a target owner, source-of-truth decision, data class, checksum/count where meaningful, authorization mapping, acceptance test, and deletion/retention decision.	No runtime change. Correct the inventory rather than forcing an unsupported translation.
1. Build an isolated landing zone	Recreate identities, one low-risk Agent, its minimum MCP/data surface, one model profile, one purpose-scoped local room, policy, metrics, and recovery configuration from reviewed Git. Use synthetic or approved non-sensitive fixtures first.	Static gates pass; allowed and denied identities, tools, model paths, and NetworkPolicy bypasses are tested on the owned target environment. Evidence names the exact revision and overlay.	Delete the isolated target resources and revoke their new credentials. The incumbent remains authoritative.
2. Parallel-run one Agent	Invite a small evaluation cohort and route one read-only or independently reversible workflow to Fgentic. Keep the incumbent route available but prevent both systems from performing the same external write. Compare task outcomes, citations, failures, latency, and cost.	The named cohort accepts quality and UX; security/privacy owners accept the exact data path; operators can diagnose, restore, rotate, and disable the route without the incumbent console.	Remove the target Agent mapping and room access, revoke target credentials, and return users to the unchanged incumbent workflow. Do not copy contextId, task IDs, or framework sessions between runtimes.
3. Cut over per room or organization	Freeze policy changes, capture the final delta, enable the approved Matrix room/Agent route, move only the in-scope participants and source access, and make the incumbent route read-only or unavailable for that scope. Keep one accountable writer and reconciler.	Full-MXID positive/negative authorization, model/tool/data behavior, quotas, audit joins, failure notices, backup/restore, and rollback timing pass for the exact room and Agent.	Before the rollback deadline, disable new Fgentic invocation, drain or classify accepted tasks, revoke the target route, and restore the preserved incumbent writer. Reconcile any external side effects explicitly.
4. Add a partner organization	Complete the bilateral federation onboarding, then enable only the approved room-v12 Matrix federation and/or exact public A2A route. Apply closed-federation ACLs, callback policy, classification bounds, partner identity, quotas, and offboarding.	Both sides prove allow/deny behavior, attribution limits, Signed AgentCard verification, machine authorization, quota reservation, policy reload, incident contacts, and data handling.	Deny new federation and A2A traffic and follow partner offboarding. Already replicated Matrix history cannot be reliably retracted; rollback stops new disclosure rather than erasing copies.
5. Decommission the incumbent scope	After the rollback window, stop new sessions, drain or classify outstanding work, export required evidence/data, revoke users/apps/tokens/routes, remove writers, expire retained copies under policy, and update support plus incident ownership.	No target dependency still points to the incumbent; deletion/retention exceptions are owned; target day-2 checks are operational; stakeholders sign the scoped acceptance record.	Decommission is the one-way boundary. Restore only from an explicitly retained, tested source under a new migration decision; do not silently reactivate stale identities, credentials, policies, or data.

Cut over one room or organization at a time. A successful answer is not authorization, fidelity, recovery, capacity, or decommission evidence. Preserve the source until the agreed rollback window closes, but do not run two active writers against the same side effect.

5. Cutover record

For each migrated scope, retain:

1. source and target inventories, owners, versions, revisions, and effective configuration;
2. identity mapping by complete principal, with explicit grants and revocations at every enforcement point;
3. data counts/checksums, classification, residency, retention, restore/import result, and abandoned-data decision;
4. positive and negative tests for rooms, senders, Agents, tools, documents, model paths, federation peers, quotas, and failure handling;
5. parallel-run comparison criteria and observed results, without invented parity, performance, cost, or compliance claims;
6. final-writer freeze, delta capture, cutover time, rollback deadline, outstanding tasks, and side-effect reconciliation;
7. revoked incumbent credentials/routes/apps, retained copies and expiry owners, and the target incident/support escalation map.

After cutover, use the Day-2 Operations Handbook with Production Installation, Observability, Exit Strategy, the security and federation runbooks, and the repository skills. The handbook is repository source; its publication and every target-cluster drill remain separate evidence gates.

Publication status

This file is repository source, not proof of publication. Delivery through the planned documentation site remains tracked by #72.