Skip to main content

A11 - Governance Registry

GroupTechnologyStatusServiceRoadmap phaseContracts
A - Governance, identity and securityPostgreSQL + APIto developgovernance3agent-manifest, model-manifest, tool-manifest

Back to index - Français

Role and responsibilities​

Inventory of agents, models, tools with owners, risk level and lifecycle status.

Data model​

Tables (schema eai, every tenant table carries tenant_id uuid NOT NULL with an RLS policy on current_setting('app.tenant_id', true)::uuid): eai.agents, eai.llm_models, eai.tools, eai.audit_events.

API endpoints​

  • GET /v1/governance/registry
GET /v1/governance/registry HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: en
Content-Type: application/json

{
  "agents": [
    {"kind": "agent", "id": "5d5e3e63-b0d1-4c5c-a918-4c6417cdc9d5", "name": "invoice-assistant", "version": "1.2.0", "owner": "team-finance@acme.example", "status": "active", "risk_level": "high", "scope": "tenant", "updated_at": "2026-10-30T01:31:24.268224Z"}
  ],
  "models": [
    {"kind": "model", "id": "e5acbd64-0e0a-4497-89e9-f9c2cfd8bc60", "name": "bedrock-claude-sonnet-4-eu", "version": "1.0.0", "owner": "platform", "status": "approved", "risk_level": null, "scope": "platform", "updated_at": "2026-10-29T16:46:11.615637Z"}
  ],
  "tools": [],
  "skills": [],
  "plugins": [],
  "connectors": [],
  "summary": {
    "agent": {"total": 5, "by_status": {"active": 5}, "by_risk": {"high": 5}, "without_owner": 0},
    "model": {"total": 15, "by_status": {"approved": 15}, "by_risk": {"unassessed": 15}, "without_owner": 0}
  },
  "missing_sources": 0
}

Errors use the common envelope {"error": {"code", "message", "message_i18n", "details", "request_id"}}; lists are paginated with limit and cursor.

Promotion gate​

Registry statuses only move up (approved, active) through an approved promotion, see A12 Controlled promotions: approval with separation of duties, risk gate for high risk systems, blocking evaluation suites. Retirements (restricted, deprecated, blocked, suspended, killed) are immediate and audited.

SDK usage​

Python (enterprise_ai):

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
items = client.governance.registry()

TypeScript (@enterprise-ai/sdk):

import { EnterpriseAI } from "@enterprise-ai/sdk";

const eai = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const items = await eai.governance.registry();

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var items = client.governance().registry();

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
items, err := client.Governance.Registry(ctx)

Configuration​

  • Environment: EAI_DATABASE_URL, EAI_OTEL_EXPORTER_OTLP_ENDPOINT.
  • Helm values: controlPlane.enabled, controlPlane.replicas, controlPlane.resources, controlPlane.config.

Security controls​

  • Authentication by OIDC JWT, tenant API key with scopes, or SPIFFE mTLS; tenant resolved from the credential, never from the body.
  • Authorization through OpenFGA and OPA decisions; every mutation and decision writes a hash-chained eai.audit_events row.
  • Secrets never returned by the API; TLS everywhere; Cilium network policies restrict who can reach the service.

Observability​

  • Metrics: eai_governance_registry_requests_total, eai_governance_registry_errors_total, eai_governance_registry_latency_seconds (Prometheus).
  • Traces: OpenTelemetry spans eai.governance.* with W3C traceparent propagation, AI spans forwarded to Opik.
  • Audit actions: agent.apply, model.create, tool.apply, policy.evaluate.

FinOps aspects​

Operating cost is allocated per tenant and project through labels on Usage Events and Kubernetes resource requests; no direct per-call cost.

Failure modes and resilience​

  • Stateless replicas behind the API Gateway, PostgreSQL HA for state; readiness probe GET /readyz removes unhealthy pods.
  • External system unavailable: fail closed for security decisions, explicit error code, no silent bypass.

Standalone adoption (client of a client)​

A client of a client can adopt this brick alone with the Python SDK sub-client client.governance (TS eai.governance, Java client.governance(), Go client.Governance). Minimal deployment: Control Plane API + PostgreSQL + Keycloak (or API keys), the Control Plane loads every domain of services/control-plane/src/eai/domains; the optional chart components are switched off in deploy/helm/enterprise-ai/values.yaml (vllm.enabled, qdrant.enabled, nats.enabled, workers.enabled).

Acceptance tests​

  1. A tenant cannot read or modify another tenant's resources (RLS test).
  2. Every mutation produces an audit event verifiable by GET /v1/audit/verify.
  3. Errors are returned in English and French according to Accept-Language.