Skip to main content

PRD-016 — Agentic Deployment, Versioning & Release Management

1. Objetivo​

Definir o mecanismo de versionamento, empacotamento, validação, publicação, rollout, canary e rollback de toda a plataforma Agentic Work.

O objetivo é garantir que o agente não seja atualizado como um simples conjunto de arquivos.

Uma alteração poderá envolver simultaneamente:

  • código;
  • capabilities;
  • policies;
  • knowledge;
  • semantic UI;
  • prompts;
  • modelos;
  • evaluation datasets;
  • schemas;
  • manifests.

Portanto, a unidade de deployment deverá ser um Agent Release Bundle versionado e verificável.

2. Problema

Imagine que uma nova versão da documentação altere a interpretação de:

“validade da permissão”.

Ou que uma nova capability seja publicada.

Ou que uma policy seja alterada.

Se cada componente possuir deployment independente, poderemos acabar com:

Code v42
Knowledge v101
Capabilities v17
Policies v23
UI Manifest v11
Prompt v8

sem saber se essas versões são compatíveis.

Isso cria comportamento imprevisível.

3. Princípio

Uma execução do agente deve saber exatamente qual conjunto de artefatos estava ativo quando tomou uma decisão.

Portanto:

Agent Execution
      ↓
Release Bundle
      ↓
Immutable Version

4. Agent Release Bundle

Modelo:

interface AgentReleaseBundle {
  releaseId: string;

  version: string;

  createdAt: string;

  agentVersion: string;

  knowledgeVersion: string;

  capabilityVersion: string;

  policyVersion: string;

  uiManifestVersion: string;

  promptVersion: string;

  evaluationVersion: string;

  runtimeVersion: string;

  status: ReleaseStatus;
}

5. Release ID

Exemplo:

agent-release-2026.09.01.001

ou:

1.12.0

O formato poderá ser Semantic Versioning ou outro padrão empresarial.

O importante é que seja:

  • único;
  • imutável;
  • rastreável.

6. Immutable Release

Depois de publicado:

Release 1.12.0

não poderá ser modificado.

Se houver alteração:

1.12.1

ou:

1.13.0

conforme a natureza da mudança.

7. Artifact Manifest

O release possuirá um manifest:

{
  "release": "1.12.0",
  "runtime": "8.4.1",
  "knowledge": "2026.09.01",
  "capabilities": "4.2.0",
  "policies": "3.8.0",
  "ui": "2.7.0",
  "prompts": "5.1.0",
  "evaluations": "12.0.0"
}

8. Manifest Hash

O bundle deverá possuir uma assinatura ou hash:

releaseHash

Isso permite verificar:

O artefato que está rodando é realmente aquele que foi aprovado?

9. Release Integrity

Antes do deployment:

Manifest
 ↓
Schema validation
 ↓
Dependency validation
 ↓
Signature/hash validation
 ↓
Evaluation
 ↓
Security tests
 ↓
Release approval

10. Dependency Compatibility

Exemplo:

Capability v4
requires
Policy >= v3

Se houver:

Policy v2

o release deverá ser rejeitado.

11. Semantic Versioning

Recomendação:

PATCH​

Correção sem mudança contratual.

1.4.1

MINOR​

Nova capability compatível.

1.5.0

MAJOR​

Mudança incompatível:

2.0.0

12. Capability Compatibility

Uma capability deverá declarar:

interface CapabilityVersion {
  id: string;

  version: string;

  compatibility: {
    input: string;
    output: string;
  };

  deprecated?: boolean;
}

13. Policy Compatibility

Policies também precisam ser versionadas.

Exemplo:

workPermit.updateValidity
policy v3

Uma execução iniciada usando:

policy v3

não deverá ser silenciosamente reinterpretada como:

policy v4

no meio da operação.

14. Execution Pinning

Toda execução deverá registrar:

releaseId

e permanecer associada ao release correspondente.

Exemplo:

Execution:
EXEC-123

Release:
1.12.0

Mesmo que o sistema faça deploy de:

1.13.0

