mirror of
https://github.com/hoshikawa2/agent_platform_oci.git
synced 2026-07-09 14:04:19 +00:00
Ajustes na documentação e remanejamento dos folders
This commit is contained in:
133
Documentacao/INVENTARIO_AGENT_GATEWAY_MCP_GATEWAY.md
Normal file
133
Documentacao/INVENTARIO_AGENT_GATEWAY_MCP_GATEWAY.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Inventário — Agent Gateway + MCP Gateway Overlay
|
||||
|
||||
Este inventário lista os arquivos incluídos no overlay `agent_platform_agent_gateway_mcp_gateway_overlay.zip`, indicando a área, o tipo de alteração e a finalidade de cada arquivo.
|
||||
|
||||
## Resumo
|
||||
|
||||
| Área | Quantidade |
|
||||
|---|---:|
|
||||
| Documentação | 1 |
|
||||
| Agent Gateway | 10 |
|
||||
| MCP Gateway | 5 |
|
||||
| Agent Framework | 4 |
|
||||
| Template Backend | 2 |
|
||||
| MCP Server Mock | 2 |
|
||||
| Deploy | 2 |
|
||||
|
||||
## Arquivos por área
|
||||
|
||||
### Documentação
|
||||
|
||||
| Arquivo | Tipo | Finalidade |
|
||||
|---|---|---|
|
||||
| `README_AGENT_GATEWAY_AND_MCP_GATEWAY_EVOLUTION.md` | Novo / overlay | Documento principal do overlay. Explica a nova arquitetura sem AI Gateway separado, com Agent Gateway governando políticas/modelos e MCP Gateway separado para tools. |
|
||||
|
||||
### Agent Gateway
|
||||
|
||||
| Arquivo | Tipo | Finalidade |
|
||||
|---|---|---|
|
||||
| `apps/agent_gateway/app/config/governance_loader.py` | Novo / overlay | Carrega o arquivo YAML de governança do Agent Gateway a partir de AGENT_GATEWAY_GOVERNANCE_CONFIG. |
|
||||
| `apps/agent_gateway/app/governance/__init__.py` | Novo / overlay | Inicializa o pacote Python de governança do Agent Gateway. |
|
||||
| `apps/agent_gateway/app/governance/audit.py` | Novo / overlay | Centraliza logging/auditoria das decisões de governança do Agent Gateway, com proteção simples para não logar mensagem completa. |
|
||||
| `apps/agent_gateway/app/governance/evaluation_hooks.py` | Novo / overlay | Hooks antes e depois da chamada ao backend/runtime. Serve para amostragem, evaluator, scoring ou integração futura com Langfuse. |
|
||||
| `apps/agent_gateway/app/governance/model_policies.py` | Novo / overlay | Resolve políticas de modelo/profile no Agent Gateway. Define qual provider/model/profile deve ser usado por operação, tenant e agente. |
|
||||
| `apps/agent_gateway/app/governance/rate_limit.py` | Novo / overlay | Implementa rate limit em memória por tenant, agente e canal antes de encaminhar a requisição ao backend/runtime. |
|
||||
| `apps/agent_gateway/app/governance/usage.py` | Novo / overlay | Hook para registrar uso de gateway, políticas aplicadas e respostas do backend. Pronto para plugar métricas, banco, Langfuse ou OTEL. |
|
||||
| `apps/agent_gateway/app/governance_middleware.py` | Novo / overlay | Componente principal de governança do Agent Gateway. Aplica rate limit, resolve model_policy, gera headers/metadados e executa hooks antes/depois do backend. |
|
||||
| `apps/agent_gateway/app/routes/governed_proxy_example.py` | Novo / overlay | Exemplo de rota governada para demonstrar como aplicar governança antes de encaminhar para o Agent Backend/Runtime. |
|
||||
| `apps/agent_gateway/config/gateway_governance.yaml` | Novo / overlay | Configuração de governança do Agent Gateway: profiles, operation_profiles, providers permitidos, rate limits, headers propagados e evaluation hooks. |
|
||||
|
||||
### MCP Gateway
|
||||
|
||||
| Arquivo | Tipo | Finalidade |
|
||||
|---|---|---|
|
||||
| `apps/mcp_gateway/Dockerfile` | Novo / overlay | Imagem Docker do MCP Gateway. |
|
||||
| `apps/mcp_gateway/app/__init__.py` | Novo / overlay | Inicializa o pacote Python da aplicação MCP Gateway. |
|
||||
| `apps/mcp_gateway/app/main.py` | Novo / overlay | Aplicação FastAPI do MCP Gateway. Expõe health, ready, catálogo de tools e endpoint de invoke com auth, autorização, mapping, cache, timeout e retry. |
|
||||
| `apps/mcp_gateway/config/mcp_gateway.yaml` | Novo / overlay | Configuração central do MCP Gateway: MCP servers, tools, versões, cache, timeout, retry, autorização por agente/canal e mapping BusinessContext → parâmetros. |
|
||||
| `apps/mcp_gateway/requirements.txt` | Novo / overlay | Dependências Python do MCP Gateway. |
|
||||
|
||||
### Agent Framework
|
||||
|
||||
| Arquivo | Tipo | Finalidade |
|
||||
|---|---|---|
|
||||
| `libs/agent_framework/src/agent_framework/gateway_policy_context.py` | Novo / overlay | Helper no framework para o Runtime ler a política de modelo enviada pelo Agent Gateway em state['metadata']['model_policy']. |
|
||||
| `libs/agent_framework/src/agent_framework/gateways/__init__.py` | Novo / overlay | Inicializa o pacote de clients de gateways no framework, exportando MCPGatewayClient. |
|
||||
| `libs/agent_framework/src/agent_framework/gateways/mcp_gateway_client.py` | Novo / overlay | Client assíncrono do framework para chamar o MCP Gateway: listar tools e executar tools. |
|
||||
| `libs/agent_framework/src/agent_framework/runtime_mcp_gateway_adapter.py` | Novo / overlay | Mixin opcional para agentes/runtime chamarem tools via MCP Gateway e anexarem resultados em state['mcp_results']. |
|
||||
|
||||
### Template Backend
|
||||
|
||||
| Arquivo | Tipo | Finalidade |
|
||||
|---|---|---|
|
||||
| `templates/agent_template_backend/app/mcp_gateway_client_factory.py` | Novo / overlay | Factory no template backend para construir MCPGatewayClient a partir de variáveis de ambiente. |
|
||||
|
||||
### MCP Server Mock
|
||||
|
||||
| Arquivo | Tipo | Finalidade |
|
||||
|---|---|---|
|
||||
| `mcp/servers/mock_telecom_mcp/app.py` | Novo / overlay | Mock MCP Server com tools consultar_fatura e consultar_pagamentos para validar o MCP Gateway localmente. |
|
||||
| `mcp/servers/mock_telecom_mcp/requirements.txt` | Novo / overlay | Dependências do mock MCP Server de telecom usado para testes locais. |
|
||||
|
||||
### Deploy
|
||||
|
||||
| Arquivo | Tipo | Finalidade |
|
||||
|---|---|---|
|
||||
| `deploy/docker/docker-compose.mcp-gateway.yml` | Novo / overlay | Docker Compose para subir MCP Gateway e mock_telecom_mcp localmente. |
|
||||
| `deploy/k8s/mcp-gateway.yaml` | Novo / overlay | Manifest Kubernetes de Deployment e Service do MCP Gateway. |
|
||||
|
||||
## Observações de integração
|
||||
|
||||
### Agent Gateway
|
||||
|
||||
Os arquivos em `apps/agent_gateway` não criam um novo serviço. Eles evoluem o Agent Gateway existente para atuar como gateway dedicado da plataforma, centralizando:
|
||||
|
||||
- políticas de modelo/profile;
|
||||
- rate limit;
|
||||
- auditoria;
|
||||
- hooks de avaliação;
|
||||
- propagação de metadados de governança para o Runtime.
|
||||
|
||||
A rota `governed_proxy_example.py` é um exemplo de integração. O handler real do `POST /gateway/message` deve aplicar:
|
||||
|
||||
```python
|
||||
governed_body, headers = governance.prepare_backend_request(body)
|
||||
```
|
||||
|
||||
antes de chamar o backend/runtime, e:
|
||||
|
||||
```python
|
||||
return governance.process_backend_response(data)
|
||||
```
|
||||
|
||||
após receber a resposta.
|
||||
|
||||
### MCP Gateway
|
||||
|
||||
O MCP Gateway é um serviço separado. Ele centraliza:
|
||||
|
||||
- catálogo de tools;
|
||||
- autorização por agente/canal;
|
||||
- versionamento de tools;
|
||||
- mapping de BusinessContext para parâmetros;
|
||||
- cache;
|
||||
- timeout;
|
||||
- retry;
|
||||
- auditoria simples.
|
||||
|
||||
### Runtime / Backend
|
||||
|
||||
O Runtime continua responsável por:
|
||||
|
||||
- LangGraph;
|
||||
- estado;
|
||||
- memória;
|
||||
- checkpoints;
|
||||
- fluxo;
|
||||
- providers LLM existentes.
|
||||
|
||||
O Runtime passa a chamar tools via MCP Gateway usando `MCPGatewayClient` e/ou `MCPGatewayRuntimeMixin`.
|
||||
|
||||
### AI Gateway
|
||||
|
||||
Este overlay não cria `apps/ai_gateway`. A governança de modelo fica no Agent Gateway, e a execução LLM continua no Runtime/backend usando os providers já existentes.
|
||||
@@ -0,0 +1,627 @@
|
||||
# Manual de Execução Local
|
||||
## Agent Gateway + MCP Gateway + Agent Template Backend + Frontend
|
||||
|
||||
## 1. Arquitetura de execução
|
||||
|
||||
A arquitetura local fica assim:
|
||||
|
||||
```text
|
||||
Frontend
|
||||
porta 5173
|
||||
│
|
||||
▼
|
||||
Agent Gateway
|
||||
porta 9000
|
||||
│
|
||||
▼
|
||||
Agent Template Backend / Agent Runtime
|
||||
porta 8000
|
||||
│
|
||||
▼
|
||||
MCP Gateway
|
||||
porta 8300
|
||||
│
|
||||
▼
|
||||
MCP Server / Mock Telecom MCP
|
||||
porta 8001
|
||||
```
|
||||
|
||||
A governança de modelo, rate limit, auditoria e políticas ficam no **Agent Gateway**.
|
||||
|
||||
O **Agent Runtime / Agent Template Backend** continua responsável por:
|
||||
|
||||
- LangGraph;
|
||||
- estado;
|
||||
- memória;
|
||||
- checkpoints;
|
||||
- supervisor/router;
|
||||
- guardrails;
|
||||
- judges;
|
||||
- chamada LLM via providers existentes;
|
||||
- chamada de tools via MCP Gateway.
|
||||
|
||||
---
|
||||
|
||||
## 2. Portas
|
||||
|
||||
| Componente | Porta | URL |
|
||||
|---|---:|---|
|
||||
| Frontend | 5173 | `http://localhost:5173` |
|
||||
| Agent Gateway | 9000 | `http://localhost:9000` |
|
||||
| Agent Template Backend | 8000 | `http://localhost:8000` |
|
||||
| MCP Gateway | 8300 | `http://localhost:8300` |
|
||||
| MCP Server / Mock Telecom MCP | 8001 | `http://localhost:8001` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Ordem recomendada para subir
|
||||
|
||||
Subir nesta ordem:
|
||||
|
||||
1. MCP Server / Mock Telecom MCP
|
||||
2. MCP Gateway
|
||||
3. Agent Template Backend
|
||||
4. Agent Gateway
|
||||
5. Frontend
|
||||
|
||||
---
|
||||
|
||||
# 4. Terminal 1 — MCP Server / Mock Telecom MCP
|
||||
|
||||
Se estiver usando o mock incluído no overlay:
|
||||
|
||||
```bash
|
||||
cd agent_platform_oci/mcp/servers/mock_telecom_mcp
|
||||
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
pip install -r requirements.txt
|
||||
|
||||
uvicorn app:app --host 0.0.0.0 --port 8001 --reload
|
||||
```
|
||||
|
||||
Validar:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8001/health
|
||||
```
|
||||
|
||||
Resultado esperado:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"service": "mock_telecom_mcp"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 5. Terminal 2 — MCP Gateway
|
||||
|
||||
```bash
|
||||
cd agent_platform_oci/apps/mcp_gateway
|
||||
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
pip install -r requirements.txt
|
||||
|
||||
export MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
|
||||
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
|
||||
```
|
||||
|
||||
Validar health:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8300/health
|
||||
```
|
||||
|
||||
Validar readiness:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8300/ready
|
||||
```
|
||||
|
||||
Listar tools:
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:8300/v1/tools | jq
|
||||
```
|
||||
|
||||
Executar tool:
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tenant_id": "default",
|
||||
"agent_id": "telecom_contas",
|
||||
"channel": "web",
|
||||
"tool_name": "consultar_fatura",
|
||||
"business_context": {
|
||||
"customer_key": "11999999999",
|
||||
"contract_key": "INV-001",
|
||||
"session_key": "session-001"
|
||||
}
|
||||
}' | jq
|
||||
```
|
||||
|
||||
Resultado esperado:
|
||||
|
||||
```json
|
||||
{
|
||||
"tool_name": "consultar_fatura",
|
||||
"version": "1.0.0",
|
||||
"ok": true,
|
||||
"data": {
|
||||
"invoice_id": "INV-001",
|
||||
"msisdn": "11999999999",
|
||||
"valor_total": 249.9,
|
||||
"vencimento": "2026-06-10",
|
||||
"status": "ABERTA"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 6. Terminal 3 — Agent Template Backend / Agent Runtime
|
||||
|
||||
```bash
|
||||
cd agent_platform_oci/templates/agent_template_backend
|
||||
```
|
||||
|
||||
ou, se o seu backend estiver em outra pasta:
|
||||
|
||||
```bash
|
||||
cd agent_platform_oci/templates/agent_template_backend
|
||||
```
|
||||
|
||||
Ativar ambiente:
|
||||
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
Se ainda não existir `.venv`:
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Configurar variáveis:
|
||||
|
||||
```bash
|
||||
export MCP_GATEWAY_ENABLED=true
|
||||
export MCP_GATEWAY_URL=http://localhost:8300
|
||||
export MCP_GATEWAY_TIMEOUT_SECONDS=60
|
||||
|
||||
export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
|
||||
```
|
||||
|
||||
Se estiver usando OCI/OpenAI-compatible, manter também as variáveis já existentes do backend:
|
||||
|
||||
```bash
|
||||
export LLM_PROVIDER=oci_openai
|
||||
export OCI_GENAI_API_KEY=<sua-chave>
|
||||
```
|
||||
|
||||
ou, para mock:
|
||||
|
||||
```bash
|
||||
export LLM_PROVIDER=mock
|
||||
```
|
||||
|
||||
Subir backend:
|
||||
|
||||
```bash
|
||||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
||||
```
|
||||
|
||||
Validar:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
Validar agentes:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/agents | jq
|
||||
```
|
||||
|
||||
Testar backend direto:
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://localhost:8000/gateway/message \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"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": "INV-001",
|
||||
"session_key": "session-001"
|
||||
}
|
||||
}
|
||||
}' | jq
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 7. Terminal 4 — Agent Gateway
|
||||
|
||||
```bash
|
||||
cd agent_platform_oci/apps/agent_gateway
|
||||
```
|
||||
|
||||
Ativar ambiente:
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Configurar variáveis:
|
||||
|
||||
```bash
|
||||
export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
|
||||
export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
|
||||
```
|
||||
|
||||
Subir Agent Gateway:
|
||||
|
||||
```bash
|
||||
python -m uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
|
||||
```
|
||||
|
||||
Validar:
|
||||
|
||||
```bash
|
||||
curl http://localhost:9000/health
|
||||
```
|
||||
|
||||
Se a rota governada de exemplo estiver registrada no `app.main`, testar:
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://localhost:9000/gateway/message/governed \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"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",
|
||||
"metadata": {
|
||||
"operation": "agent.final_answer"
|
||||
},
|
||||
"business_context": {
|
||||
"customer_key": "11999999999",
|
||||
"contract_key": "INV-001",
|
||||
"session_key": "session-001"
|
||||
}
|
||||
}
|
||||
}' | jq
|
||||
```
|
||||
|
||||
Se a rota real for `/gateway/message`, testar:
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://localhost:9000/gateway/message \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"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",
|
||||
"metadata": {
|
||||
"operation": "agent.final_answer"
|
||||
},
|
||||
"business_context": {
|
||||
"customer_key": "11999999999",
|
||||
"contract_key": "INV-001",
|
||||
"session_key": "session-001"
|
||||
}
|
||||
}
|
||||
}' | jq
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 8. Terminal 5 — Frontend
|
||||
|
||||
```bash
|
||||
cd agent_platform_oci/agent_frontend
|
||||
```
|
||||
|
||||
ou a pasta onde estiver o frontend.
|
||||
|
||||
Instalar dependências:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Subir:
|
||||
|
||||
```bash
|
||||
npm run dev -- --host 0.0.0.0 --port 5173
|
||||
```
|
||||
|
||||
Abrir:
|
||||
|
||||
```text
|
||||
http://localhost:5173
|
||||
```
|
||||
|
||||
Configurar no frontend:
|
||||
|
||||
```text
|
||||
Backend URL: http://localhost:9000
|
||||
Agent: telecom_contas
|
||||
Session ID: session-001
|
||||
Customer Key: 11999999999
|
||||
Contract Key: INV-001
|
||||
```
|
||||
|
||||
O frontend deve chamar o **Agent Gateway** na porta 9000, não o MCP Gateway.
|
||||
|
||||
---
|
||||
|
||||
# 9. Fluxo final esperado
|
||||
|
||||
```text
|
||||
Frontend 5173
|
||||
↓
|
||||
Agent Gateway 9000
|
||||
↓
|
||||
Agent Template Backend 8000
|
||||
↓
|
||||
MCP Gateway 8300
|
||||
↓
|
||||
Mock Telecom MCP 8001
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 10. Docker Compose para MCP Gateway + Mock MCP
|
||||
|
||||
Também é possível subir MCP Gateway + Mock MCP com Docker Compose:
|
||||
|
||||
```bash
|
||||
cd agent_platform_oci
|
||||
|
||||
docker compose -f deploy/docker/docker-compose.mcp-gateway.yml up --build
|
||||
```
|
||||
|
||||
Isso sobe:
|
||||
|
||||
```text
|
||||
MCP Gateway http://localhost:8300
|
||||
Mock Telecom MCP http://localhost:8001
|
||||
```
|
||||
|
||||
Depois subir manualmente:
|
||||
|
||||
- Agent Template Backend na porta 8000;
|
||||
- Agent Gateway na porta 9000;
|
||||
- Frontend na porta 5173.
|
||||
|
||||
---
|
||||
|
||||
# 11. Checklist de validação
|
||||
|
||||
## MCP Server
|
||||
|
||||
```bash
|
||||
curl http://localhost:8001/health
|
||||
```
|
||||
|
||||
## MCP Gateway
|
||||
|
||||
```bash
|
||||
curl http://localhost:8300/health
|
||||
curl http://localhost:8300/v1/tools
|
||||
```
|
||||
|
||||
## Backend Runtime
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
curl http://localhost:8000/agents
|
||||
```
|
||||
|
||||
## Agent Gateway
|
||||
|
||||
```bash
|
||||
curl http://localhost:9000/health
|
||||
```
|
||||
|
||||
## Frontend
|
||||
|
||||
```text
|
||||
http://localhost:5173
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 12. Erros comuns
|
||||
|
||||
## 12.1. Frontend chamando porta errada
|
||||
|
||||
Errado:
|
||||
|
||||
```text
|
||||
Frontend → http://localhost:8000
|
||||
```
|
||||
|
||||
Correto:
|
||||
|
||||
```text
|
||||
Frontend → http://localhost:9000
|
||||
```
|
||||
|
||||
Se você quiser testar sem Agent Gateway, pode apontar temporariamente para 8000. Mas no modelo final, o frontend deve usar o Agent Gateway.
|
||||
|
||||
---
|
||||
|
||||
## 12.2. MCP Gateway sem MCP Server
|
||||
|
||||
Sintoma:
|
||||
|
||||
```text
|
||||
MCP server unavailable
|
||||
```
|
||||
|
||||
Correção:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8001/health
|
||||
```
|
||||
|
||||
Se falhar, subir o mock MCP server.
|
||||
|
||||
---
|
||||
|
||||
## 12.3. Tool sem BusinessContext
|
||||
|
||||
Sintoma:
|
||||
|
||||
```json
|
||||
{
|
||||
"missing_business_keys": ["customer_key", "contract_key"]
|
||||
}
|
||||
```
|
||||
|
||||
Correção:
|
||||
|
||||
enviar:
|
||||
|
||||
```json
|
||||
"business_context": {
|
||||
"customer_key": "11999999999",
|
||||
"contract_key": "INV-001",
|
||||
"session_key": "session-001"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12.4. Agent Gateway não encontra backend
|
||||
|
||||
Sintoma:
|
||||
|
||||
```text
|
||||
Connection refused http://localhost:8000
|
||||
```
|
||||
|
||||
Correção:
|
||||
|
||||
validar:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
e configurar:
|
||||
|
||||
```bash
|
||||
export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12.5. Rota governada não registrada
|
||||
|
||||
Se `/gateway/message/governed` retornar 404, significa que o arquivo de exemplo ainda não foi incluído no `app.main`.
|
||||
|
||||
Nesse caso, use a rota real `/gateway/message` ou registre no `main.py`:
|
||||
|
||||
```python
|
||||
from app.routes.governed_proxy_example import router as governed_router
|
||||
|
||||
app.include_router(governed_router)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 13. Variáveis consolidadas
|
||||
|
||||
## Agent Gateway
|
||||
|
||||
```env
|
||||
DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
|
||||
AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
|
||||
```
|
||||
|
||||
## Agent Template Backend
|
||||
|
||||
```env
|
||||
MCP_GATEWAY_ENABLED=true
|
||||
MCP_GATEWAY_URL=http://localhost:8300
|
||||
MCP_GATEWAY_TIMEOUT_SECONDS=60
|
||||
LLM_PROVIDER=mock
|
||||
```
|
||||
|
||||
## MCP Gateway
|
||||
|
||||
```env
|
||||
MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 14. Resumo rápido
|
||||
|
||||
Em cinco terminais:
|
||||
|
||||
```bash
|
||||
# Terminal 1
|
||||
cd mcp/servers/mock_telecom_mcp
|
||||
source .venv/bin/activate
|
||||
uvicorn app:app --host 0.0.0.0 --port 8001 --reload
|
||||
|
||||
# Terminal 2
|
||||
cd apps/mcp_gateway
|
||||
source .venv/bin/activate
|
||||
export MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
|
||||
|
||||
# Terminal 3
|
||||
cd templates/agent_template_backend
|
||||
source .venv/bin/activate
|
||||
export MCP_GATEWAY_ENABLED=true
|
||||
export MCP_GATEWAY_URL=http://localhost:8300
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
||||
|
||||
# Terminal 4
|
||||
cd apps/agent_gateway
|
||||
source .venv/bin/activate
|
||||
export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
|
||||
export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
|
||||
|
||||
# Terminal 5
|
||||
cd agent_frontend
|
||||
npm install
|
||||
npm run dev -- --host 0.0.0.0 --port 5173
|
||||
```
|
||||
93
Documentacao/MCP_GATEWAY_RUNBOOK.md
Normal file
93
Documentacao/MCP_GATEWAY_RUNBOOK.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# MCP Gateway Runbook
|
||||
|
||||
## Arquitetura corrigida
|
||||
|
||||
O backend/agente não deve chamar diretamente os MCP servers finais. O fluxo correto é:
|
||||
|
||||
```text
|
||||
agent_template_backend / agent_framework
|
||||
-> MCP Gateway Client
|
||||
-> apps/mcp_gateway
|
||||
-> mcp/servers/telecom_mcp_server ou mcp/servers/retail_mcp_server
|
||||
```
|
||||
|
||||
## Subir localmente
|
||||
|
||||
A partir da raiz do projeto:
|
||||
|
||||
### Terminal 1 - Telecom MCP Server
|
||||
|
||||
```bash
|
||||
cd mcp/servers/telecom_mcp_server
|
||||
python -m uvicorn main:app --host 0.0.0.0 --port 8100 --reload
|
||||
```
|
||||
|
||||
### Terminal 2 - Retail MCP Server
|
||||
|
||||
```bash
|
||||
cd mcp/servers/retail_mcp_server
|
||||
python -m uvicorn main:app --host 0.0.0.0 --port 8200 --reload
|
||||
```
|
||||
|
||||
### Terminal 3 - MCP Gateway
|
||||
|
||||
```bash
|
||||
cd apps/mcp_gateway
|
||||
export MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
|
||||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
|
||||
```
|
||||
|
||||
### Terminal 4 - Backend/agente
|
||||
|
||||
No `.env` do backend/agente ou do runtime que usa o `agent_framework`, habilite:
|
||||
|
||||
```env
|
||||
ENABLE_MCP_TOOLS=true
|
||||
MCP_GATEWAY_ENABLED=true
|
||||
MCP_GATEWAY_URL=http://localhost:8300
|
||||
MCP_GATEWAY_AGENT_ID=telecom_contas
|
||||
MCP_GATEWAY_TENANT_ID=default
|
||||
```
|
||||
|
||||
## Testes rápidos
|
||||
|
||||
### Health do gateway
|
||||
|
||||
```bash
|
||||
curl http://localhost:8300/health
|
||||
```
|
||||
|
||||
### Lista de tools expostas pelo gateway
|
||||
|
||||
```bash
|
||||
curl http://localhost:8300/v1/tools
|
||||
```
|
||||
|
||||
### Chamada de tool via gateway
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"tenant_id": "default",
|
||||
"agent_id": "telecom_contas",
|
||||
"channel": "web",
|
||||
"tool_name": "consultar_fatura",
|
||||
"arguments": {
|
||||
"msisdn": "11999999999",
|
||||
"invoice_id": "INV-123"
|
||||
},
|
||||
"business_context": {},
|
||||
"metadata": {"session_id": "local-test"}
|
||||
}'
|
||||
```
|
||||
|
||||
Resposta esperada: `ok: true`, `data.invoice_id`, `data.msisdn`, `metadata.server: telecom`.
|
||||
|
||||
## O que foi corrigido
|
||||
|
||||
- `apps/mcp_gateway/config/mcp_gateway.yaml` agora aponta para os MCP servers reais nas portas `8100` e `8200`.
|
||||
- O MCP Gateway agora suporta o contrato legado dos MCP servers: `POST /mcp/tools/call` com `{tool_name, arguments}`.
|
||||
- O `agent_framework` ganhou flags `MCP_GATEWAY_ENABLED`, `MCP_GATEWAY_URL`, `MCP_GATEWAY_TOKEN`, `MCP_GATEWAY_AGENT_ID` e `MCP_GATEWAY_TENANT_ID`.
|
||||
- O `MCPToolRouter` passa a chamar o MCP Gateway quando `MCP_GATEWAY_ENABLED=true`.
|
||||
- `libs/agent_framework/config/mcp_servers.yaml` foi mantido como registry lógico/fallback, não como caminho principal quando o gateway está ativo.
|
||||
129
Documentacao/README_AGENT_GATEWAY_AND_MCP_GATEWAY_EVOLUTION.md
Normal file
129
Documentacao/README_AGENT_GATEWAY_AND_MCP_GATEWAY_EVOLUTION.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Agent Platform OCI — Agent Gateway + MCP Gateway Evolution
|
||||
|
||||
Este overlay remove o conceito de `AI Gateway` separado.
|
||||
|
||||
## Arquitetura
|
||||
|
||||
```text
|
||||
Frontend
|
||||
↓
|
||||
Agent Gateway
|
||||
├── governance
|
||||
├── model policies
|
||||
├── rate limit
|
||||
├── audit
|
||||
└── evaluation hooks
|
||||
↓
|
||||
Agent Backend / Runtime
|
||||
├── LangGraph
|
||||
├── state
|
||||
├── memory
|
||||
├── checkpoints
|
||||
└── LLM providers via profiles existentes
|
||||
↓
|
||||
MCP Gateway
|
||||
↓
|
||||
MCP Servers
|
||||
```
|
||||
|
||||
## O que entra no Agent Gateway
|
||||
|
||||
```text
|
||||
apps/agent_gateway/app/governance/
|
||||
apps/agent_gateway/app/governance_middleware.py
|
||||
apps/agent_gateway/app/routes/governed_proxy_example.py
|
||||
apps/agent_gateway/config/gateway_governance.yaml
|
||||
```
|
||||
|
||||
## O que entra no MCP Gateway
|
||||
|
||||
```text
|
||||
apps/mcp_gateway/
|
||||
libs/agent_framework/src/agent_framework/gateways/mcp_gateway_client.py
|
||||
libs/agent_framework/src/agent_framework/runtime_mcp_gateway_adapter.py
|
||||
```
|
||||
|
||||
## Aplicar overlay
|
||||
|
||||
```bash
|
||||
unzip agent_platform_agent_gateway_mcp_gateway_overlay.zip -d /tmp/overlay
|
||||
rsync -av /tmp/overlay/ ./
|
||||
```
|
||||
|
||||
## Subir MCP Gateway local
|
||||
|
||||
```bash
|
||||
docker compose -f deploy/docker/docker-compose.mcp-gateway.yml up --build
|
||||
```
|
||||
|
||||
Serviços:
|
||||
|
||||
```text
|
||||
MCP Gateway http://localhost:8300
|
||||
Mock Telecom MCP http://localhost:8001
|
||||
```
|
||||
|
||||
## Testar MCP Gateway
|
||||
|
||||
```bash
|
||||
curl http://localhost:8300/health
|
||||
curl http://localhost:8300/v1/tools
|
||||
```
|
||||
|
||||
Executar tool:
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tenant_id": "default",
|
||||
"agent_id": "telecom_contas",
|
||||
"channel": "web",
|
||||
"tool_name": "consultar_fatura",
|
||||
"business_context": {
|
||||
"customer_key": "11999999999",
|
||||
"contract_key": "INV-001",
|
||||
"session_key": "session-001"
|
||||
}
|
||||
}' | jq
|
||||
```
|
||||
|
||||
## Como plugar no Agent Gateway
|
||||
|
||||
No handler real do `POST /gateway/message`, antes de encaminhar ao backend/runtime:
|
||||
|
||||
```python
|
||||
governed_body, headers = governance.prepare_backend_request(body)
|
||||
```
|
||||
|
||||
Ao receber resposta do backend:
|
||||
|
||||
```python
|
||||
return governance.process_backend_response(data)
|
||||
```
|
||||
|
||||
O arquivo abaixo mostra um exemplo completo:
|
||||
|
||||
```text
|
||||
apps/agent_gateway/app/routes/governed_proxy_example.py
|
||||
```
|
||||
|
||||
## Variáveis do Runtime
|
||||
|
||||
```env
|
||||
MCP_GATEWAY_ENABLED=true
|
||||
MCP_GATEWAY_URL=http://localhost:8300
|
||||
MCP_GATEWAY_TIMEOUT_SECONDS=60
|
||||
```
|
||||
|
||||
## Importante
|
||||
|
||||
Não existe `apps/ai_gateway`.
|
||||
|
||||
A governança de modelo fica no Agent Gateway como policy/metadados.
|
||||
|
||||
O Runtime continua usando os LLM providers existentes, podendo ler a política enviada pelo Gateway em:
|
||||
|
||||
```python
|
||||
state["metadata"]["model_policy"]
|
||||
```
|
||||
Reference in New Issue
Block a user