oracle/agent_framework_oci
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

First commit

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-10-30 22:04:44 -03:00
commit 645ecdfb07
2794 changed files with 282545 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
specs/en/SPEC-004-MCP-Gateway.md Normal file
View File

@@ -0,0 +1,231 @@
# SPEC-004 — MCP Gateway
## Scope
O MCP Gateway centraliza Catalog, Authorization, Routing, Execution, cache, timeout, retry, Observability and Response padronizada of tools MCP.
## Endpoints
| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/health` | Health check. |
| `GET` | `/ready` | Readiness check. |
| `GET` | `/v1/tools` | Catalog of tools. |
| `GET` | `/v1/tools/{tool_name}` | Detalhe of the tool. |
| `POST` | `/v1/tools/{tool_name}/invoke` | Execution of tool. |
| `GET` | `/v1/servers` | Lista MCP servers. |
## ToolInvocation
```json
{
"tenant_id": "default",
"agent_id": "telecom_contas",
"tool_name": "consultar_fatura",
"arguments": {
"msisdn": "11999999999",
"invoice_id": "3000131180",
"session_id": "default:telecom_contas:session-001"
},
"business_context": {
"customer_key": "11999999999",
"contract_key": "3000131180",
"session_key": "session-001"
},
"metadata": {
"request_id": "req-001",
"trace_id": "trace-001"
}
}
```
## ToolResult
```json
{
"tool_name": "consultar_fatura",
"ok": true,
"data": {
"invoice_id": "3000131180",
"valor_total": 249.90,
"vencimento": "2026-06-10",
"status": "ABERTA"
},
"cache": {
"hit": false,
"ttl_seconds": 300
},
"latency_ms": 140,
"metadata": {
"server": "telecom"
}
}
```
## mcp_servers.yaml
```yaml
servers:
telecom:
transport: http
url: http://telecom-mcp:8001/mcp
enabled: true
timeout_seconds: 30
retail:
transport: http
url: http://retail-mcp:8002/mcp
enabled: true
timeout_seconds: 30
```
## tools.yaml
```yaml
tools:
consultar_fatura:
server: telecom
enabled: true
idempotent: true
cache_ttl_seconds: 300
allowed_agents:
- telecom_contas
required_business_keys:
- customer_key
- contract_key
solicitar_devolucao:
server: retail
enabled: true
idempotent: false
requires_confirmation: true
allowed_agents:
- retail_orders
```
## mcp_parameter_mapping.yaml
```yaml
tools:
consultar_fatura:
map:
customer_key: msisdn
contract_key: invoice_id
interaction_key: ura_call_id
session_key: session_id
```
## Authorization
```yaml
authorization:
default_policy: deny
agents:
telecom_contas:
allowed_tools:
- consultar_fatura
- consultar_pagamentos
- consultar_plano
```
## Cache
| Regra | value |
|---|---|
| Chave | `tenant_id:agent_id:tool_name:hash(arguments)` |
| Aplicação | only tools idempotentes |
| Bypass | `metadata.cache_bypass=true` |
| TTL | `cache_ttl_seconds` |
| Escrita | No cachear operações mutáveis |
## Retry and Timeout
```yaml
execution:
default_timeout_seconds: 30
retry:
enabled: true
max_attempts: 2
backoff_ms: 250
circuit_breaker:
enabled: true
failure_threshold: 5
recovery_seconds: 60
```
## Events
| Evento | Description |
|---|---|
| `mcp.tool.requested` | Tool requisitada. |
| `mcp.tool.authorized` | Authorization aprovada. |
| `mcp.tool.denied` | Authorization negada. |
| `mcp.tool.started` | Execution iniciada. |
| `mcp.tool.completed` | Execution concluída. |
| `mcp.tool.failed` | Execution failed. |
| `mcp.cache.hit` | Cache hit. |
| `mcp.cache.miss` | Cache miss. |
## Metrics
| metric | Dimensões |
|---|---|
| `mcp_tool_calls_total` | tool, server, tenant, agent, status |
| `mcp_tool_latency_ms` | tool, server |
| `mcp_tool_errors_total` | tool, server, error_type |
| `mcp_cache_hits_total` | tool |
| `mcp_cache_misses_total` | tool |
## Security
- Tools are negadas por Standard.
- Argumentos sensíveis are mascarados.
- Tools mutáveis exigem confirmação when configured.
- MCP servers No recebem payload bruto of canal.
- Credenciais of backend are mantidas nos MCP servers or secret store.
## 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
- [ ] Catalog of tools retorna tools habilitadas.
- [ ] ToolInvocation is validado before of the Execution.
- [ ] Authorization por Agent is aplicada.
- [ ] Parâmetros are derivados of the BusinessContext.
- [ ] Cache só is applied a tools idempotentes.
- [ ] Timeout/retry/circuit breaker are configuráveis.
- [ ] Events and Metrics are emitidos.
- [ ] Failures retornam ToolResult padronizado.
- [ ] MCP servers are substituíveis por Configuration.
- [ ] Tools críticas possuem Tests of Contract.
## 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. |
## Policy mínima of Operations
before forward a tool, The runtime must apply a Policy Optional of the backend em `config/tool_policies.yaml`. Os tipos canônicos are `read_only` and `transactional`; esta última can exigir confirmação booleana explícita and fields required. A ausência of the file No is Error and preserva os fields legados of `tools.yaml`. A Policy conversational No substitui Authentication, Authorization, idempotência nem atomicidade no MCP Server.