Skip to content

🌐 Open WebUI Integration Plan

Data: 13/02/2026
Branch: feature/open-webui
Objetivo: Integrar iFriend Agent com Open WebUI para interface de chat profissional

📊 Análise - Open WebUI

Open WebUI é uma plataforma self-hosted de chat AI com: - ✅ Interface moderna (Svelte + Python/FastAPI) - ✅ Suporte a Ollama e OpenAI-compatible APIs - ✅ Pipelines Plugin Framework - extensibilidade via Python - ✅ RAG, Web Search, Custom Functions - ✅ Multi-model conversations - ✅ Authentication (LDAP, OAuth, SSO) - ✅ 124k+ stars no GitHub

Repositório: https://github.com/open-webui/open-webui
Documentação: https://docs.openwebui.com/

🎯 Objetivos da Integração

  1. UI Profissional: Usar Open WebUI como frontend moderno para iFriend Agent
  2. Preservar Funcionalidades: Manter todas as ferramentas customizadas (busca produtos, booking, email, etc.)
  3. Multi-Plataforma: Open WebUI + Slack + WhatsApp + Telegram funcionando simultaneamente
  4. JWT Authentication: Integrar autenticação JWT do iFriend com Open WebUI
  5. Sessões Compartilhadas: Mesma sessão acessível via Open WebUI e outras plataformas

🔀 Abordagens de Integração

Abordagem 1: OpenAI-Compatible API ⭐ RECOMENDADA

Conceito: Expor iFriend Agent como API compatível com OpenAI Chat Completions

Vantagens: - ✅ Open WebUI já suporta OpenAI-compatible APIs nativamente - ✅ Zero modificação no Open WebUI - ✅ Reutiliza toda infraestrutura iFriend (tools, session, memory) - ✅ Funciona com qualquer cliente OpenAI-compatible

Implementação: 

┌─────────────────┐
│   Open WebUI    │ (Frontend)
└────────┬────────┘
         │ POST /v1/chat/completions
         │ (OpenAI format)
         ▼
┌─────────────────┐
│ ifriend-agents/ │
│ open-webui/     │
│  openai_api.py  │ (OpenAI-compatible API)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Google ADK     │
│  Runner +       │
│  iFriend Tools  │
└─────────────────┘

Arquivos Necessários: - open-webui/openai_api.py - FastAPI endpoints compatíveis com OpenAI - open-webui/openai_adapter.py - Adapter para converter OpenAI ↔ iFriend - open-webui/streaming.py - Suporte a streaming SSE - open-webui/config.py - Configurações específicas Open WebUI

Abordagem 2: Open WebUI Pipeline

Conceito: Criar um Pipeline customizado que se comunica com iFriend Agent

Vantagens: - ✅ Integração oficial via Pipelines Framework - ✅ Suporte a functions/tools - ✅ Middleware capabilities (rate limiting, logging)

Desvantagens: - ⚠️ Requer Open WebUI Pipelines instalado separadamente - ⚠️ Mais complexo - duas instâncias rodando

Implementação: 

┌─────────────────┐
│   Open WebUI    │
└────────┬────────┘
         │ via Pipelines
         ▼
┌─────────────────┐
│  Pipelines      │
│  ifriend.py     │ (Custom Pipeline)
└────────┬────────┘
         │ HTTP/gRPC
         ▼
┌─────────────────┐
│  unified_bot.py │
│  iFriend Agent  │
└─────────────────┘

Abordagem 3: Direct WebChat Adapter (Menos recomendada)

Conceito: Open WebUI consome diretamente nosso WebChat endpoint

Desvantagens: - ❌ Não aproveita recursos nativos do Open WebUI - ❌ Requer modificação pesada no Open WebUI frontend - ❌ Não recomendado

🏗️ Arquitetura Proposta (Abordagem 1)

Stack Completo

┌────────────────────────────────────────────────────────────┐
│                      OPEN WEBUI                            │
│  - Svelte Frontend (UI moderna)                            │
│  - Auth (OAuth, JWT, LDAP)                                 │
│  - User Management                                         │
│  - Chat History                                            │
└────────────────────┬───────────────────────────────────────┘
                     │
                     │ POST /v1/chat/completions
                     │ Authorization: Bearer <JWT>
                     │