a execução antiga deverá continuar referenciando:

1.12.0

15. Long-Running Tasks

Para operações longas:

Execution started
 ↓
Release 1.12.0
 ↓
Deployment 1.13.0

a execução não deve automaticamente migrar.

Deverá existir uma política explícita:

CONTINUE_OLD_RELEASE
PAUSE
MIGRATE
CANCEL

16. Release States

DRAFT
 ↓
VALIDATING
 ↓
EVALUATING
 ↓
APPROVED
 ↓
CANARY
 ↓
ACTIVE
 ↓
DEPRECATED
 ↓
RETIRED

17. Release Gate

Um release só poderá avançar se passar:

TypeScript
+
Build
+
Manifest
+
Capabilities
+
Policies
+
Security
+
Evaluation
+
Performance

18. Evaluation Gate

O PRD-014 será integrado diretamente.

Exemplo:

Intent Accuracy >= 97%
Reference Accuracy >= 97%
Capability Accuracy >= 99%
Unsafe Actions = 0

Se não atingir:

RELEASE BLOCKED

19. Performance Gate

Também poderá existir:

P95 latency regression < 10%

ou thresholds específicos por domínio.

20. Cost Gate

Uma nova versão que aumente drasticamente o custo deverá ser sinalizada.

Exemplo:

Cost/task:
$0.0012 → $0.0048

Resultado:

COST_REGRESSION

O release poderá exigir aprovação.

21. Security Gate

Qualquer regressão crítica:

unsafe action
tenant isolation failure
authorization bypass
policy bypass

deverá bloquear o release automaticamente.

22. Canary Deployment

O release será inicialmente disponibilizado para uma pequena parcela:

1%
 ↓
5%
 ↓
10%
 ↓
25%
 ↓
50%
 ↓
100%

O avanço dependerá de métricas.

23. Canary Dimensions

O canary poderá ser segmentado por:

  • tenant;
  • usuário;
  • percentual;
  • domínio;
  • capability;
  • região;
  • ambiente.

24. Canary por Tenant

Exemplo:

Tenant A → v1.13
Tenant B → v1.12
Tenant C → v1.12

Isso permite validação gradual.

25. Feature Flags

Capabilities poderão ser habilitadas independentemente:

agent.capability.workPermit.updateValidity.v2

Estados:

OFF
INTERNAL
CANARY
ENABLED

26. Capability Rollout

Uma nova capability:

workPermit.approve

poderá inicialmente ser:

registered
+
tested
+
disabled

Depois:

enabled for internal users

e somente depois:

production

27. Policy Rollout

Policies novas deverão suportar:

ACTIVE
SHADOW

No modo shadow:

Current policy → decides
New policy → evaluates only

Depois os resultados são comparados.

28. Policy Comparison

Exemplo:

Old:
ALLOW

New:
REQUIRE_CONFIRMATION

O sistema poderá mostrar:

A nova policy alteraria 3,4% das decisões.

Isso permite revisão antes da ativação.

29. Knowledge Rollout

Da mesma forma:

Knowledge v101

poderá ser testado contra:

Knowledge v100

usando o evaluation dataset.

30. Prompt Rollout

Prompts poderão ser versionados:

prompt.v12
prompt.v13

e avaliados contra o mesmo dataset.

31. Model Rollout

O mesmo:

Model A
vs
Model B

sem necessidade de modificar capabilities ou policies.

32. Rollback

Rollback deverá ser uma operação de primeira classe.

Exemplo:

v1.13
 ↓ incident
rollback
 ↓
v1.12

Sem rebuild desnecessário.

33. Automatic Rollback

Poderá ocorrer quando:

error rate > threshold
latency > threshold
unsafe action > 0
cost spike > threshold

34. Rollback Safety

Uma operação já iniciada não deve ser simplesmente interrompida sem considerar consistência.

O rollback afeta:

NEW executions

por padrão.

Executions existentes seguem a política definida anteriormente.

35. Release Diff

O sistema deverá mostrar:

Release 1.12 → 1.13

