# Agent Registry & Prompt Versioning Roadmap

> **Purpose:** Create a system of record for agents, prompts, tools, versions,
> rollout states, and release governance.
>
> **Primary Surfaces:** `services/platform-service/`, `services/mcp-server/`
>
> **Status:** Planned
>
> **Estimated Effort:** 2-3 weeks

---

## Why This Is Missing

The repo has MCP tools and A2A pipelines, but it does not have a persistent registry
for the definitions that power them. Without that, agent behavior is embedded in code
and docs rather than treated as versioned platform data.

---

## Recommended Stack

- **PostgreSQL** for metadata and version history
- **Blob storage or Git-backed artifacts** for prompt files and larger assets
- **OpenTelemetry** for linking versions to production runs

### Repo-Fit Alternative

- Cosmos-backed registry module in `platform-service`
- Prompt artifacts stored in blob storage
- MCP server resolves active versions from `platform-service`

### Default Decision For This Repo

- Put the system of record in `platform-service`
- Store large prompt assets in blob storage
- Require `agentVersion` and `promptVersion` on every durable run

---

## Dependencies

- Agent Runtime & Orchestration
- AI Governance & Evaluation

---

## V1 Non-Goals

- Non-technical prompt editing UI
- Marketplace-style public agent publishing
- Full GitOps-only release flow

---

## Phase 1 - Core Registry

- [ ] Create modules:
  - [ ] `agent-registry`
  - [ ] `prompt-registry`
  - [ ] `tool-bundles`
- [ ] Add entities:
  - [ ] `AgentDefinition`
  - [ ] `AgentVersion`
  - [ ] `PromptTemplate`
  - [ ] `PromptVersion`
  - [ ] `ToolBundle`
  - [ ] `ReleaseChannel`
- [ ] Track:
  - [ ] owner
  - [ ] changelog
  - [ ] status: `draft`, `staged`, `active`, `deprecated`, `archived`
  - [ ] compatibility constraints

**Acceptance Criteria**

- Every production agent has a durable version record
- Prompt changes are diffable and auditable

---

## Phase 2 - Rollouts & Safety

- [ ] Add staged rollouts by product, org, workspace, or cohort
- [ ] Add allowlists and freeze controls
- [ ] Add prompt approval requirement for sensitive agents
- [ ] Add rollback support
- [ ] Link agent versions to eval results and incidents

---

## Phase 3 - Runtime Integration

- [ ] `mcp-server` loads active definitions from registry rather than code-only defaults
- [ ] `agent-runs` store `agentVersion` and `promptVersion`
- [ ] support replay against older versions for regression analysis

---

## Tech Stack Options

| Option                           | Pros                       | Cons                           | Fit                         |
| -------------------------------- | -------------------------- | ------------------------------ | --------------------------- |
| PostgreSQL + blob storage        | Strong relational history  | New datastore                  | Best long-term              |
| Git as source of truth + sync DB | Great developer ergonomics | Dual-source complexity         | Good for prompt-heavy teams |
| Cosmos + blob storage            | Consistent with repo       | Version queries less ergonomic | Good short-term             |

---

## Risks

- Code-only prompt management creates invisible production drift
- Without version pinning, incident replay and audit are weak
- Registry without rollout controls is just a metadata catalog