┌────────────────────▼───────────────────────────────────────┐
│           IFRIEND OPENAI-COMPATIBLE API                    │
│  open-webui/                                               │
│    ├── openai_api.py         (FastAPI app)                 │
│    ├── openai_adapter.py     (Format converter)            │
│    ├── streaming.py          (SSE streaming)               │
│    └── config.py             (Config)                      │
└────────────────────┬───────────────────────────────────────┘
                     │
                     │ Uses existing components
                     │
┌────────────────────▼───────────────────────────────────────┐
│              IFRIEND AGENT (Existing)                      │
│  - Google ADK Runner                                       │
│  - JWT Context Manager                                     │
│  - Session Service (Redis/CloudSQL)                        │
│  - Memory Service                                          │
│  - 17+ Custom Tools                                        │
│  - Messaging Adapters (Slack, WhatsApp, etc.)             │
└────────────────────────────────────────────────────────────┘

📦 Estrutura de Pastas Proposta

ifriend-agents/
├── openwebui/                        # 🆕 Pasta específica Open WebUI
│   ├── __init__.py
│   ├── README.md                     # Documentação de integração
│   ├── config.py                     # Configurações Open WebUI
│   ├── openai_api.py                 # FastAPI OpenAI-compatible endpoints
│   ├── openai_adapter.py             # Converter: OpenAI ↔ iFriend
│   ├── streaming.py                  # SSE streaming support
│   ├── auth.py                       # JWT integration with Open WebUI
│   ├── tools_formatter.py            # Format iFriend tools → OpenAI functions
│   ├── docker-compose.openwebui.yaml # Deploy completo (Open WebUI + iFriend)
│   ├── .env.openwebui.example        # Env vars específicas
│   └── tests/
│       ├── test_openai_api.py
│       ├── test_streaming.py
│       └── test_tools_format.py
│
├── unified_bot.py                    # ✅ Existente (pode montar OpenAI API aqui tb)
├── messaging/                        # ✅ Existente
├── ifriend_agent/                    # ✅ Existente
└── docs/
    └── OPENWEBUI_INTEGRATION_PLAN.md # 🆕 Este arquivo

🛠️ Fase de Implementação

Fase 1: OpenAI API Base (2 dias)

Objetivo: Criar API compatível com OpenAI Chat Completions

1.1. Endpoint /v1/chat/completions

  • ✅ Receber request formato OpenAI
  • ✅ Converter para iFriend format
  • ✅ Invocar Google ADK Runner
  • ✅ Retornar response formato OpenAI

Arquivo: openwebui/openai_api.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional

app = FastAPI()

class ChatMessage(BaseModel):
    role: str  # "system", "user", "assistant"
    content: str

class ChatCompletionRequest(BaseModel):
    model: str
    messages: List[ChatMessage]
    temperature: Optional[float] = 0.2
    stream: Optional[bool] = False
    functions: Optional[List[dict]] = None

@app.post("/v1/chat/completions")
async def chat_completions(request: ChatCompletionRequest):
    # 1. Extract JWT from Authorization header
    # 2. Convert OpenAI messages → iFriend format
    # 3. Invoke ADK Runner
    # 4. Convert iFriend response → OpenAI format
    # 5. Return response
    pass

1.2. Adapter OpenAI ↔ iFriend

Arquivo: openwebui/openai_adapter.py

class OpenAIAdapter:
    @staticmethod
    def openai_to_ifriend(messages: List[ChatMessage]) -> str:
        """Convert OpenAI messages to iFriend prompt"""

    @staticmethod
    def ifriend_to_openai(response: str, model: str) -> dict:
        """Convert iFriend response to OpenAI format"""
        return {
            "id": "chatcmpl-...",
            "object": "chat.completion",
            "created": int(time.time()),
            "model": model,
            "choices": [{
                "index": 0,
                "message": {
                    "role": "assistant",
                    "content": response
                },
                "finish_reason": "stop"
            }]
        }

