agent_framework_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

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

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

{
  "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

{
  "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

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.