+ 4 capabilities
- 1 capability
~ 7 policies
~ 120 documents
+ 32 semantic bindings
~ prompt
~ model

36. Semantic Diff

Além do diff de arquivos:

semantic diff

Exemplo:

workPermit.validity

Before:
editable

After:
requires confirmation

Isso é muito mais importante para o comportamento do agente do que simplesmente mostrar diferenças de YAML.

37. Capability Diff

Exemplo:

ADDED
workPermit.updateValidity

CHANGED
workPermit.update

DEPRECATED
workPermit.modify

38. Policy Diff

Mostrar:

Policy:
workPermit.updateValidity

Risk:
MEDIUM → HIGH

Confirmation:
optional → required

39. Knowledge Diff

Mostrar alterações semânticas:

Added:
validity period

Changed:
maximum validity

Removed:
legacy rule

Isso poderá ser derivado do pipeline existente de documentação/knowledge.

40. UI Manifest Diff

Exemplo:

workPermit.validity

antes:

interactive = true

depois:

interactive = false

Isso poderá impactar capabilities.

O release gate deverá detectar essas incompatibilidades.

41. Breaking Change Detection

Exemplo:

Capability expects:
workPermit.validityDays

UI exposes:
workPermit.validity

Se o binding deixar de existir:

BROKEN CONTRACT

Release bloqueado.

42. Migration

Quando houver mudança incompatível:

v1
 ↓
migration
 ↓
v2

deverá existir um migration handler quando necessário.

43. Backward Compatibility

Durante rollout:

v1 client
+
v2 backend

poderá existir temporariamente.

Os contratos deverão definir explicitamente o período de compatibilidade.

44. Environment Promotion

Fluxo:

LOCAL
 ↓
CI
 ↓
TEST
 ↓
STAGING
 ↓
CANARY
 ↓
PRODUCTION

O mesmo release artifact deverá ser promovido.

Não reconstruir artefatos diferentes em cada ambiente.

45. Release Artifact Imutável

Exemplo:

agent-release-1.13.0.tar

deverá ser o mesmo artefato promovido:

staging → production

46. Configuration vs Release

Configurações externas não devem destruir a reprodutibilidade.

Distinguir:

Release configuration

de:

Runtime configuration

E registrar quais configurações relevantes estavam ativas.

47. Tenant Overrides

Se tenants puderem possuir configurações específicas:

Global Release
      +
Tenant Configuration

deverão ser registradas.

Exemplo:

Agent Release: 1.13.0
Tenant Policy Overlay: T42-v8

48. Release Observability

O PRD-015 deverá alimentar:

release version
deployment timestamp
traffic percentage
error rate
latency
cost
LLM usage
task success

49. Release Health

Dashboard:

Release 1.13.0

Traffic       10%
Success       99.2%
P95           481ms
Unsafe        0
Cost/task     +3.2%

Status:
HEALTHY

50. Release Approval

Dependendo do risco:

Low​

Automático.

Medium​

Automático se evaluation passar.

High​

Revisão humana.

Critical​

Aprovação formal obrigatória.

51. Release Risk

Risco agregado:

Code change
+
Capability change
+
Policy change
+
Knowledge change
+
Model change

Exemplo:

documentation only → LOW

new capability → MEDIUM

policy change → HIGH

destructive capability → CRITICAL

52. Change Impact Analysis

Antes do deploy:

Changed:
workPermit.validity

Sistema deverá encontrar:

Knowledge
Capabilities
Policies
UI
Tests

afetados.

53. Impact Graph

Usar o Knowledge Graph já existente:

workPermit.validity
      │
 ┌────┼────┐
 ▼    ▼    ▼
Docs  UI  Capability
          │
          ▼
        Policy

Assim o impacto pode ser calculado automaticamente.

54. Release Validation

Validar:

Semantic IDs
Capabilities
Policies
UI bindings
Documentation
Schemas
Dependencies
Tests

55. Release Registry

Criar:

interface ReleaseRegistry {
  createRelease(): Promise<Release>;

