agent_framework_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

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

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

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

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

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

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.