agent_platform_oci/specs/en/SPEC-001-Architecture.md

# SPEC-001 — Architecture

## Scope

The Agent Platform OCI consists of reusable components, deployable applications, integration contracts, agent templates, an evaluation layer, and operational artifacts.

## Components

| Componente | Tipo | Responsibility |
|---|---|---|
| `libs/agent_framework` | Lib | Core reutilizável of the framework. |
| `runtimes/langgraph_runtime` | Runtime | Execution of Agents based on LangGraph. |
| `apps/agent_gateway` | App | Input padronizada and Routing of Agents/backends. |
| `apps/channel_gateway` | App | Normalização of canais external. |
| `apps/ai_gateway` | App | Abstração, Governance and Routing of modelos. |
| `apps/mcp_gateway` | App | Governance, Catalog and Execution of tools MCP. |
| `mcp/servers` | Apps | MCP servers of Domain. |
| `evals/offline` | App/Lib | Evaluation offline/batch. |
| `evals/certification` | Suite | Certification técnica and funcional. |
| `templates/agent_template_backend` | Template | Scaffold for new Agents. |
| `specs` | documentation | contracts SDD versionados. |
| `deploy` | Operations | Docker, Kubernetes and Helm. |

## Repository structure

```text
agent_platform_oci/
├── libs/
│   └── agent_framework/
├── runtimes/
│   └── langgraph_runtime/
├── apps/
│   ├── agent_gateway/
│   ├── channel_gateway/
│   ├── ai_gateway/
│   └── mcp_gateway/
├── mcp/
│   └── servers/
├── evals/
│   ├── offline/
│   └── certification/
├── templates/
│   ├── agent_template_backend/
│   └── agent_template_backend_day_zero/
├── specs/
├── deploy/
│   ├── docker/
│   ├── k8s/
│   └── helm/
├── tests/
└── docs/
```

## Logical architecture

```mermaid
flowchart LR
    C[Canal] --> CG[Channel Gateway]
    CG --> AG[Agent Gateway]
    AG --> RT[Agent Runtime]
    RT --> FW[Agent Framework Core]
    RT --> AIG[AI Gateway]
    RT --> MCPG[MCP Gateway]
    MCPG --> MCPS[MCP Servers]
    RT --> OBS[Observability]
    RT --> MEM[Memory/Checkpoint]
    OBS --> LF[Langfuse/OTEL]
    LF --> EV[Evaluator]
```

## Physical architecture

| service | Porta Standard | Deploy | Escala |
|---|---:|---|---|
| Agent Gateway | 9000 | Kubernetes Deployment | Horizontal |
| Agent Backend / Runtime | 8000 | Kubernetes Deployment | Horizontal with external storage |
| Channel Gateway | 7000 | Kubernetes Deployment | Horizontal |
| AI Gateway | 9100 | Kubernetes Deployment | Horizontal |
| MCP Gateway | 8300 | Kubernetes Deployment | Horizontal |
| MCP Servers | 8001+ | Kubernetes Deployment | Per domain |
| Evaluator API | 9300 | Deployment/CronJob | By batch workload |
| Frontend Demo | 5173 | Optional | Noncritical |

## Main contracts

| Contract | producer | consumer |
|---|---|---|
| GatewayRequest | Channel Gateway / Agent Gateway | Agent Runtime |
| ChannelResponse | Agent Runtime | Channel Gateway / Cliente |
| BusinessContext | Channel Gateway / Identity resolve | Runtime / Agents / MCP |
| LLMRequest | Agent Runtime | AI Gateway |
| LLMResponse | AI Gateway | Agent Runtime |
| ToolInvocation | Agent Runtime / MCP Gateway | MCP Server |
| ToolResult | MCP Server / MCP Gateway | Agent Runtime |
| GuardrailResult | Guardrail Engine | Runtime / Observability |
| JudgeResult | Judge Engine / Evaluator | Runtime / Evaluator |
| EvaluationRun | Evaluator | Persistence / Dashboards |

## GatewayRequest