  validateRelease(
    releaseId: string
  ): Promise<ValidationResult>;

  promote(
    releaseId: string,
    environment: string
  ): Promise<void>;

  rollback(
    releaseId: string
  ): Promise<void>;

  getActiveRelease(): Promise<Release>;
}

56. Release Resolution

A execução deverá determinar:

tenant
+
environment
+
feature flags
+
release

antes de iniciar.

57. Release Lock

Para operações críticas:

execution
 ↓
release pinned

Não deverá ocorrer alteração silenciosa durante execução.

58. Incident Mode

Durante incidente:

NORMAL
 ↓
INCIDENT MODE

poderá:

  • congelar releases;
  • desabilitar capabilities;
  • reduzir rollout;
  • forçar versão anterior;
  • exigir human review.

59. Emergency Rollback

Deverá existir caminho rápido:

Incident
 ↓
Select stable release
 ↓
Rollback
 ↓
Verify health

Sem depender de uma nova compilação.

60. Audit

Toda mudança de release deverá ser auditada:

WHO
WHAT
WHEN
FROM
TO
WHY
APPROVED BY

Exemplo:

User: admin-42
Action: promote
From: 1.12.0
To: 1.13.0
Environment: production

61. Release Notes

Cada release deverá gerar automaticamente:

Features
Changes
Policies
Capabilities
Knowledge
Breaking Changes
Security
Performance
Evaluation

62. Agent Changelog

Exemplo:

1.13.0

Added:
- workPermit.updateValidity

Changed:
- confirmation policy

Knowledge:
- updated validity documentation

Performance:
- 14% faster reference resolution

Evaluation:
- 98.9% intent accuracy

63. Rollback Validation

Depois do rollback:

health check
+
smoke tests
+
critical evaluations

deverão ser executados.

64. Smoke Tests

Exemplos:

"Abra WP-123"
"Explique a validade"
"Mostre os componentes"

e uma operação segura de atualização em sandbox.

65. Production Smoke Test

Após deployment:

Production
 ↓
Synthetic Agent Requests
 ↓
Read-only operations
 ↓
Validate

Operações destrutivas nunca devem ser utilizadas como smoke test real.

66. Release Freeze

Permitir:

releaseFreeze = true

durante:

  • auditoria;
  • incidente;
  • período crítico;
  • fechamento empresarial.

67. First Vertical Slice

Implementar inicialmente:

Work Permit Agent Release

incluindo:

Runtime
Knowledge
Capabilities
Policies
UI Manifest
Evaluation Dataset
Prompts

68. Acceptance Criteria

Versionamento​

  • todos os artefatos possuem versão;
  • release possui manifest;
  • release é imutável;
  • execution fica pinned ao release.

Validation​

  • schemas validados;
  • bindings validados;
  • dependências validadas;
  • evaluation executada;
  • security gate executado.

Deployment​

  • staging;
  • canary;
  • progressive rollout;
  • feature flags;
  • production.

Rollback​

  • rollback manual;
  • rollback automático;
  • release anterior preservado;
  • execução existente protegida.

Observability​

  • versão aparece nos traces;
  • métricas por release;
  • custo por release;
  • erros por release;
  • comparação entre releases.

Evidência parcial de implementação — 2026-09-04​

O manifest canônico fixa versão e hash de artefatos; registry D1 tenant-safe preserva releases imutáveis, avaliação pinada para promoção e rollback emergencial para uma versão estável avaliada. A allocation percentual é limitada a superadmin e só aceita estados CANARY/ACTIVE; execuções existentes preservam seus pins e não são reinterpretadas por uma troca de release.

Em 2026-09-04, 16 testes locais de manifest, releases e risk rollouts passaram. Na mesma data, o seletor puro de rollout passou mais 8 testes locais: deriva um bucket estável de tenantId + requestId, escolhe CANARY apenas dentro do percentual válido e devolve o releaseId como pin. A versão do Worker f1f12c8e-edb1-4f82-87da-04c1933feac2 foi publicada a 100% e o health check respondeu OK.

