Descripción general

Datadog proporciona un conjunto de habilidades de Claude Code que llevan el análisis de Agent Observability directamente a su flujo de trabajo de desarrollo. En lugar de navegar por los dashboards manualmente, puede invocar estas habilidades desde una sesión de Claude Code para clasificar sesiones, diagnosticar fallas, comparar experimentos, generar código de experimento en Python y realizar el bootstrap de evaluadores, todo contra sus datos de producción en vivo.

Las habilidades producen resultados estructurados y accionables (informes de RCA con propuestas de corrección antes/después, código de evaluador generado, comparaciones de experimentos) que puede pasar directamente a un agente de codificación para aplicar correcciones a su aplicación. Cuando Claude Code tiene acceso a su base de código, puede buscar el prompt del sistema, las definiciones de herramientas o la lógica de enrutamiento relevantes y proponer diffs específicos sin abandonar la sesión.

Configuración

Requisitos previos

• Claude Code instalado y autenticado
• Al menos una aplicación LLM instrumentada con Agent Observability y que produzca trazas
• Un data backend: ya sea el Datadog MCP server o la pup CLI

Instale las habilidades

Las habilidades están publicadas en el repositorio agent-skills. Instálelas con el siguiente comando:

npx skills add datadog-labs/agent-skills/agent-observability --full-depth -y

Las habilidades están disponibles en cualquier sesión de Claude Code después de instalarlas.

Datadog MCP server

Para utilizar la opción del Datadog MCP server, conecte el Agent Observability MCP server a su sesión de Claude Code:

claude mcp add --scope user --transport http datadog-llmo-mcp \
  '?toolsets=llmobs,core'

Todas las habilidades detectan el MCP server automáticamente al iniciarse y lo utilizan en todo momento.

Opción B: pup CLI

Si prefiere no utilizar el servidor MCP, las habilidades también se ejecutan a través de pup, la CLI interna de Datadog. Instale pup y autentíquese:

pup auth login

Cada habilidad detecta al iniciarse si el MCP server está disponible; si no, busca pup y cambia al modo pup automáticamente. También puede forzar el modo pup explícitamente pasando --backend pup a cualquier invocación de habilidad.

En el modo pup, todas las llamadas a la Datadog API se realizan a través de subcomandos de pup llm-obs en lugar de herramientas MCP. La salida y el flujo de trabajo son idénticos.

Habilidades

Clasificar sesiones y trazas

/agent-observability-session-classify evalúa si la intención del usuario fue satisfecha en una interacción determinada. Funciona en tres modos dependiendo de lo que usted proporcione:

La habilidad extrae de hasta tres fuentes de señales, y la precisión mejora cuanto más datos tenga a su disposición:

• Trazas de Agent Observability — el árbol de tramos completo, el contenido de la conversación, los resultados de llamadas a herramientas y los veredictos de jueces de evaluación. Siempre disponible.
• Señales de comportamiento de RUM — vistas de página, acciones personalizadas, tiempo de permanencia y eventos de retroalimentación explícita que confirman o contradicen lo que muestra la traza. Disponible cuando RUM está instrumentado para su aplicación.
• Audit Trail — eventos de escritura confirmados por el servidor (paneles creados, monitores modificados, cuadernos eliminados) que prueban si las acciones del asistente realmente se llevaron a cabo. La señal más autorizada cuando la sesión involucró la creación o edición de activos.

La habilidad devuelve un yes / partial / no veredicto compacto con una razón de una oración de forma predeterminada. Agregue verbose: true para un informe completo en formato markdown.

Ejemplos:

/agent-observability-session-classify session_id=abc-123
/agent-observability-session-classify trace_id=def-456
/agent-observability-session-classify ml_app=my-chatbot --timeframe now-7d

Diagnostique fallas con análisis de causa raíz

/agent-observability-trace-rca recorre el árbol de tramos de trazas fallidas para identificar por qué su aplicación LLM está produciendo resultados deficientes. Selecciona el mejor modo de análisis según las señales disponibles: veredictos de evaluación de juez LLM (la señal más fuerte), errores de tiempo de ejecución o anomalías estructurales como valores atípicos de latencia y decisiones de bucle de agente.

La habilidad muestrea los tramos fallidos, los agrupa en una taxonomía de fallas y compila un informe de RCA estructurado con categorías de causa raíz, evidencia de respaldo y propuestas de solución concretas. Cada corrección incluye el texto o código real de la traza — extractos del prompt del sistema, formas de argumentos de herramientas, lógica de enrutamiento — con un BEFORE / AFTER que muestra exactamente qué cambiar.

Cuando Claude Code tiene acceso a su base de código, la habilidad busca los archivos fuente relevantes y propone diferencias que puede aplicar de inmediato. Para deficiencias en el prompt del sistema, uso indebido de herramientas o errores de enrutamiento, esto significa pasar del diagnóstico a una solicitud de extracción (pull request) sin abandonar la sesión.

Ejemplos:

/agent-observability-trace-rca ml_app=my-chatbot
/agent-observability-trace-rca ml_app=my-chatbot eval_name=faithfulness --timeframe now-24h

Analice y compare experimentos

/agent-observability-experiment-analyzer recupera los resultados del experimento y muestra qué cambió entre un candidato y un baseline. Funciona para un solo experimento (análisis exploratorio) o un par (análisis comparativo).

La habilidad resalta qué métricas mejoraron o empeoraron, qué categorías de eventos cambiaron y dónde el candidato tuvo un rendimiento inferior, para que pueda tomar una decisión de promoción con confianza.

Ejemplos

/agent-observability-experiment-analyzer experiment_id=exp-123
/agent-observability-experiment-analyzer experiment_id=exp-456 baseline_id=exp-123

Genere código de experimento con el SDK de Python

/agent-observability-experiment-py-bootstrap emite un script .py autónomo o un notebook de Jupyter .ipynb que utiliza el ddtrace.llmobs SDK y coincide con los reference notebooks canónicos.

El conjunto de datos puede ser un JSON DatasetRecordRaw[] local (integrado en el archivo), un CSV (cargado en tiempo de ejecución a través de LLMObs.create_dataset_from_csv), un conjunto de datos de Datadog existente por nombre (LLMObs.pull_dataset), o — de forma predeterminada — una pequeña muestra en línea de 3 registros.

Todas las flags a continuación son opcionales. Invoque /agent-observability-experiment-py-bootstrap sin argumentos y la habilidad solicitará lo que necesita y emitirá un archivo ejecutable con la muestra predeterminada de 3 registros.

Ejemplos

/agent-observability-experiment-py-bootstrap --purpose "validate output accuracy"
/agent-observability-experiment-py-bootstrap --purpose "test tool selection on ambiguous queries" --dataset ./data/qa.json
/agent-observability-experiment-py-bootstrap --dataset-name qa_v3 --project-name customer-qa
/agent-observability-experiment-py-bootstrap --task-source mymodule.handlers:respond --evaluator-style remote
/agent-observability-experiment-py-bootstrap --placeholder-task --format ipynb

Inicializa evaluadores a partir de datos de traza

/agent-observability-eval-bootstrap analiza trazas de producción de una ml_app (o un informe de RCA ya en contexto) y propone un conjunto de evaluadores que detectarían los modos de falla observados. Genera uno de cuatro artefactos:

Los primeros tres modos comparten el mismo flujo de trabajo de evaluador-propuesta y difieren solo en cómo se materializa la suite. El cuarto modo (--emit-dataset) es independiente: muestrea tramos raíz para el ml_app (filtrado a @status:ok), extrae input_data y expected_output por registro, ejecuta una limpieza de PII en los valores de cadena y escribe un archivo JSON que puede publicar en Datadog como un conjunto de datos y luego ejecutar un experimento contra él. Los tags por registro se normalizan automáticamente (cadenas simples envueltas como tag:<value>) para que Dataset.append() no rechace el registro. El campo expected_output está documentado como la línea base de comportamiento de producción, no como la verdad fundamental; es útil para experimentos de tipo regresión (¿mi refactorización cambia los resultados observados?) antes de ser promovido a un conjunto de oro etiquetado.

Ejemplos

/agent-observability-eval-bootstrap ml_app=my-chatbot
/agent-observability-eval-bootstrap ml_app=my-chatbot --publish
/agent-observability-eval-bootstrap ml_app=my-chatbot --data-only
/agent-observability-eval-bootstrap ml_app=my-chatbot --emit-dataset ./datasets/my_chatbot_seed.json --trace-limit 25

Ejecute el pipeline de extremo a extremo

/agent-observability-eval-pipeline encadena las subhabilidades de observabilidad de agentes en un flujo de trabajo supervisado y narrado único que recorre desde las trazas de producción hasta los evaluadores, conjuntos de datos, experimentos y análisis. Cada fase tiene el mismo formato: un banner que nombra la entidad que se está produciendo, un bloque pedagógico que explica su propósito, la acción (una llamada a una subhabilidad o un pequeño paso ejecutable) y un punto de control que espera su confirmación. Es el punto de partida recomendado cuando no tiene evaluadores o experimentos existentes y desea un recorrido determinista.

Phase 1: Classify ml_app traces      → agent-observability-session-classify (ml_app mode)
Phase 2: Root cause analysis         → agent-observability-trace-rca
Phase 3: Bootstrap evaluators        → agent-observability-eval-bootstrap
Phase 4: Create + publish dataset    → agent-observability-eval-bootstrap --emit-dataset + LLMObs.create_dataset(records=...)
Phase 5: Generate + run experiment   → agent-observability-experiment-py-bootstrap + python <generated_file>
                                       (with an in-phase review beat between codegen and run)
Phase 6: Analyze experiment          → agent-observability-experiment-analyzer

Cada fase tiene un nombre corto canónico: el mismo valor aceptado por --start-at y --stop-after. Utilice estos nombres siempre que necesite referirse a una sola fase sin ambigüedades (por ejemplo, en scripts, en chats con compañeros de equipo o en tickets de soporte):

Las fases 4 y 5 son las únicas dos que ejecutan código en su máquina; el resto son de solo lectura o escriben archivos generados en --output-dir. El comportamiento clásico del pipeline de evaluación de tres fases (clasificar → RCA → solo evaluadores bootstrap) se conserva pasando --stop-after eval-bootstrap. La fase 5 se pausa entre la generación de código y la ejecución para que pueda revisar el archivo de experimento generado antes de que se consuman tokens del proveedor: escriba run para ejecutar, edit para pausar y ajustar, o stop para salir de forma limpia.

Entre y salga en cualquier fase. El pipeline persiste la salida principal de cada fase (resumen de clasificación, informe de RCA, suite de evaluadores, conjunto de datos, nombre del conjunto de datos publicado, archivo de experimento, ejecución de experimento, informe del analizador) en <output-dir>/state/0N-<name>.{md, json} antes de que se muestre cada punto de control. Esto significa:

• stop en cualquier punto de control (o --stop-after <phase> desde la parte superior) finaliza la ejecución de forma limpia, dejando un artefacto reingresable en el disco.
• --start-at <phase> carga el archivo de estado de cada fase anterior (o acepta un override flag si proporcionó uno) y salta directamente a la fase nombrada. Puede reanudar horas o días después, o saltar directamente a “solo volver a analizar este experimento” sin volver a ejecutar nada anterior.

Vocabulario de puntos de control en cada fase: continue avanza, stop sale limpiamente, redo vuelve a ejecutar la fase actual (con notas de ajuste opcionales adjuntas), back retrocede una fase. Cualquier otra entrada se trata como ajuste.

Solo se requiere <ml_app>. Cada flag a continuación es opcional: la habilidad elige valores predeterminados sensatos para cada una. La invocación mínima es /agent-observability-eval-pipeline <ml_app>; el resto de la tabla es para cuando desea anular un valor predeterminado, reanudar a mitad del flujo o fijar una ubicación de salida específica.

Ejemplos

# Full six-phase walkthrough for a brand new ml_app
/agent-observability-eval-pipeline my-chatbot --project-name my-chatbot

# Organize the dataset and experiment under a specific Datadog project
# (the project is created lazily — no need to pre-create it in the UI)
/agent-observability-eval-pipeline my-chatbot --project-name customer-qa-eval

# Classic three-phase eval-pipeline behavior — preserves backward compatibility
/agent-observability-eval-pipeline my-chatbot --stop-after eval-bootstrap

# Resume from where a previous run stopped
/agent-observability-eval-pipeline my-chatbot --start-at experiment

# Re-analyze a previous experiment run without re-running it
/agent-observability-eval-pipeline my-chatbot --start-at analyze --experiment-id <UUID>

# Run a single phase in isolation
/agent-observability-eval-pipeline my-chatbot --start-at dataset --stop-after dataset

Nombre del proyecto — si se omite --project-name, la habilidad lo deriva automáticamente de su base de código (en orden: pyproject.toml → setup.cfg → setup.py → package.json → nombre base de cwd), recurriendo a experiment-sdk-default. El nombre resuelto se muestra en la salida de la verificación previa antes de que se ejecute cualquier fase, por lo que puede confirmarlo o anularlo sin volver a invocar. El proyecto de Datadog en sí es creado de forma diferida por LLMObs.enable(project_name=...) cuando la Fase 4 publica el conjunto de datos; nunca necesita crearlo previamente en la interfaz de usuario.

Flujo de trabajo típico

Si es nuevo en la evaluación de una aplicación LLM, el flujo recomendado es:

1. Ejecute la pipeline para recorrer desde las trazas de producción hasta los evaluadores, un conjunto de datos semilla, un experimento y el análisis:

   /agent-observability-eval-pipeline <ml_app> --project-name <project>
   

   Para detenerse en la salida clásica solo de evaluador (sin conjunto de datos ni experimento), pase --stop-after eval-bootstrap. Para reanudar una ejecución anterior, pase --start-at <phase>: la canalización recarga el estado anterior desde <output-dir>/state/ y continúa desde allí.

2. Aplique correcciones. El informe de RCA producido en la Fase 2 incluye propuestas de corrección específicas de antes/después basadas en evidencia de trazas. Pase el informe a un agente de codificación (o actúe directamente sobre él) para corregir los prompts del sistema, las definiciones de herramientas o la lógica de enrutamiento en su base de código.

3. Ejecute un experimento sin conexión utilizando los evaluadores generados frente a un conjunto de datos etiquetado para validar su calidad antes de habilitarlos en producción. Consulte la Guía para desarrolladores de evaluación.

4. Publique evaluadores en línea una vez que los evaluadores estén validados. Ejecutar /agent-observability-eval-bootstrap con --publish crea evaluadores de juez LLM en línea en Datadog que se ejecutan automáticamente en sus trazas de producción en tiempo real — no se requieren cambios de código:

   /agent-observability-eval-bootstrap <ml_app> --publish
   

5. Haga un seguimiento e itere. A medida que su aplicación evolucione, vuelva a ejecutar /agent-observability-trace-rca y /agent-observability-eval-bootstrap para detectar nuevos modos de falla y mantener actualizado su conjunto de evaluadores.

Documentación, enlaces y artículos útiles adicionales:

Evaluaciones de Agent ObservabilityDOCUMENTACIÓN Experimentos de LLMDOCUMENTACIÓN Guía para desarrolladores de evaluación: cree evaluadores personalizadosGUÍA Mejore la calidad de los agentes de IA con Bits EvalsBLOG datadog-labs/agent-skillsGITHUB