agent_platform_oci/specs/en/SPEC-008-Deployment.md

# SPEC-008 — Deployment

## Scope

Deployment cobre empacotamento, CI/CD, Kubernetes/OKE, Docker, secrets, Authentication OCI, health checks, rollback and Operations of the Components.

## Components Deployáveis

| Componente | Artefato |
|---|---|
| Agent Gateway | Docker image + Kubernetes Deployment |
| Channel Gateway | Docker image + Kubernetes Deployment |
| AI Gateway | Docker image + Kubernetes Deployment |
| MCP Gateway | Docker image + Kubernetes Deployment |
| Agent Backend | Docker image + Kubernetes Deployment |
| MCP Server | Docker image + Kubernetes Deployment |
| Evaluator API | Docker image + Kubernetes Deployment |
| Evaluator Batch | Kubernetes CronJob |
| Frontend Demo | Docker image Optional |

## Pipeline

```mermaid
flowchart LR
    A[Commit] --> B[Lint]
    B --> C[Type Check]
    C --> D[Unit Tests]
    D --> E[Contract Tests]
    E --> F[Security Scan]
    F --> G[Build Wheel]
    G --> H[Build Images]
    H --> I[Publish]
    I --> J[Deploy Dev]
    J --> K[Smoke Tests]
    K --> L[Certification]
    L --> M[Deploy HML/Prod]
```

## Stages

```yaml
stages:
  - validate
  - lint
  - type_check
  - unit_test
  - contract_test
  - security_scan
  - build_package
  - build_image
  - publish
  - deploy_dev
  - smoke_test
  - certification
  - deploy_hml
  - deploy_prod
```

## Kubernetes Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: agent-runtime
  labels:
    app: agent-runtime
    component: runtime
spec:
  replicas: 2
  selector:
    matchLabels:
      app: agent-runtime
  template:
    metadata:
      labels:
        app: agent-runtime
    spec:
      serviceAccountName: agent-runtime-sa
      containers:
        - name: agent-runtime
          image: registry/agent-runtime:1.0.0
          ports:
            - containerPort: 8000
          envFrom:
            - configMapRef:
                name: agent-runtime-config
            - secretRef:
                name: agent-runtime-secrets
          readinessProbe:
            httpGet:
              path: /ready
              port: 8000
          livenessProbe:
            httpGet:
              path: /health
              port: 8000
```

## Service

```yaml
apiVersion: v1
kind: Service
metadata:
  name: agent-runtime
spec:
  selector:
    app: agent-runtime
  ports:
    - port: 8000
      targetPort: 8000
```

## OCI Authentication

| Ambiente | Modo |
|---|---|
| Local | `config_file` |
| Local with endpoint OpenAI-Compatible | API key |
| OCI Compute | `instance_principal` |
| OKE | `workload_identity` or `resource_principal` |
| Tests | `mock` |

## Variáveis

```env
LLM_PROVIDER=oci_sdk
OCI_AUTH_MODE=workload_identity
ENABLE_LANGFUSE=true
ENABLE_OTEL=true
SESSION_REPOSITORY_PROVIDER=autonomous
MEMORY_REPOSITORY_PROVIDER=autonomous
CHECKPOINT_REPOSITORY_PROVIDER=autonomous
```

## Secrets

| Secret | Uso |
|---|---|
| `LANGFUSE_PUBLIC_KEY` | Langfuse |
| `LANGFUSE_SECRET_KEY` | Langfuse |
| `OCI_GENAI_API_KEY` | OCI OpenAI-Compatible |
| `ADB_PASSWORD` | Autonomous Database |
| `MCP_BACKEND_TOKEN` | Integrações MCP |
| `OTEL_AUTH_TOKEN` | Exportador OTEL, if aplicável |

## Health Checks

| Endpoint | Uso |
|---|---|
| `/health` | Process vivo. |
| `/ready` | ready for traffic. |
| `/version` | Version of build. |
| `/debug/env` | Ambiente without segredos, when enabled. |

## Rollback

Itens considerados:

- tag of the imagem;
- Version of the pacote Python;
- Version of the schemas;
- Version of the YAMLs;
- migrations;
- datasets of eval;
- contracts;
- dashboards.

## Smoke Tests

```bash
curl -f http://agent-runtime:8000/health
curl -f http://agent-gateway:9000/health
curl -f http://mcp-gateway:8300/health
curl -f http://ai-gateway:9100/health
```

## Certification Stage

A pipeline executa:

- health checks;
- Contract GatewayRequest;
- Routing;
- MCP invoke;
- LLM mock/real conforme ambiente;
- guardrails;
- judges;
- Memory/checkpoint;
- relatório JSON/HTML.


## Requirements No Funcionais

| Categoria | Requirement |
|---|---|
| Availability | Components deployáveis expõem `/health` and `/ready`. |
| Escalabilidade | Apps stateless escalam horizontalmente. State conversational fica em repositórios external. |
| Security | Segredos are fornecidos por secret store or Kubernetes Secrets. |
| Observability | Logs, Metrics and traces usam correlation por request_id, trace_id, session_id, tenant_id and agent_id. |
| Auditabilidade | Decisions of rota, guardrail, judge, MCP and LLM are rastreáveis. |
| Portabilidade | Execution suportada em local, Docker Compose and Kubernetes/OKE. |
| Configuration | Comportamento variável is controlado por `.env` and YAML versionado. |


## Acceptance criteria

- [ ] each app possui Dockerfile.
- [ ] each app possui manifest Kubernetes.
- [ ] CI executa lint, type check and Tests.
- [ ] Contract tests validam Main contracts.
- [ ] Security scan executa before of the publish.
- [ ] Secrets No are versionados.
- [ ] Workload Identity is configured em OKE.
- [ ] Health/readiness/liveness are ativos.
- [ ] Smoke tests rodam após deploy.
- [ ] Rollback is documentado.


## Glossário

| Termo | Definição |
|---|---|
| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contracts and Components operational. |
| Agent Framework | Biblioteca/core reutilizável with contracts, guardrails, judges, Memory, telemetria, providers and utilitários. |
| Agent Runtime | Motor of Execution of Agents based on LangGraph, State, Session, Memory, checkpoints, Routing and ciclo of vida. |
| Agent Gateway | Aplicação deployável of Input, Routing and orquestração between backends/Agents. |
| Channel Gateway | Aplicação or módulo of normalização of payloads of canais for GatewayRequest. |
| AI Gateway | Aplicação of Governance, Routing and abstração of Calls LLM/embedding. |
| MCP Gateway | Aplicação of Governance and Routing of tools MCP. |
| Evaluator | layer of Evaluation online/offline, regressão and Certification. |
| Business Context | Conjunto of chaves canônicas of negócio: customer_key, contract_key, interaction_key, account_key, resource_key and session_key. |