Na versão feaffbc6-fe01-47cd-8872-53c428757509, a rota autenticada de prévia de orquestração passou a resolver a release ACTIVE e eventual CANARY no registry do próprio tenant. Ela ignora a release declarada pelo cliente, registra origem/bucket/pin no audit ledger e usa a release selecionada no plano. A versão ced9a7b9-2562-4347-a7db-3d74edb5ec73 reforçou a falha fechada: se não houver release promovida, retorna 409 RELEASE_CONTROL_PLANE_UNCONFIGURED, sem retroceder para o ID do cliente. Ambos os deploys foram distribuídos a 100% e o health check respondeu OK.

Em consulta remota ao D1 em 2026-09-04, o registry de produção não possuía release ACTIVE nem CANARY. Portanto, ainda é necessário promover uma release avaliada por tenant antes de usar essa rota em jornada autenticada; a configuração ausente é observável e bloqueada de modo seguro.

O canário operacional pnpm --dir apps/agente run canary:release-control-plane foi executado em 2026-09-04 com tenant sintético. Ele promoveu uma release estável e uma CANARY, registrou duas avaliações com segurança aprovada, configurou 100% de rollout e enviou deliberadamente o ID da estável pelo cliente. A prévia retornou READY, e o audit ledger confirmou que o servidor pinou a canário (releaseSource=CANARY, releasePinned=true) sem autorizar execução. Após a prova, registry, avaliações, rollout e tenant foram removidos; a consulta D1 posterior retornou zero registros operacionais. O único artefato retido é o audit ledger imutável, por desenho.

Em 2026-09-05, os contratos de release passaram com 17 testes em 4 arquivos. O canário remoto confirmou release estável e canário, seleção/pinning do canário mesmo com ID estável enviado pelo cliente, dois evaluation gates, rollout, preview READY, ausência de autoridade e cleanup com audit ledger imutável retido. A integração de execução além da prévia de Work Permit continua sendo expansão futura, sem reduzir os controles de release certificados.

Em 2026-09-06, a regressão atual dos quatro contratos de manifesto, rollout router e rotas de release passou com 17 testes, e o typecheck do Agent passou novamente. O health público do Worker confirmou runtime e bindings. A execução adicional do canário iniciou contra o control plane sintético, mas seu recibo terminal não ficou disponível após o processo assíncrono encerrar; por isso esta atualização não a usa como nova prova. O estado permanece PARTIAL por métricas e roteamento progressivo reais, além da integração de execução além da prévia.

Em 2026-09-06, GET /releases/:releaseId/metrics passou a correlacionar avaliação, rollout configurado e telemetria observada por release. A versão 0c7009df-2083-4032-b61e-58a6cadf1503 foi publicada a 100%. O canário de release obteve recibo terminal: avaliação/pinning de canário/rollout 100% válidos, contexto obsoleto rejeitado, métricas coerentes sem operações inventadas e remainingRows=0 após cleanup sintético; o audit imutável permaneceu por desenho.

Em 2026-09-06, o contrato do rollout foi alinhado ao comportamento efetivo: POST /releases/:releaseId/rollouts e GET /releases/:releaseId/metrics retornam routesOrchestrationPreview=true, pois o seletor servidor-side já roteia prévias autenticadas por bucket determinístico de tenantId + requestId; ele fixa a release selecionada no audit ledger e ignora a escolha enviada pelo cliente. Isso não alega tráfego de execução nem concede autoridade (authorizesExecution=false). Os 17 testes de release, roteador e orquestração cobrem canário e fallback ACTIVE a 50%, determinismo e o contrato HTTP; o typecheck integral do Agent passou. A expansão pendente é aplicar o mesmo pin a jornadas de execução autorizada, com revalidação de policy/approval antes de qualquer mutação.