1.3. Testes Básicos

  • ✅ Test /v1/chat/completions response format
  • ✅ Test message conversion
  • ✅ Test error handling

Fase 2: Streaming Support (1 dia)

Objetivo: Suportar streaming SSE para respostas em tempo real

2.1. Streaming SSE

Arquivo: openwebui/streaming.py

async def stream_openai_response(ifriend_response_stream):
    """
    Stream iFriend responses in OpenAI SSE format

    OpenAI format:
    data: {"choices": [{"delta": {"content": "Hello"}}]}
    data: [DONE]
    """
    async for chunk in ifriend_response_stream:
        yield {
            "choices": [{
                "index": 0,
                "delta": {"content": chunk},
                "finish_reason": None
            }]
        }

    # Final chunk
    yield {
        "choices": [{
            "index": 0,
            "delta": {},
            "finish_reason": "stop"
        }]
    }

2.2. Integrar com Google ADK Streaming

  • ✅ ADK Runner já suporta streaming
  • ✅ Converter stream ADK → OpenAI SSE

Fase 3: Tools/Functions Support (2 dias)

Objetivo: Expor ferramentas iFriend como OpenAI Functions

3.1. Tools Formatter

Arquivo: openwebui/tools_formatter.py

def ifriend_tools_to_openai_functions() -> List[dict]:
    """
    Convert iFriend tools to OpenAI function calling format

    iFriend Tool:
    - buscar_produtos_tool
    - fazer_reserva_tool
    - enviar_email_tool

    OpenAI Function:
    {
        "name": "buscar_produtos",
        "description": "Busca produtos iFriend",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "limit": {"type": "integer"}
            },
            "required": ["query"]
        }
    }
    """
    return [
        {
            "name": "buscar_produtos",
            "description": "Busca produtos no catálogo iFriend",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Termo de busca"},
                    "limit": {"type": "integer", "description": "Limite de resultados"}
                },
                "required": ["query"]
            }
        },
        # ... outras 16 ferramentas
    ]

3.2. Function Calling Flow

User: "Busca experiências em Paris"
  ↓
Open WebUI send function call request
  ↓
iFriend API executes buscar_produtos_tool
  ↓
Return function result
  ↓
Open WebUI displays result

Fase 4: JWT Integration (1 dia)

Objetivo: Integrar JWT authentication iFriend com Open WebUI

4.1. JWT Validation

Arquivo: open-webui/auth.py

from ifriend_agent.session.jwt_context import JWTContextManager

async def extract_jwt_from_openwebui(request: Request) -> Optional[str]:
    """
    Extract JWT from Open WebUI request

    Open WebUI sends: Authorization: Bearer <token>
    """
    auth_header = request.headers.get("Authorization")
    if auth_header and auth_header.startswith("Bearer "):
        return auth_header[7:]
    return None

async def validate_openwebui_jwt(jwt_token: str) -> UserContext:
    """Validate JWT using existing JWTContextManager"""
    jwt_manager = JWTContextManager()
    return await jwt_manager.get_user_context(jwt_token)

4.2. Session Context

  • ✅ Usar session_id do Open WebUI
  • ✅ Armazenar context no Redis (existing)
  • ✅ Compartilhar sessões entre Open WebUI e outras plataformas

Fase 5: Docker Compose Setup (1 dia)

Objetivo: Deploy completo Open WebUI + iFriend

5.1. Docker Compose

Arquivo: openwebui/docker-compose.openwebui.yaml

version: '3.8'

