> For the complete documentation index, see [llms.txt](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/arquitectura-y-conceptos/architecture/integration/2.5_system_integration.md).

# Integración del sistema

En esta sección se detalla cómo los componentes del sistema Taína IA se integran entre sí y con sistemas externos. Se centra en los patrones de comunicación, formatos de intercambio de datos y puntos de integración entre la Interfaz de Usuario de Voice AI (frontend) y el Agente WebRTC (backend), así como sus interacciones con servicios externos.

## Puntos de integración

### 1. Integración de Frontend a Backend

La Interfaz de Usuario de Voice AI (frontend) y el Agente WebRTC (backend) se integran principalmente a través de LiveKit, un servidor WebRTC que facilita la comunicación de audio en tiempo real.

#### Puntos clave de integración:

1. **Conexión WebRTC**
   * **Protocolo**: WebRTC sobre WebSockets
   * **Servidor**: LiveKit
   * **Autenticación**: Tokens JWT generados por el backend
   * **Formato de Datos**: Flujos de audio en tiempo real y canales de datos
2. **Gestión de salas**
   * El frontend se conecta a una sala de LiveKit
   * El backend se une a la misma sala como participante
   * Los nombres de las salas se basan típicamente en identificadores de sesión

### 2. Integración de Backend con servicios externos

El Agente WebRTC se integra con varios servicios externos para proporcionar su funcionalidad:

#### Integración de Speech-to-Text (Deepgram)

* **Método de Integración**: API REST
* **Autenticación**: Clave API
* **Formato de Solicitud**: Flujo de audio o fragmentos
* **Formato de Respuesta**: JSON con resultados de transcripción
* **Configuración**:
  * Idioma: Español (`es`)
  * Modelo: Mejorado
  * Características: Puntuación, resultados provisionales

#### Integración de Text-to-Speech (ElevenLabs)

* **Método de Integración**: API REST y WebSocket para streaming
* **Autenticación**: Clave API
* **Formato de Solicitud**: JSON con texto y parámetros de voz
* **Formato de Respuesta**: Flujo de audio (MP3)
* **Configuración**:
  * ID de Voz: Voz personalizada en español dominicano
  * Modelo: eleven\_multilingual\_v2
  * Frecuencia de Muestreo: 44100Hz
  * Formato: MP3

#### Integración de Modelo de Lenguaje (Google Gemini)

* **Método de Integración**: API REST
* **Autenticación**: Clave API
* **Formato de Solicitud**: JSON con prompt, historial y parámetros de herramientas
* **Formato de Respuesta**: JSON con texto generado y llamadas a funciones
* **Configuración**:
  * Modelo: `gemini-1.5-flash`
  * Temperatura: 0.7
  * Llamada de funciones: habilitada para invocar herramientas

### 3. Integración del Sistema RAG

El sistema de Generación Aumentada por Recuperación (RAG) está integrado dentro del backend:

* **Base de Datos Vectorial**: ChromaDB (colecciones de servicios y QA)
* **Fuente de Documentos**: Pipelines de ingestión (`data/chunks/`) y generación de QA
* **Interfaz de Consulta**: Herramientas asincrónicas (`list_services`, `ask_knowledge_base`, etc.)
* **Formato de Respuesta**: JSON estructurado que el LLM resume para la conversación
* **Método de Integración**: Llamadas internas a funciones Python

## Secuencias de flujo de datos

### Flujo de interacción de voz

A grandes rasgos:

1. El usuario inicia la sesión desde el frontend (quiosco o web).
2. La UI obtiene un token JWT del backend y se conecta a LiveKit.
3. El backend se une a la sala y gestiona el audio entrante.
4. Deepgram produce la transcripción, Gemini analiza la intención y decide si invocar herramientas.
5. Las herramientas consultan ChromaDB, se genera la respuesta y ElevenLabs la sintetiza en voz.
6. El audio sale nuevamente por LiveKit hasta el dispositivo del ciudadano.

## Variantes de implementación

El sistema admite diferentes variantes de implementación para ciertos componentes:

### Variantes de TTS

1. **TTS de ElevenLabs**:
   * Implementación principal
   * Voz en español de alta calidad
   * Capacidad de streaming
2. **TTS de OpenAI**:
   * Implementación alternativa
   * Menor latencia
   * Opciones de voz limitadas

### Variantes de RAG

1. **RAG con Motor de Chat**:
   * Preservación del contexto conversacional
   * Interacciones de múltiples turnos
2. **RAG con Motor de Consulta**:
   * Respuestas factuales directas
   * Mayor precisión para consultas específicas
3. **RAG con Motor de Recuperación**:
   * Mejora dinámica del prompt del sistema
   * Contexto más completo

## Consideraciones de despliegue

1. **Requisitos de red**:
   * Conexión de baja latencia para WebRTC
   * Ancho de banda suficiente para streaming de audio
   * Conexión a internet confiable
2. **Escalabilidad**:
   * El servidor LiveKit puede escalarse horizontalmente
   * Se pueden desplegar múltiples instancias de agentes
   * Balanceo de carga para tráfico alto
3. **Monitoreo**:
   * Métricas de calidad de conexión WebRTC
   * Tiempos de respuesta de API
   * Tasas y tipos de errores


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/arquitectura-y-conceptos/architecture/integration/2.5_system_integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.