O Worker dfef3ce6-b585-4e40-87ae-61c66da0980f foi publicado a 100% após essa correção e o health público confirmou todas as bindings. O canário remoto release-control-plane criou releases sintéticas estável e canário, selecionou/pinou canary-6fea4246d8914145, comprovou dois evaluation gates, rollout 100%, prévia atual aceita, contexto obsoleto rejeitado antes de persistência, uma trilha de intent e ausência de autoridade. O cleanup confirmou remainingRows=0; somente o ledger imutável permaneceu por desenho.

Em seguida, o seletor foi extraído para release/pinned-release.ts, preservando a única implementação servidor-side para prévia e para a futura jornada de dispatcher. A versão 7aea55b5-d48b-4bb2-b924-7338a5a3e81f foi publicada a 100%; o canário remoto voltou a passar com canary-1bda2a46868e4b3f pinada, dois gates, contexto stale rejeitado, uma trilha de intent e cleanup PostgreSQL/D1 zero. Os dados sintéticos não permaneceram; o ledger append-only é a retenção intencional.

Em 2026-09-06, o pin foi integrado ao dispatcher executável: a criação seleciona a release apenas pelo control plane e a inclui no snapshot SHA-256; ausência de release promovida retorna 409 RELEASE_CONTROL_PLANE_UNCONFIGURED. Antes de RUNNING e imediatamente antes do egress interno, o Workflow relê a release pinada e aceita somente CANARY/ACTIVE; snapshots legados ou release retirada falham fechados. Os 43 testes de rota/workflow e o typecheck passaram. No Worker 1707fb85-7e08-4773-ba8f-5f5951ac2a9c, o canário remoto promoveu uma release sintética avaliada, comprovou seu pin no plano, recibo server-issued, execução concluída e stream COMPLETED; cleanup PostgreSQL/D1 retornou zero e três recibos append-only foram retidos por desenho.

69. Resultado

O Agentic Work passa a ter um ciclo de vida profissional:

                    DEVELOPMENT
                         │
                         ▼
                     EVALUATION
                         │
                         ▼
                      RELEASE
                         │
                         ▼
                      CANARY
                         │
                         ▼
                    PRODUCTION
                         │
             ┌───────────┴───────────┐
             ▼                       ▼
         OBSERVE                   AUDIT
             │                       │
             └───────────┬───────────┘
                         ▼
                     IMPROVE
                         │
                         ▼
                     RELEASE

Isso fecha o ciclo entre desenvolvimento e operação.

PRD-017 — Agentic Multi-Tenant Architecture & Isolation

O próximo estágio deve tratar uma característica fundamental do sistema SST: multi-tenancy.

Até aqui, tenant isolation apareceu nos PRDs anteriores como requisito de segurança. No entanto, considerando que o agente terá:

  • conhecimento;
  • memória operacional;
  • capabilities;
  • policies;
  • conversas;
  • contexto;
  • auditoria;
  • métricas;
  • cache;
  • Vectorize;
  • documentos;
  • configurações;

precisamos definir explicitamente o que é global, o que pertence ao tenant, o que pertence ao usuário e o que pode ser compartilhado.

O objetivo do PRD-017 será estabelecer uma arquitetura de isolamento como:

                    AGENT PLATFORM
                          │
              ┌───────────┴───────────┐
              │                       │
           GLOBAL                  TENANT
              │                       │
       ┌──────┼──────┐       ┌────────┼────────┐
       ▼      ▼      ▼       ▼        ▼        ▼
    Runtime  Base   Models  Knowledge Policies Memory
                      │
                      ▼
                  Tenant Data

O ponto crítico será garantir que uma pergunta de um tenant jamais possa recuperar conhecimento, memória, embeddings, registros, contexto ou resultados de outro tenant, inclusive através de:

  • cache;
  • BM25;
  • Vectorize;
  • HAG;
  • Wikilinks;
  • conversation memory;
  • audit;
  • analytics;
  • tool discovery;
  • LLM context.

O PRD-017 deverá definir também tenant-aware retrieval, tenant-aware caching, isolamento de embeddings, políticas globais versus tenant-specific, configurações por cliente, quotas, rate limits e estratégias para eventualmente suportar milhares de tenants sem duplicar desnecessariamente toda a infraestrutura.