services:
  # Open WebUI Frontend
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "3000:8080"
    environment:
      - OPENAI_API_BASE_URL=http://ifriend-openai-api:8081/v1
      - OPENAI_API_KEY=ifriend-api-key  # Fake key, JWT usado
    depends_on:
      - ifriend-openai-api
    networks:
      - ifriend-network

  # iFriend OpenAI-Compatible API
  ifriend-openai-api:
    build:
      context: ..
      dockerfile: open-webui/Dockerfile
    container_name: ifriend-openai-api
    ports:
      - "8081:8081"
    environment:
      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
      - REDIS_URL=redis://redis:6379/0
      - GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
      - MODEL=${MODEL}
    volumes:
      - ../ifriend_agent/service-account-key.json:/app/service-account-key.json
    depends_on:
      - redis
    networks:
      - ifriend-network

  # Redis (Shared)
  redis:
    image: redis:7-alpine
    container_name: ifriend-redis
    ports:
      - "6379:6379"
    networks:
      - ifriend-network

  # Existing unified_bot (outras plataformas)
  unified-bot:
    build:
      context: ..
      dockerfile: Dockerfile
    container_name: ifriend-unified-bot
    ports:
      - "8080:8080"
    environment:
      - SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN}
      - WHATSAPP_OFFICIAL_ACCESS_TOKEN=${WHATSAPP_OFFICIAL_ACCESS_TOKEN}
      # ... outras plataformas
    depends_on:
      - redis
    networks:
      - ifriend-network

networks:
  ifriend-network:
    driver: bridge

🔧 Variáveis de Ambiente

Arquivo: openwebui/.env.openwebui.example

# ============================================================================
# OPEN WEBUI INTEGRATION
# ============================================================================

# --- Open WebUI Configuration ---
OPENWEBUI_URL=http://localhost:3000
OPENWEBUI_ADMIN_EMAIL=admin@theifriend.com
OPENWEBUI_ADMIN_PASSWORD=changeme

# --- iFriend OpenAI API ---
IFRIEND_OPENAI_API_PORT=8081
IFRIEND_OPENAI_API_URL=http://localhost:8081/v1

# Modelo padrão exposto para Open WebUI
OPENAI_MODEL_NAME=ifriend-gemini-2.5-flash

# --- JWT (Shared with main iFriend) ---
JWT_SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256

# --- Redis (Shared) ---
REDIS_URL=redis://localhost:6379/0

# --- Google ADK (Shared) ---
GOOGLE_CLOUD_PROJECT=ifriend-platform
GOOGLE_CLOUD_LOCATION=us-central1
MODEL=gemini-2.5-flash

# --- API iFriend (para tools) ---
API_BASE_URL=https://stage.api.theifriend.com
API_EMAIL=your-email@theifriend.com
API_PASSWORD=your-password

📊 Comparação de Abordagens

Aspecto OpenAI API Pipeline Direct WebChat
Complexidade Média Alta Muito Alta
Modificações Open WebUI Zero Zero Muitas
Reutilização Código 100% 80% 60%
Manutenção Fácil Média Difícil
Streaming ✅ Nativo ✅ Via Pipeline ⚠️ Custom
Tools/Functions ✅ OpenAI Functions ✅ Pipeline Functions ❌ Limitado
Multi-Plataforma ✅ Simultâneo ✅ Simultâneo ⚠️ Conflito
Deploy 2 containers 3 containers 1 container

Recomendação: OpenAI API (Abordagem 1) ⭐

🎯 Roadmap de Implementação

Sprint 1 (1 semana)

  • [ ] Fase 1: OpenAI API Base
  • [ ] Criar estrutura open-webui/
  • [ ] Implementar /v1/chat/completions
  • [ ] Adapter OpenAI ↔ iFriend
  • [ ] Testes básicos

Sprint 2 (3 dias)

  • [ ] Fase 2: Streaming
  • [ ] SSE streaming
  • [ ] Integração com ADK streaming
  • [ ] Testes de streaming

Sprint 3 (1 semana)

  • [ ] Fase 3: Tools/Functions
  • [ ] Tools formatter (17 ferramentas)
  • [ ] Function calling flow
  • [ ] Testes de function calling

Sprint 4 (3 dias)

  • [ ] Fase 4: JWT Integration
  • [ ] JWT extraction e validation
  • [ ] Session context
  • [ ] Testes de autenticação

Sprint 5 (2 dias)

  • [ ] Fase 5: Docker Compose
  • [ ] docker-compose.openwebui.yaml
  • [ ] Dockerfile para OpenAI API
  • [ ] Documentação de deploy
  • [ ] Testes end-to-end

Total: ~3 semanas

✅ Critérios de Sucesso

  1. ✅ Open WebUI exibe interface de chat funcional
  2. ✅ Todas as 17 ferramentas iFriend acessíveis via Open WebUI
  3. ✅ Streaming de respostas em tempo real
  4. ✅ JWT authentication funcionando
  5. ✅ Sessões compartilhadas entre Open WebUI e outras plataformas
  6. ✅ Zero quebra de funcionalidades existentes (Slack, WhatsApp, etc.)
  7. ✅ Deploy via docker-compose em < 5 minutos

🚀 Benefícios

Para Usuários

  • ✅ UI Moderna: Interface profissional tipo ChatGPT
  • ✅ Multi-Device: Web, mobile PWA
  • ✅ Histórico Completo: Busca e navegação de conversas
  • ✅ Multi-Modal: Texto + imagens (futuramente)

Para Developers

  • ✅ Padrão OpenAI: Compatível com qualquer cliente OpenAI
  • ✅ Reutilização: 100% do código iFriend reutilizado
  • ✅ Extensibilidade: Fácil adicionar novas tools
  • ✅ Deploy Simples: docker-compose up

Para Negócio

  • ✅ White-Label: Open WebUI suporta branding customizado
  • ✅ Enterprise Ready: LDAP, SSO, user management
  • ✅ Self-Hosted: Controle total dos dados
  • ✅ Multi-Tenancy: Suporta múltiplos usuários

🔒 Segurança

Inherited from iFriend

  • ✅ JWT authentication (já implementado)
  • ✅ Secret management (GCP Secret Manager)
  • ✅ HTTPS enforcement

Open WebUI Security

  • ✅ Built-in authentication
  • ✅ RBAC (Role-Based Access Control)
  • ✅ Session management
  • ✅ CORS configuration

📚 Recursos

Open WebUI

  • GitHub: https://github.com/open-webui/open-webui
  • Docs: https://docs.openwebui.com/
  • Pipelines: https://github.com/open-webui/pipelines
  • Discord: https://discord.gg/5rJgQTnV4s

OpenAI API Reference

  • Chat Completions: https://platform.openai.com/docs/api-reference/chat
  • Function Calling: https://platform.openai.com/docs/guides/function-calling
  • Streaming: https://platform.openai.com/docs/api-reference/streaming

iFriend Docs

  • Messaging Architecture: docs/architecture/MESSAGING_ARCHITECTURE.md
  • JWT Implementation: docs/JWT_IMPLEMENTATION_CHECKLIST.md
  • Tools Documentation: ifriend_agent/tools/

🤔 Perguntas Frequentes

Q: Preciso modificar o Open WebUI?

A: Não! Usando OpenAI-compatible API, zero modificações.

Q: As outras plataformas (Slack, WhatsApp) continuam funcionando?

A: Sim! Open WebUI é apenas mais uma plataforma. unified_bot.py continua rodando.

Q: Como funciona a autenticação?

A: Open WebUI autentica usuários, gera JWT, envia para iFriend API que valida com JWTContextManager existente.

Q: Preciso de 2 servidores?

A: Sim, mas podem rodar no mesmo container host: - Open WebUI (porta 3000) - iFriend OpenAI API (porta 8081) - unified_bot (porta 8080) - opcional se só usar Open WebUI

Q: Qual a diferença entre unified_bot e OpenAI API?

A: - unified_bot.py: Webhooks para Slack, WhatsApp, Telegram, WebChat, SSE - open-webui/openai_api.py: OpenAI-compatible API para Open WebUI (e outros clientes)

🎬 Próximos Passos

  1. Review deste plano - Aprovação da arquitetura
  2. Criar branch - git flow feature start open-webui ✅ (já criado!)
  3. Sprint 1 - Implementar OpenAI API base
  4. Deploy teste - Validar integração
  5. Iteração - Adicionar streaming, tools, JWT

Status: 📋 PLANEJAMENTO COMPLETO
Próximo: Aprovação → Implementação Sprint 1
Estimativa Total: 3 semanas

Autor: AI Assistant
Revisão: Glauber Portella
Data: 13/02/2026