> 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/referencias-tecnicas/api/system-prompt.md). # System Prompt En esta sección se explica cómo está construido y para qué sirve el prompt de sistema definido en `backend/src/prompts.py`. El archivo describe el comportamiento base del asistente Taína y orquesta el uso de las herramientas asíncronas declaradas en `backend/src/tools.py`. * `AGENT_INSTRUCTIONS` define el rol del agente, detalla el tono, precisión, e incluye la lista de herramientas agénticas que se pueden invocar (`list_services`, `get_service_overview`, `list_service_variations`, `get_service_locations`, `get_service_digital_channel`, `get_service_contact`, `ask_knowledge_base`, `set_retriever_mode`, `get_current_date`). * `DATA_STRUCTURE_CONTEXT` documenta la forma en que el pipeline de datos entrega la información (chunks granulares por tipo de documento). * `SESSION_INSTRUCTIONS` define el saludo inicial obligatorio y el encuadre de cada nueva conversación. * `SYSTEM_CONTEXT` aporta contexto operativo (país, herramientas complementarias, protocolos de escalación). * `ERROR_HANDLING_INSTRUCTIONS` fija las respuestas frente a placeholders, vacíos de datos y fallos técnicos. * `COMBINED_PROMPT` concatena todo lo anterior en un unico bloque que consume el orquestador LLM. ### Buenas practicas * Cuando agregues nuevas funciones en `tools.py`, refleja el propósito en `AGENT_INSTRUCTIONS` para que el modelo sepa cuando usarlas. * Si cambian los campos de los chunks o se incorporan nuevos tipos de documento, ajusta `DATA_STRUCTURE_CONTEXT` con ejemplos actualizados. * Conserva la coherencia entre los mensajes de error del prompt y las respuestas estandarizadas en `tools.py` para evitar contradicciones frente al ciudadano. * Antes de desplegar cambios, valida que `COMBINED_PROMPT` siga por debajo de los limites de tokens del modelo seleccionado (genera la longitud concatenando las constantes y revisa en el entorno de inferencia). ### Desglose por sección Cada constante aborda un aspecto distinto de la personalidad y la gobernanza del asistente: unas fijan el rol y la voz, otras describen la estructura genérica de los datos, y otras dictan protocolos transversales de sesión y recuperación. Lo que sigue detalla como se concreta ese diseño en la configuración actual del prompt para Taína, pero conserva suficiente abstracción para servir como guía en futuras variaciones. #### 1. `AGENT_INSTRUCTIONS` Sus apartados clave son: * **Rol y tono**: Enmarca la función, normas de pronunciación (ej. leer teléfonos dígito a dígito) y prohíbe el uso de Markdown en la salida porque se optimiza para sintetizadores de voz. * **Uso de herramientas**: Lista explícita de las funciones disponibles en `backend/src/tools.py` y describe cuándo invocarlas. Esto alinea la convicción agéntica con la instrumentación real: * `list_services` y `list_service_variations` trabajan sobre el catálogo estructurado en `tools.py` para identificar el servicio concreto y la variación pertinente. * `get_service_overview`, `get_service_locations`, `get_service_digital_channel` y `get_service_contact` traen datos especializados que el agente debe explicar en lenguaje natural. * `ask_knowledge_base` usa el retriever activo (`_get_retriever`) para cubrir brechas con contenido semiestructurado. * `set_retriever_mode` y `list_retriever_profiles` permiten cambiar/inspeccionar el perfil de recuperación, aun cuando el prompt advierte que solo debe hacerse bajo indicación humana. * `get_current_date` obtiene la fecha actual con el formato amigable definido en `tools.py`. * **Protocolo de atención**: Especifica un flujo guiado: identificar servicio, confirmar con el ciudadano, presentar panorama general, profundizar en variaciones, entregar ubicaciones, canales y contactos, y cerrar ofreciendo escalación al asterisco 4 6 2 cuando la información es incompleta. * **Manejo de datos granulares**: Indica cómo convertir horarios, montos y direcciones en frases naturales, y enfatiza que no se repitan tecnicismos. Si requieres modificar la personalidad o ampliar la cobertura de herramientas, esta sección es el punto de entrada. Mantener el orden de uso de herramientas es importante para conservar la coherencia con la lógica de recuperación implementada en `tools.py`. #### 2. `DATA_STRUCTURE_CONTEXT` Esta constante describe la arquitectura de retrieval. Expone ejemplos concretos de cada tipo de porción de datos (`servicio_principal`, `variacion_servicio`, `ubicaciones`, `canal_digital`, `contacto`) y documenta los campos agregados por el pipeline (desglose\_de\_costos, concepto\_de\_pago, precios mínimos y máximos). El objetivo es recordarle al modelo que los documentos llegan ya limpiados (sin HTML) y que debe: * Añadir estructura conversacional sobre los datos (ej. agrupar oficinas, convertir horarios). * Explicar precios y métodos de pago con el vocabulario local. * Priorizar la relevancia según la consulta del ciudadano en lugar de enumerar todos los fragmentos recuperados. #### 3. `SESSION_INSTRUCTIONS` Define el arranque de cada sesión: saludo personalizado, solicitud de nombre y recordatorio de que el idioma siempre es español dominicano. Es útil cuando se reinicia la conversación o se crean nuevas salas en el backend de LiveKit, ya que garantiza una experiencia uniforme independientemente del estado de la memoria conversacional. #### 4. `SYSTEM_CONTEXT` Aporta información transversal (contexto geográfico, horario de atención variable, recomendación de utilizar `get_current_date`) y explica el mecanismo de escalación: cuando la consulta excede el alcance, el asistente debe ofrecer canales oficiales y describir los pasos a seguir. Esto se alinea con los mensajes de error en `tools.py`, que redirigen al ciudadano hacia gob.do o al asterisco 4 6 2. #### 5. `ERROR_HANDLING_INSTRUCTIONS` Cubre tres escenarios: 1. `ask_knowledge_base` sin resultados: instruye a explicar la limitación y ofrecer alternativas. 2. Problemas técnicos: solicita mantener calma y brindar canales alternativos. 3. Preguntas fuera de alcance: invita a redirigir cortésmente. Varios de estos mensajes concuerdan con las constantes `ERROR_RESPONSES` de `tools.py`, asegurando que las respuestas del modelo sean consistentes con los mensajes de error generados por las herramientas. #### 6. `COMBINED_PROMPT` Es la versión final del prompt. Concatena las secciones anteriores mediante un f-string multilínea. Esta constante suele ser la que se pasa directamente al inicializar el modelo de lenguaje en la capa de orquestación. Gracias a la concatenación con `DATA_STRUCTURE_CONTEXT`, `SYSTEM_CONTEXT` y `ERROR_HANDLING_INSTRUCTIONS`, el LLM recuerda el formato de los documentos recuperados y el comportamiento esperado frente a fallas. ### Interacción con `backend/src/tools.py` El prompt no ejecuta las herramientas, pero define el marco narrativo para que el modelo las utilice correctamente: * La estrategia de descubrimiento de servicios descrita en el prompt depende de `list_services`, que filtra el catálogo cargado por `load_service_catalog` y ordena según score semántico. * Una vez confirmado el servicio, el agente usa `get_service_overview` y `list_service_variations`; ambos emplean `_get_documents_by_filter` para leer la base Chroma con el perfil `chunks` o `qa` segun disponibilidad. * Para información operativa se activan `get_service_locations`, `get_service_digital_channel` y `get_service_contact`. Estas funciones formatean los documentos (conversión de enlaces en `enlace_lectura`, sanitización de teléfonos, parsing de horarios) y devuelven JSON listo para ser reformulado en lenguaje natural. * Cuando las consultas no se resuelven con los chunks estructurados, el prompt alienta el uso de `ask_knowledge_base`, que ejecuta `retriever.invoke` con timeout y maneja errores de la misma manera que se documenta en la sección de fallos. * El prompt recuerda no cambiar el perfil de búsqueda salvo indicación humana porque `set_retriever_mode` y `reset_retriever` implican reinicializar embeddings y pueden impactar el tiempo de respuesta. * La referencia constante al asterisco 4 6 2 coincide con los mensajes de fallback que `tools.py` regresa cuando no encuentra información o detecta placeholders. Con esta información puedes ubicar rápidamente cada sección del prompt y entender cómo se relaciona con la implementación de herramientas asíncronas en `backend/src/tools.py`. Mantener ambas piezas sincronizadas garantiza que la experiencia ciudadana sea consistente y que el asistente aproveche al máximo los datos ya normalizados por el pipeline. --- # 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/referencias-tecnicas/api/system-prompt.md?ask=&goal= ``` `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.