Mejores prácticas para el diseño de contexto.

La contextualización efectiva garantiza que tu agente tenga acceso al conocimiento correcto, en el momento correcto, para la tarea en cuestión. Cuando se implementa correctamente, aumenta la precisión, mejora el rendimiento y reduce los costes de tokens.

Esta sección describe cómo configurar y mantener tus fuentes de contexto mediante Contextualización, incluidas las mejores prácticas para la configuración del índice, el diseño de esquemas y la evaluación continua.

Para obtener detalles sobre el servicio de Contextualización, consulta la documentación dedicada: Acerca de la contextualización.

Comprender qué es la contextualización

Los agentes se conectan al conocimiento de la empresa, como documentos, preguntas frecuentes, correos electrónicos y SOP, a través de Contextualización. Creas índices en Orchestrator y los adjuntas a agentes en Studio Web para habilitar esta conexión.

La contextualización ayuda a los agentes a:

• Razonar sobre datos específicos de la empresa.
• Evitar las alucinaciones o las invenciones.
• Responder con conocimiento actualizado y controlado.
• Citar fuentes cuando están configurados con restricciones de esquema.

Mejores prácticas para configurar la contextualización

Para crear agentes fiables y receptivos, sigue estas prácticas básicas al diseñar y ajustar tu contexto:

Usa nombres de índice descriptivos y con versiones

Da nombre a tus índices utilizando un patrón claro y coherente. Ejemplo: HR-Policies-2025-Q3.

Esto hace más fácil:

• Volver a versiones anteriores del índice.
• Realizar pruebas A/B con diferentes bases de conocimiento.
• Realizar un seguimiento de las actualizaciones a lo largo del tiempo.

Crea un nuevo índice en Orchestrator cuando el contenido cambie de forma significativa y actualiza la definición de agente en consecuencia.

Elige el modo de ingestión correcto

Al crear un índice, selecciona el modo de ingestión adecuado para tu contenido:

• Modo básico: ideal para documentos con texto mayormente sin formato.
• Modo avanzado: úsalo para archivos que combinan texto e imágenes (por ejemplo, archivos PDF escaneados o infografías).

Esto afecta tanto a la cobertura como al coste relacionado con el OCR. Elige en función del tipo de documentos y de la importancia del contenido visual para la recuperación.

Mantener cadencia de sincronización regular

Mantener los índices actualizados garantiza que los agentes hagan referencia a información actualizada. Usa la acción Sincronizar en Orchestrator o la actividad Actualizar índice de Contextualización en Studio para actualizar los contenidos del índice. Puedes programar sincronizaciones periódicas en función de la frecuencia de actualización de tu contenido de origen.

Calibrar el número de resultados y la puntuación de umbral

• Número de resultados: ajusta esta configuración para controlar cuántos fragmentos de contexto se recuperan. Más resultados aumentan la recuperación, pero también amplían el uso de tokens.
• Umbral: filtra el contexto de baja relevancia. El valor predeterminado es 0. Puedes aumentarlo para mejorar la precisión si se devuelven demasiados pasajes no relacionados. Sin embargo, ten en cuenta que establecer el valor de umbral por encima de 0 (cero) significa que se pueden filtrar fragmentos relevantes de las respuestas, lo que puede provocar alucinaciones.

Equilibra estos parámetros para garantizar un contexto de alta relevancia sin exceder los límites de tokens.

Usa descripciones de contexto claras en el diseño de agentes

Al añadir un índice de contexto a un agente, proporciona una descripción breve y precisa de lo que contiene el índice. Esto ayuda a guiar la recuperación y el uso del conocimiento por parte del agente durante la ejecución.

Las descripciones son particularmente útiles cuando se utilizan varias fuentes de contexto.

Alinear el esquema con las expectativas del agente

Define un esquema de respuesta cuando sea necesario, especialmente para salida estructurada como JSON. Esto garantiza que el agente formatee las respuestas correctamente y solo incluya información del contexto.

Incluye ejemplos de esquemas en tu solicitud del sistema para mejorar la fiabilidad.

Cuándo y cómo iterar

Revisar la configuración de contexto cuando:

• Los agentes no tienen los resultados esperados.
• Aparece contenido irrelevante en los seguimientos.
• Los agentes superan los límites de tokens o fallan con errores "límite de tokens excedido".
• Cambios de esquemas de documento.
• Se produce un nuevo caso de uso o expansión del ámbito.

