Name: Nombre descriptivo que refleje el propósito de la cola (por ejemplo, "Revisión de evaluaciones fallidas - Q1 2026")
Project: Proyecto Agent Observability al que pertenece esta cola
Description (opcional): Explique el propósito de la cola y cualquier instrucción especial para los anotadores
Luego haga clic en Next.
En la pestaña Schema, defina el esquema de etiquetas de su nueva cola. Use el panel de Vista previa para ver cómo aparecen las etiquetas para los anotadores a medida que las configura. Cada etiqueta puede marcarse como obligatoria y puede incluir opcionalmente:
Assessment criteria: Permita que los anotadores indiquen aprobado/reprobado para ese valor de etiqueta
Reasoning: Permita que los anotadores agreguen una breve explicación
Revise la configuración de su cola y haga clic en Create para crear la cola.
Paso 2: Seleccione trazas para la anotación
Puede crear y agregar trazas a la cola manualmente desde Trace Explorer o completar colas automáticamente usando Automation Rules.
Agregue trazas a una cola manualmente desde Trace Explorer:
Filtre las trazas usando las facetas disponibles (resultados de evaluación, estado de error, aplicación, rango de tiempo)
Seleccione trazas individuales o seleccione varias trazas de forma masiva
Haga clic en Flag for Annotation
Elija Create New Queue o seleccione una cola existente
En lugar de seleccionar trazas manualmente, utilice Automation Rules para enrutar trazas a las colas de anotación automáticamente según filtros y criterios de muestreo. Esto permite una población de colas continua y automática sin necesidad de seleccionar trazas manualmente. Consulte Automation Rules para obtener la referencia completa de la función, incluidos los campos de filtro admitidos y los límites.
Automations se aplican de ahora en adelante: las nuevas trazas que coincidan con su regla se enrutan a la cola a medida que llegan. Las trazas existentes que coincidan con el filtro no se agregan de forma retroactiva.
Para añadir una acción de cola de anotación a una Automation Rule:
Aplique filtros para identificar las trazas que desea enrutar (errores de evaluación, umbrales de latencia, aplicaciones específicas). Consulte Automation Rules > Supported filter fields para ver lo que está permitido.
Haga clic en Automate Query
Configure la tasa de muestreo (hasta un 5% para las colas de anotación; por ejemplo, el 2% de las trazas coincidentes).
En Actions, seleccione Add to Annotation Queue.
Elija la cola de destino.
Guarde la regla.
Las trazas que coincidan con los filtros de la regla se añaden a la cola a medida que llegan. Las colas de anotación contienen hasta 1,000 registros; la automatización se pausa cuando la cola alcanza ese límite.
Anotación de trazas
Acceso a sus colas
Navegue a AI Observability > Experiment > Annotations para ver todas las colas de anotación disponibles. Haga clic en una cola para ver la lista de trazas, luego haga clic en Review para comenzar a anotar.
Nota: Cuando se le asigna una nueva tarea de anotación, Datadog envía un correo electrónico con el nombre de la cola, el usuario que la asignó y un enlace directo para abrir la interacción asignada. Para optar por no participar, deshabilite los correos electrónicos de asignación de anotaciones de Agent Observability en Suscripciones de correo electrónico de Configuración personal.
El Modo de revisión muestra:
Full trace context (panel derecho):
Árbol de tramos completo con entradas, salidas y metadatos
Llamadas a herramientas y pasos de razonamiento intermedios
Resultados de la evaluación en la traza y en los tramos individuales
Annotation controls (panel izquierdo):
Etiquetas configuradas para esta cola
Indicador de progreso que muestra la posición en la cola
Controles de navegación (Anterior, Siguiente)
Aplicación de etiquetas
Para cada traza:
Revise el contexto completo de la traza: Expanda los tramos según sea necesario para comprender las entradas, salidas, llamadas a herramientas y resultados de evaluación.
Aplique etiquetas: Complete las etiquetas configuradas según su evaluación.
Las anotaciones se guardarán automáticamente.
Mejores prácticas para la anotación
Sea consistente:
Revise la descripción de la cola y las definiciones de las etiquetas antes de comenzar.
Cuando varios anotadores trabajen en la misma cola, establezca un entendimiento compartido de los criterios.
Documente el razonamiento en las notas para casos límite.
Proporcione razonamiento:
Utilice notas de formato libre para documentar por qué aplicó etiquetas específicas.
Observe los patrones que note en múltiples trazas.
El razonamiento ayuda a refinar los criterios de evaluación y a comprender los modos de falla.
Administración de colas
Seguimiento del progreso de la cola
La página de lista de Anotaciones muestra una barra de progreso para cada cola que indica la proporción de interacciones revisadas respecto al total de interacciones. Utilice esto para monitorear el progreso de la anotación en todas las colas de un vistazo.
Administración del acceso a la cola
Los propietarios de la cola administran la lista de revisores, la configuración de acceso y las asignaciones desde los detalles de la cola. Solo el propietario de la cola puede cambiar la lista de revisores, la configuración de acceso o las asignaciones.
Las restricciones de acceso se aplican de forma independiente, por lo que puede habilitar una restricción, la otra o ambas:
La restricción de revisor limita las interacciones no asignadas a los revisores designados.
La restricción de asignado limita las interacciones asignadas a sus asignados.
Cuando ambas restricciones están habilitadas, los revisores pueden anotar interacciones no asignadas y los asignados pueden anotar sus interacciones asignadas.
El propietario de la cola conserva el acceso y puede anotar todas las interacciones.
Filtrado de trazas por etiquetas de anotación
use la faceta Annotation Labels para filtrar trazas por etiquetas aplicadas en colas de anotación. Esto le permite:
Encontrar todas las trazas etiquetadas con un modo de falla específico (por ejemplo, failure_type: hallucination)
Crear muestras específicas para revisión posterior, creación de conjuntos de datos o exportación a CSV para análisis de datos
Edición del esquema de la cola
Puede modificar el esquema de etiquetas de una cola después de su creación:
El archivo se descarga como annotations_<queue-id>.csv. También puede recuperar datos de tramo mediante programación utilizando la Export API.
Formato CSV
Cada fila representa una interacción anotada. El archivo comienza con estas columnas fijas:
Columna
Descripción
Content ID
ID del contenido anotado (por ejemplo, un ID de traza o ID de sesión)
Type
Tipo de interacción: trace, experiment_trace o session
Input
Resumen de entrada (vacío para interacciones de sesión)
Output
Resumen de salida (vacío para interacciones de sesión)
Expected Output
Solo presente cuando Include Expected Output está habilitado; completado solo para trazas de experimento
Después de las columnas fijas, hay un conjunto de columnas por revisor por etiqueta. Los revisores se ordenan alfabéticamente por nombre de visualización (los espacios se reemplazan con guiones bajos). Las etiquetas siguen el orden definido en el esquema de la cola:
Columna
Descripción
{reviewer}_{label}
Valor de la etiqueta (cadena, número, booleano o matriz JSON)
{reviewer}_{label}_assessment
pass o fail, si los criterios de evaluación están habilitados para esa etiqueta
{reviewer}_{label}_reasoning
Razonamiento de texto libre, si el razonamiento está habilitado para esa etiqueta
Si un revisor no ha anotado una fila determinada, esas celdas están vacías.
Ejemplo: una cola con los revisores Alice Johnson y Bob Smith y las etiquetas quality (puntuación) y failure_type (categórica) produce estos encabezados de columna:
Después de exportar los datos de anotación, utilice la Export API para recuperar los datos completos de los tramos para las trazas o sesiones en el CSV y únalos con sus etiquetas de anotación.
Establezca el expected output del conjunto de datos:
From interaction: utilice la salida real de cada traza. Para las trazas de experimentos, también puede elegir Expected output para utilizar la salida esperada original del conjunto de datos fuente del experimento.
From annotation label: utilice los valores que aplicaron los anotadores. Elija una o más etiquetas. El expected_output del registro se crea a partir de su selección.
Elija un conjunto de datos existente o cree uno.
Cuando la salida esperada se construye a partir de etiquetas de anotación, el valor exportado es un objeto JSON con claves basadas en el nombre de la etiqueta, por ejemplo { "is_harmful": false, "tone": ["neutral"], "topics": ["safety", "policy"] }. La misma forma se aplica tanto si selecciona una etiqueta como si selecciona varias. Las etiquetas categóricas siempre se exportan como matrices de opciones seleccionadas, independientemente de si la etiqueta es de selección única o múltiple.
Cómo se agregan los valores de anotación entre los anotadores
Cuando varios anotadores han anotado la misma traza, el valor de cada etiqueta se agrega entre ellos por consenso:
Tipo de etiqueta
Agregación
Booleano
Voto mayoritario (los empates se resuelven a favor de true)
Categórico
Intersección: el conjunto ordenado de opciones que todos los anotadores seleccionaron
Puntaje
Promedio
Texto
Lista de respuestas
Para etiquetas categóricas (selección única o múltiple), el valor agregado es la matriz ordenada de opciones que todos los anotadores seleccionaron. Si la selección de algún anotador difiere, el valor es una matriz vacía. El resultado siempre es una matriz, incluso cuando solo un anotador ha anotado la traza.
Ejemplo: categórico (consenso). Tres anotadores califican tone y todos están de acuerdo:
Anotador A: polite
Anotador B: polite
Anotador C: polite
Agregado: ["polite"].
Ejemplo: categórico (desacuerdo). Tres anotadores califican tone y uno difiere:
Anotador A: polite
Anotador B: rude
Anotador C: polite
Agregado: []. La intersección está vacía porque rude no está en el conjunto de cada anotador.
Ejemplo: categórico (selección múltiple). Tres anotadores etiquetan topics (cada uno puede elegir múltiples opciones):
Anotador A: ["safety", "policy"]
Anotador B: ["safety", "billing"]
Anotador C: ["safety", "policy"]
Agregado: ["safety"]. Solo safety aparece en el conjunto de cada anotador; policy falta en la selección de B y billing falta en las de A y C.
Ejemplo: texto. Dos anotadores dejan notas:
Anotador A: "Confusing phrasing"
Anotador B: "Tone too casual"
Agregado: ["Confusing phrasing", "Tone too casual"]. El valor de cada anotador se conserva.
Los valores sin procesar por anotador se conservan en los metadatos de cada registro, junto con la identidad del anotador. Si el consenso predeterminado no se ajusta a su flujo de trabajo, puede volver a calcularlo con una estrategia diferente (por ejemplo, mediana, voto ponderado o selección del revisor).
Las etiquetas que no se seleccionan como resultado esperado también se incluyen con cada traza como metadatos.
Consulte Datasets para obtener más información sobre el uso de conjuntos de datos en experimentos.
Eliminar una cola elimina la cola y las asociaciones de etiquetas, pero no elimina las trazas subyacentes de Agent Observability. Las trazas permanecen accesibles en Trace Explorer.
Cree una cola de anotación. name y project_id son obligatorios. Incluya un annotation_schema opcional para definir etiquetas al momento de la creación.
Cree o reemplace el esquema de etiquetas para una cola.
Retención de datos
Datos
Período de retención
Trazas en colas
Limitado por el período de retención de trazas de su organización
Etiquetas de anotación
Indefinido
Flujos de trabajo de ejemplo
Análisis de errores y descubrimiento de modos de falla
Revise las trazas fallidas para identificar patrones recurrentes y categorizar cómo falla su aplicación en producción.
Filtre las trazas en Trace Explorer para evaluaciones fallidas o patrones de error específicos
Seleccione manualmente las trazas y agréguelas a una cola de anotación
Los anotadores revisan las trazas y documentan los tipos de falla en notas de formato libre
Surgen patrones comunes: alucinaciones en contextos específicos, problemas de formato, rechazos inapropiados
Cree etiquetas categóricas para los modos de falla identificados y vuelva a codificar las trazas
Utilice la distribución de modos de falla para priorizar las correcciones
Configuración de cola
Etiquetas: Notas de formato libre, etiqueta failure_type categórica, calificación de aprobado/reprobado
Anotadores: Gerentes de producto, ingenieros, expertos en el dominio
Validación de evaluaciones de LLM-as-a-judge
Encuentre las trazas donde los evaluadores automatizados puedan ser inciertos o incorrectos, luego haga que los humanos proporcionen la verdad de referencia.
Muestree resultados de evaluación: todos los resultados, o una puntuación/umbral determinado
Agregue las trazas seleccionadas a una cola de anotación
Los anotadores revisan las trazas y proporcionan puntuaciones humanas para los mismos criterios
Compare las etiquetas humanas con las puntuaciones de evaluación automatizadas
Identifique desacuerdos sistemáticos (juez demasiado estricto, demasiado indulgente o que malinterpreta los criterios)
Refine los prompts de evaluación basándose en los desacuerdos
Configuración de cola
Etiquetas: Puntuaciones numéricas que coinciden con los criterios de evaluación (0-10), etiqueta categórica judge_accuracy, notas de razonamiento
Anotadores: Expertos en la materia que comprenden los criterios de evaluación
Creación de conjuntos de datos de referencia
Cree conjuntos de datos de referencia con etiquetas verificadas por humanos para pruebas de regresión y validación continua.
Muestree diversas trazas de producción de Trace Explorer (ejemplos buenos y malos)
Agregue trazas a la cola de anotación
Los anotadores revisan y etiquetan las trazas en múltiples dimensiones de calidad
Agregue ejemplos bien etiquetados y de alta confianza al conjunto de datos de referencia
Utilice el conjunto de datos para pruebas de regresión de CI/CD de cambios en los prompts
Amplíe continuamente el conjunto de datos con nuevos casos extremos
Configuración de cola
Etiquetas: Múltiples etiquetas categóricas que cubren dimensiones de calidad, puntuaciones numéricas, calificación de aprobado/reprobado, notas
Anotadores: Equipo de expertos en el dominio para la consistencia
Lecturas adicionales
Documentación, enlaces y artículos útiles adicionales:
