4.3 KiB
Agent Platform OCI — Manual Oficial de Agent Gateway e MCP Gateway
Objetivo
Este documento consolida:
- Arquitetura oficial
- Inventário dos componentes
- Procedimento completo de execução local
- MCP Gateway
- Agent Gateway
- Backend Runtime
- Frontend
- Testes E2E
- Troubleshooting
- Decisões arquiteturais
Arquitetura Oficial
Frontend (5173) ↓ Agent Gateway (9000) ↓ Agent Template Backend / Runtime (8000) ↓ MCP Gateway (8300) ↓ Telecom MCP Server (8100) Retail MCP Server (8200)
Não existe AI Gateway.
Portas Oficiais
| Componente | Porta |
|---|---|
| Frontend | 5173 |
| Agent Gateway | 9000 |
| Backend Runtime | 8000 |
| MCP Gateway | 8300 |
| Telecom MCP Server | 8100 |
| Retail MCP Server | 8200 |
Variáveis Oficiais
Agent Template Backend
ENABLE_MCP_TOOLS=true
MCP_GATEWAY_ENABLED=true MCP_GATEWAY_URL=http://localhost:8300 MCP_GATEWAY_TIMEOUT_SECONDS=60 MCP_GATEWAY_AGENT_ID=telecom_contas MCP_GATEWAY_TENANT_ID=default
Agent Gateway
DEFAULT_AGENT_BACKEND_URL=http://localhost:8000 AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
MCP Gateway
MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
Ordem de Inicialização
- Telecom MCP Server
- Retail MCP Server
- MCP Gateway
- Agent Template Backend
- Agent Gateway
- Frontend
Terminal 1 — Telecom MCP Server
cd mcp/servers/telecom_mcp_server
python -m venv .venv source .venv/bin/activate pip install -r requirements.txt
python -m uvicorn main:app --host 0.0.0.0 --port 8100 --reload
Validação:
curl http://localhost:8100/health
Terminal 2 — Retail MCP Server
cd mcp/servers/retail_mcp_server
python -m venv .venv source .venv/bin/activate pip install -r requirements.txt
python -m uvicorn main:app --host 0.0.0.0 --port 8200 --reload
Validação:
curl http://localhost:8200/health
Terminal 3 — MCP Gateway
cd 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
python -m uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
Validações:
curl http://localhost:8300/health curl http://localhost:8300/ready curl http://localhost:8300/v1/tools
Teste:
curl -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke
Terminal 4 — Agent Template Backend
cd templates/agent_template_backend
python -m venv .venv source .venv/bin/activate pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
Validações:
curl http://localhost:8000/health curl http://localhost:8000/agents
Terminal 5 — Agent Gateway
cd apps/agent_gateway
python -m venv .venv source .venv/bin/activate pip install -r requirements.txt
export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000 export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
python -m uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
Validações:
curl http://localhost:9000/health
Teste:
curl -X POST http://localhost:9000/gateway/message
Terminal 6 — Frontend
cd agent_frontend
npm install
npm run dev -- --host 0.0.0.0 --port 5173
Abrir:
Backend URL:
Fluxo de Tools
Agent ↓ MCPToolRouter ↓ MCPGatewayClient ↓ MCP Gateway ↓ MCP Server
Teste Integrado E2E
Frontend ↓ Agent Gateway ↓ Backend Runtime ↓ MCP Gateway ↓ Telecom MCP Server
Resultado esperado:
- Agent Gateway recebe requisição
- Runtime executa LangGraph
- MCP Gateway resolve tool
- MCP Server responde
- Usuário recebe resposta
Troubleshooting
Backend chamando MCP Server direto
Confirmar:
MCP_GATEWAY_ENABLED=true
MCP_GATEWAY_URL=http://localhost:8300
Porta incorreta
A porta oficial do MCP Gateway é:
8300
Agent Gateway não encontra Backend
Validar:
curl http://localhost:8000/health
MCP Gateway não encontra MCP Server
Validar:
curl http://localhost:8100/health curl http://localhost:8200/health
Decisões Arquiteturais Oficiais
- Não existe AI Gateway
- Agent Gateway centraliza governança
- Runtime executa LangGraph
- Runtime executa LLM
- MCP Gateway centraliza tools
- MCP Servers executam tools
- Backend usa MCP Gateway
- gateway_runtime.env.example foi removido
- MCP_GATEWAY_* fica no .env do backend
- Porta oficial MCP Gateway = 8300