Usa registros de seguimiento de ejecuciones de prueba y producción para diagnosticar si el problema está con la calidad del contexto, la cantidad o los parámetros de indexación.

Errores comunes y cómo solucionarlos

Usa esta tabla para identificar y resolver problemas comunes de contextualización. Cada fila resalta una señal de detección que puedes observar en los seguimientos y las acciones recomendadas para corregirla.

Tabla 1. Solución de problemas de contextualización

Error	Señal de detección	Corrección recomendada
El agente no responde como se esperaba, a pesar de que debería tener documentos relevantes en el índice	No se encontraron resultados	Confirmar los datos más recientes, añadir documentos relevantes y sincronizar el índice.
Faltan respuestas esperadas	Seguimiento muestra un filtrado de umbral alto	Reducir el umbral o mejorar la cobertura de documentos
Desbordamiento de ventana de contexto	Fallo del agente con "límite de tokens excedido"	Reducir el número de resultados o acortar la entrada del usuario
Información obsoleta devuelta	El seguimiento muestra una marca de tiempo obsoleta	Sincronizar o reconstruir el índice; volver a publicar el agente

Evaluación de la calidad del contexto

Usa ejecuciones de evaluación en Agent Builder para probar qué tan bien tus fuentes de contexto admiten los objetivos del agente.

Las ejecuciones de evaluación deberían:

• Incluir solicitudes diversas y del mundo real.
• Revisar los seguimientos para inspeccionar qué fragmentos se recuperaron.
• Incluir pruebas de regresión al actualizar o reemplazar índices.

También puedes simular ejecuciones utilizando simulaciones de herramientas con contexto simulado para evaluar el rendimiento antes de comprometerte con una actualización completa del índice.

Lista de verificación resumen

Usa la siguiente lista de verificación para asegurarte de que tu configuración de contextualización siga las mejores prácticas:

• Los nombres de índice están versionados y son descriptivos.
• El modo de ingestión coincide con el tipo de documento.
• Los índices se sincronizan con regularidad.
• El número de resultados y el umbral están ajustados.
• Las descripciones de contexto son informativas.
• El esquema se define y se aplica en la solicitud.
• Los errores comunes se rastrean y se resuelven mediante registros de seguimiento.

Ejemplo de plantillas de solicitud

Usa las siguientes plantillas como punto de partida para tu solicitud del Sistema de agente. Personalízalas para que se ajusten a tu caso de uso específico.

Control de calidad/Búsqueda de conocimiento

Eres un asistente de conocimiento empresarial.

Objetivo: responder a las preguntas de los usuarios utilizando SOLO documentos de la empresa aprobados.

Restricciones:

• Cite cada respuesta con el título de origen y la sección.
• Si la confianza es baja o no se recuperó ningún contexto relevante, haga una pregunta aclaratoria en lugar de adivinar.
• Responder en Markdown a menos que se solicite JSON.

Pasos de procesamiento

1. Interpreta la pregunta del usuario.
2. Revise el contexto recuperado a continuación.
3. Utilizar solo información encontrada en contexto; no fabriques.
4. Proporciona una respuesta concisa y cita las fuentes.

Extracción y validación estructurada

Eres un agente de extracción que asigna el contenido del documento a un esquema estructurado.

Objetivo: rellenar todos los campos obligatorios a partir de fragmentos de documentos recuperados.

Restricciones:

• Devuelve un JSON válido que coincida con el esquema.
• Usar nulo si no se encuentra el campo; NO adivine.
• Proporcione una puntuación de confianza de 0‑1 para cada campo.
• Incluir metadatos de source_span (doc_id, fragment_id).

Pasos

1. Leer instrucciones de usuario para el tipo de documento de destino.
2. Revisar el contexto recuperado.
3. Extraer campos.
4. Validar los campos obligatorios; solicitar una escalada si faltan valores críticos.

Razonamiento y selección de acción

Es un agente de triaje de operaciones.

Objetivo: decidir la siguiente mejor acción en función de las políticas y los detalles del caso actual.

Restricciones:

• Elija solo de la lista de acciones permitidas.
• Proporciona una breve justificación.
• Salida como JSON: {"action":string,"reason":string,"evidence_sources":[...]}

Acciones permitidas

{{ACTION_LIST}}