```json
{
  "channel": "web",
  "tenant_id": "default",
  "agent_id": "telecom_contas",
  "payload": {
    "message": "Quero consultar minha fatura",
    "session_id": "session-001",
    "user_id": "user-001",
    "message_id": "msg-001",
    "business_context": {
      "customer_key": "11999999999",
      "contract_key": "3000131180",
      "interaction_key": "301953872",
      "session_key": "session-001"
    },
    "metadata": {
      "request_id": "req-001"
    }
  }
}
```

## ChannelResponse

```json
{
  "channel": "web",
  "session_id": "default:telecom_contas:session-001",
  "text": "Resposta final do agente.",
  "metadata": {
    "tenant_id": "default",
    "agent_id": "telecom_contas",
    "route": "billing_agent",
    "intent": "billing_invoice_explanation"
  }
}
```

## Flow main

```mermaid
sequenceDiagram
    participant Canal
    participant ChannelGateway
    participant AgentGateway
    participant Runtime
    participant AIGateway
    participant MCPGateway
    participant Store
    Canal->>ChannelGateway: Payload bruto
    ChannelGateway->>AgentGateway: GatewayRequest
    AgentGateway->>Runtime: GatewayRequest normalizado
    Runtime->>Store: Sessão, memória e checkpoint
    Runtime->>Runtime: Guardrails de entrada
    Runtime->>Runtime: Router/Supervisor
    Runtime->>MCPGateway: ToolInvocation
    MCPGateway-->>Runtime: ToolResult
    Runtime->>AIGateway: LLMRequest
    AIGateway-->>Runtime: LLMResponse
    Runtime->>Runtime: Guardrails de saída e Judges
    Runtime->>Store: Persistência
    Runtime-->>AgentGateway: ChannelResponse
    AgentGateway-->>ChannelGateway: ChannelResponse
    ChannelGateway-->>Canal: Resposta do canal
```

## Configuration

| file | Uso |
|---|---|
| `.env` | Provider, Authentication, flags and endpoints por ambiente. |
| `agents.yaml` | Registration of Agents. |
| `routing.yaml` | Intents, rotas, Policies and fallback. |
| `guardrails.yaml` | Guardrails global. |
| `judges.yaml` | Judges global. |
| `llm_profiles.yaml` | Profiles of modelos por componente. |
| `mcp_servers.yaml` | MCP servers disponíveis. |
| `tools.yaml` | Catalog of tools. |
| `mcp_parameter_mapping.yaml` | Mapeamento BusinessContext → argumentos MCP. |
| `identity.yaml` | Resolução of Identity of negócio. |
| `observability.yaml` | Logs, Metrics, traces and exporters. |
| `evals.yaml` | Datasets, Metrics and Configuration of the evaluator. |

## Events

| Evento | Origem | Description |
|---|---|---|
| `gateway.request.received` | Agent Gateway | Request recebida. |
| `channel.normalized` | Channel Gateway | Payload convertido em GatewayRequest. |
| `runtime.started` | Runtime | Execution iniciada. |
| `guardrail.input.completed` | Guardrails | Guardrails of Input concluídos. |
| `route.selected` | Router/Supervisor | Rota definida. |
| `mcp.tool.completed` | MCP Gateway | Tool executada. |
| `llm.completed` | AI Gateway | Call LLM concluída. |
| `judge.completed` | Judge Engine | Evaluation concluída. |
| `runtime.completed` | Runtime | Execution finalizada. |


## 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

- [ ] Repository structure separa libs, runtimes, apps, mcp, evals, templates, specs and deploy.
- [ ] each app deployável possui Contract of Input/Output documentado.
- [ ] GatewayRequest and ChannelResponse are versionados.
- [ ] BusinessContext is Used como Contract canônico.
- [ ] Runtime No recebe payload bruto of canal.
- [ ] AI Gateway and MCP Gateway possuem fronteiras explícitas.
- [ ] Evaluator is componente padronizado of Evaluation.
- [ ] all os services possuem health check.
- [ ] Telemetria fim-a-fim correlaciona request_id, trace_id and session_id.
- [ ] Configuration críticas possuem YAML dedicado.


## 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. |