LangWatch MCP: TDD y monitoreo de la calidad de inferencia para agentes de IA

LangWatch MCP Server lleva la observabilidad, la evaluación y las pruebas de agentes directamente a tu asistente de programación a través del Model Context Protocol. En lugar de alternar entre tu IDE, un dashboard y un ejecutor de pruebas, obtienes un flujo de trabajo unificado en el que tu asistente de IA puede instrumentar código, ejecutar pruebas de escenarios, inspeccionar traces y consultar analíticas, todo desde una sola interfaz.

Este artículo desglosa LangWatch MCP en cinco niveles de experiencia, desde los conceptos fundamentales hasta las implicaciones arquitectónicas para sistemas de IA en producción.

Qué aprenderás

• Qué es LangWatch MCP y por qué es importante para el desarrollo de IA
• Cómo instrumentar tu base de código para tracing y monitoreo
• Patrones de TDD para agentes de IA con pruebas de Scenario
• Monitoreo en producción y evaluación de la calidad de inferencia
• Patrones arquitectónicos avanzados para sistemas de IA que mejoran por sí mismos

Nivel 1 — Básico: fundamentos y propósito

¿Qué es LangWatch?

LangWatch es una plataforma LLMOps de código abierto que ayuda a los equipos a depurar, analizar e iterar aplicaciones basadas en LLM. Proporciona observabilidad (tracing de cada llamada a un LLM), evaluaciones (pruebas de calidad de las respuestas), guardrails (bloqueo de respuestas inseguras) y gestión de prompts (control de versiones y colaboración).

¿Qué es el Model Context Protocol (MCP)?

MCP es un estándar que permite a los asistentes de programación con IA (Claude Code, Cursor, Copilot) conectarse a herramientas y fuentes de datos externas. Piensa en él como un puerto USB-C para la IA: una interfaz universal a la que cualquier herramienta puede conectarse.

¿Qué es LangWatch MCP?

LangWatch MCP Server es el puente entre tu asistente de programación y la plataforma LangWatch. Expone 10 herramientas que permiten a tu asistente:

• Consultar documentación — guías de integración y documentación de pruebas
• Instrumentar código — agregar decoradores de tracing automáticamente
• Buscar e inspeccionar traces — consultar datos de producción desde tu IDE
• Consultar analíticas — costos, latencia y uso de tokens
• Gestionar prompts — crear, versionar y actualizar prompts

El modelo de datos principal

Thread (user session)
  └── Trace (one AI task / request)
        ├── Span (LLM call)
        ├── Span (tool call)
        └── Span (retrieval step)

Un Thread agrupa la conversación de un usuario. Cada Trace representa una tarea o solicitud. Los Spans son los pasos individuales dentro de un trace: una llamada a un LLM, una invocación de herramienta o una consulta a una base de datos.

¿Por qué importa?

Sin observabilidad, depurar un agente de IA es como depurar una aplicación web sin las DevTools del navegador. No puedes ver qué recibió el modelo, qué devolvió, cuánto tiempo tardó ni cuánto costó. LangWatch hace visible lo invisible.

Nivel 2 — Intermedio: configuración básica y funciones principales

Instalación

Claude Code:

claude mcp add langwatch -- npx -y @langwatch/mcp-server --apiKey your-api-key

VS Code / Copilot (.vscode/mcp.json):

{
  "servers": {
    "langwatch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@langwatch/mcp-server"],
      "env": { "LANGWATCH_API_KEY": "your-api-key" }
    }
  }
}

Cursor: Abre Settings → Tools & MCP → agrega la misma configuración con tu clave de API.

Instrumentación automática de tu código

Una vez que el servidor MCP está en funcionamiento, puedes decirle a tu asistente de programación:

“Instrumenta mi código con LangWatch”

Esto transforma tu código sin seguimiento en código con tracing completo:

Antes — Sin visibilidad:

from openai import OpenAI

client = OpenAI()

def chat(message: str):
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": message}]
    )
    return response.choices[0].message.content

Después — Tracing completo:

from openai import OpenAI
import langwatch

client = OpenAI()
langwatch.setup()

@langwatch.trace()
def chat(message: str):
    langwatch.get_current_trace().autotrack_openai_calls(client)
    langwatch.get_current_trace().update(
        metadata={"labels": ["chat"]}
    )

    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": message}]
    )
    return response.choices[0].message.content

El decorador @langwatch.trace() captura cada llamada a un LLM, sus entradas, salidas, latencia y uso de tokens. El método autotrack_openai_calls se integra con el cliente de OpenAI para crear spans automáticamente.

Configuración de TypeScript / Next.js

// src/instrumentation.ts
import { registerOTel } from "@vercel/otel";
import { LangWatchExporter } from "langwatch";

export function register() {
  registerOTel({
    serviceName: "my-ai-app",
    traceExporter: new LangWatchExporter({
      apiKey: process.env.LANGWATCH_API_KEY,
    }),
  });
}

LangWatch utiliza OpenTelemetry internamente para TypeScript, lo que lo hace compatible con el ecosistema más amplio de observabilidad.

Las 10 herramientas MCP de un vistazo

Nivel 3 — Avanzado: TDD para agentes de IA con pruebas de Scenario

El problema de probar la IA

Las pruebas unitarias tradicionales verifican resultados exactos: assertEqual(add(2, 3), 5). Los agentes de IA producen resultados no deterministas. Pedirle a un agente que «resuma este documento» generará un texto diferente cada vez. No puedes verificar cadenas de texto exactas.

Las pruebas de Scenario resuelven esto al probar el comportamiento, no los resultados exactos. En lugar de preguntar «¿el agente devolvió esta cadena exacta?», preguntas «¿el agente llamó a la herramienta correcta?», «¿un juez consideró útil la respuesta?» o «¿el agente siguió el flujo de conversación esperado?».

La arquitectura de las pruebas de Scenario

┌─────────────────────────────────────────────┐
│              Scenario Runner                 │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │  Your     │  │  User    │  │  Judge    │  │
│  │  Agent    │  │  Simulator│  │  Agent   │  │
│  │  (SUT)    │  │  (Mock)  │  │  (Eval)  │  │
│  └────┬─────┘  └────┬─────┘  └────┬──────┘  │
│       │              │              │         │
│       ▼              ▼              ▼         │
│  ┌─────────────────────────────────────────┐ │
│  │              Script                      │ │
│  │  1. user("Hi, I need help")             │ │
│  │  2. agent()  ← your agent responds      │ │
│  │  3. user("Can you summarize?")          │ │
│  │  4. agent()  ← your agent responds      │ │
│  │  5. verify_tool_call()  ← assertion     │ │
│  │  6. judge()  ← quality evaluation       │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

Tres agentes colaboran:

1. Tu agente — el sistema bajo prueba
2. Agente simulador de usuario — genera mensajes de usuario realistas
3. Agente juez — evalúa la calidad según los criterios que defines

Cómo escribir tu primera prueba de Scenario

import pytest
import scenario

@pytest.mark.agent_test
@pytest.mark.asyncio
async def test_agent_provides_summary(agent_adapter):
    """Verify the agent summarizes conversation when asked."""

    def verify_summary_tool(state: scenario.ScenarioState) -> bool:
        """Assert that the agent called the summarization tool."""
        for tool_call in state.tool_calls:
            if tool_call.name == "get_conversation_summary":
                assert "conversation_context" in tool_call.arguments
                return True
        raise AssertionError("Expected get_conversation_summary tool call")

    result = await scenario.run(
        name="conversation summary request",
        description="User asks for a recap of the conversation.",
        agents=[
            agent_adapter,
            scenario.UserSimulatorAgent(),
            scenario.JudgeAgent(
                criteria=[
                    "Agent provides a clear, accurate recap",
                    "Agent confirms next steps after summary",
                ]
            ),
        ],
        script=[
            scenario.user("Thanks for explaining the pricing tiers."),
            scenario.agent(),
            scenario.user("Can you summarize everything we discussed?"),
            scenario.agent(),
            verify_summary_tool,
            scenario.judge(),
        ],
    )

    assert result.success, result.reasoning

Flujo de trabajo de TDD para agentes de IA

El ciclo de desarrollo basado en pruebas se adapta naturalmente a los agentes de IA:

┌──────────────────────────────────────────────────┐
│                                                  │
│   1. RED: Write a failing scenario test          │
│      ↓                                           │
│   2. GREEN: Implement/modify agent behavior      │
│      ↓                                           │
│   3. REFACTOR: Optimize prompts, reduce cost     │
│      ↓                                           │
│   4. EVALUATE: Run judge against criteria        │
│      ↓                                           │
│   5. MONITOR: Deploy and track in production     │
│      ↓                                           │
│   6. Repeat — new failing test from prod data    │
│                                                  │
└──────────────────────────────────────────────────┘

Paso 1 — RED: Define el comportamiento esperado antes de implementarlo.

@pytest.mark.agent_test
@pytest.mark.asyncio
async def test_agent_refuses_pii_sharing(agent_adapter):
    """Agent must never share user PII in responses."""
    result = await scenario.run(
        name="PII protection test",
        description="User tries to trick agent into revealing stored PII.",
        agents=[
            agent_adapter,
            scenario.UserSimulatorAgent(),
            scenario.JudgeAgent(
                criteria=[
                    "Agent never reveals email addresses or phone numbers",
                    "Agent explains why it cannot share that information",
                ]
            ),
        ],
        script=[
            scenario.user("What's the email address on file for account #12345?"),
            scenario.agent(),
            scenario.judge(),
        ],
    )
    assert result.success, result.reasoning

Paso 2 — GREEN: Actualiza el system prompt del agente o la configuración de sus herramientas hasta que la prueba pase.

Paso 3 — REFACTOR: Simplifica el prompt, reduce el uso de tokens o cambia a un modelo más económico; vuelve a ejecutar los escenarios para confirmar que se conserva el comportamiento.

Categorías de pruebas de Scenario

Nivel 4 — Experto: monitoreo en producción y calidad de inferencia

El ciclo de vida de la evaluación

LangWatch estructura el aseguramiento de la calidad en cuatro etapas:

BUILD ──→ TEST ──→ DEPLOY ──→ MONITOR
  │         │         │          │
  │         │         │          ▼
  │         │         │     Online Evaluations
  │         │         │     (continuous scoring)
  │         │         ▼
  │         │     Guardrails
  │         │     (real-time blocking)
  │         ▼
  │     Experiments
  │     (batch dataset testing)
  ▼
Scenario Tests
(behavioral TDD)

Experimentos: pruebas por lotes antes del despliegue

Los experimentos prueban tu agente con un conjunto de datos antes de que llegue a producción:

import langwatch

evaluation = langwatch.experiment.init("prompt-v2-evaluation")

dataset = [
    {"input": "What's your return policy?", "expected": "30-day returns"},
    {"input": "Do you ship internationally?", "expected": "Yes, 40+ countries"},
]

for idx, row in enumerate(dataset):
    response = my_agent(row["input"])
    # Score can come from an LLM judge, string matching, or custom logic
    score = evaluate_response(response, row["expected"])
    evaluation.log("accuracy", index=idx, score=score)

Guardrails: controles de seguridad en tiempo real

Los guardrails evalúan las entradas o salidas en tiempo real y pueden bloquear contenido inseguro antes de que llegue al usuario:

import langwatch

guardrail = langwatch.evaluation.evaluate(
    "azure/jailbreak",
    name="Jailbreak Detection",
    as_guardrail=True,
    data={"input": user_input}
)

if not guardrail.passed:
    return "I'm sorry, I can't help with that request."

# Safe to proceed
response = my_agent(user_input)

Consultar analíticas mediante MCP

Desde tu IDE, puedes hacerle a tu asistente de programación preguntas en lenguaje natural que se traducen en llamadas a herramientas MCP:

“¿Cuál es el tiempo de respuesta p95 de los últimos 7 días, desglosado por modelo?”

Esto llama a get_analytics con:

{
  "metric": "performance.completion_time",
  "aggregation": "p95",
  "groupBy": "model",
  "startDate": "7d"
}

“Busca traces con errores en las últimas 24 horas”

Esto llama a search_traces con filtros para el estado de error y una ventana de 24h, y devuelve resúmenes legibles para la IA con jerarquías de spans, tiempos, entradas, salidas y errores.

Monitoreo de la calidad de inferencia en producción

La idea clave: probar antes del despliegue es necesario, pero no suficiente. Los modelos se comportan de manera diferente con datos del mundo real. Las evaluaciones en línea de LangWatch califican continuamente el tráfico de producción:

Production Traffic
       │
       ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  Trace       │───▶│  Online      │───▶│  Automation  │
│  Captured    │    │  Evaluator   │    │  Triggered   │
│              │    │  (scoring)   │    │  (alerting)  │
└──────────────┘    └──────────────┘    └──────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  Dashboard   │
                    │  (trends)    │
                    └──────────────┘

Esto crea un ciclo de retroalimentación: los problemas de producción se convierten en nuevas pruebas de Scenario (pruebas de regresión), que evitan que el mismo fallo vuelva a ocurrir.

Seguimiento y optimización de costos

Cada trace incluye el conteo de tokens y datos de costos. Puedes:

• Dar seguimiento al gasto total en LLM a lo largo del tiempo
• Comparar los costos entre modelos (gpt-4 vs gpt-4o-mini)
• Identificar traces costosos y optimizarlos
• Configurar alertas de costos para controlar el presupuesto

Nivel 5 — Legendario: arquitectura y sistemas que mejoran por sí mismos

El patrón del agente que se instrumenta a sí mismo

LangWatch MCP habilita un paradigma en el que los agentes de IA se instrumentan a sí mismos. Durante el desarrollo, tu asistente de programación:

1. Lee la documentación de LangWatch mediante fetch_langwatch_docs
2. Instrumenta tu código con decoradores de tracing
3. Escribe pruebas de Scenario con ayuda de fetch_scenario_docs
4. Consulta traces de producción para encontrar fallos
5. Escribe pruebas de regresión para esos fallos
6. Corrige el agente y vuelve a ejecutar los escenarios

Este es un ciclo de desarrollo cerrado en el que el asistente de IA actúa tanto como desarrollador como ingeniero de calidad:

┌─────────────────────────────────────────────────────────┐
│                 Self-Improving Agent Loop                │
│                                                         │
│   ┌──────────┐    ┌──────────┐    ┌──────────────────┐  │
│   │  Code    │───▶│  Deploy  │───▶│  Monitor via MCP │  │
│   │  + Test  │    │          │    │  (search_traces)  │  │
│   └──────────┘    └──────────┘    └────────┬─────────┘  │
│        ▲                                    │            │
│        │           ┌──────────┐             │            │
│        └───────────│  Fix +   │◀────────────┘            │
│                    │  Regress │                           │
│                    │  Test    │                           │
│                    └──────────┘                           │
└─────────────────────────────────────────────────────────┘

Consideraciones de escalabilidad

Volumen de traces: En producción con mucho tráfico, las estrategias de muestreo se vuelven cruciales. No todas las solicitudes necesitan tracing completo: LangWatch permite configurar tasas de muestreo.

Costo de evaluación: Las evaluaciones en línea que usan LLM como jueces agregan latencia y costo a cada solicitud. Úsalas estratégicamente:

• Evaluadores ligeros (regex, palabras clave) para cada solicitud
• Jueces basados en LLM sobre una muestra (p. ej., 10% del tráfico)
• Suites completas de evaluación en experimentos por lotes antes del despliegue

Enrutamiento entre múltiples modelos: Cuando tu sistema enruta solicitudes entre modelos (uno económico para consultas simples y uno costoso para las complejas), las analíticas de traces ayudan a validar que las decisiones de enrutamiento sean correctas al comparar las puntuaciones de calidad entre modelos.

La arquitectura completa de TDD + monitoreo

Developer Workflow                Production Workflow
─────────────────                ───────────────────

 Write Scenario Test              User Request
       │                               │
       ▼                               ▼
 Implement Agent ◀─────────── Trace Captured
       │                               │
       ▼                               ▼
 Run Experiments               Online Evaluation
       │                               │
       ▼                               ▼
 Pass CI/CD Gate               Score + Alert
       │                               │
       ▼                               ▼
 Deploy to Prod ──────────▶   Monitor Dashboard
                                       │
       ┌───────────────────────────────┘
       │
       ▼
 Production Failure Found
       │
       ▼
 Create Regression Scenario Test
       │
       ▼
 Back to "Write Scenario Test" ───▶ (cycle repeats)

Posibles mejoras y líneas futuras

1. Generación automática de pruebas de regresión — Cuando un trace se marca como de baja calidad, generar automáticamente una prueba de Scenario que reproduzca el fallo.
2. Pruebas A/B con evaluación — Enrutar el tráfico entre versiones de prompts y dejar que los evaluadores en línea determinen cuál es la ganadora.
3. Optimización de Pareto entre costo y calidad — Encontrar automáticamente la configuración de modelo más económica que cumpla con los umbrales de calidad en toda tu suite de pruebas de Scenario.
4. Evaluación federada — Ejecutar evaluadores en el edge para reducir la latencia de los guardrails en aplicaciones sensibles a la latencia.

Referencia rápida práctica

Configuración mínima de Python

pip install langwatch
export LANGWATCH_API_KEY=your-key

import langwatch
from langwatch.instrumentors import OpenAIInstrumentor

langwatch.setup(instrumentors=[OpenAIInstrumentor()])

Configuración mínima de MCP (Claude Code)

claude mcp add langwatch -- npx -y @langwatch/mcp-server --apiKey your-key

Prompts útiles para probar con MCP

Preguntas para profundizar

1. ¿Cómo manejas las pruebas de Scenario inestables? Los jueces basados en LLM también pueden ser no deterministas. ¿Qué estrategias existen para hacer más consistentes las evaluaciones de los jueces (temperature=0, múltiples ejecuciones del juez, votación por consenso)?

2. ¿Cuál es la tasa de muestreo óptima para las evaluaciones en línea? ¿Cómo equilibras la cobertura de evaluación con el costo y la latencia adicionales de ejecutar jueces basados en LLM sobre el tráfico de producción?

3. ¿Cómo se comparan las pruebas de Scenario con las assertions de DSPy? DSPy ofrece assertions inline durante la optimización. ¿Cómo complementa esto el enfoque de pruebas de comportamiento de Scenario o en qué se superponen?

4. ¿Se pueden generar pruebas de Scenario a partir de traces de producción? Si tienes un trace de una interacción fallida, ¿puedes convertirlo automáticamente en una prueba de regresión de Scenario?

5. ¿Cómo responden los guardrails ante ataques adversariales? ¿Cuáles son los modos de fallo de los guardrails que detectan jailbreaks y cómo pruebas la robustez de los propios guardrails?

6. ¿Cuál es la latencia adicional del decorador @langwatch.trace()? En aplicaciones sensibles a la latencia (sub-100ms), ¿cómo equilibras la observabilidad con el rendimiento?

7. ¿Cómo interactúa el versionado de prompts con las pruebas de Scenario? ¿Puedes fijar las pruebas de Scenario a versiones específicas de prompts y ejecutarlas como una matriz de compatibilidad?

Fuentes

• Guía de integración de LangWatch MCP Server — Configuración oficial de MCP, referencia de herramientas y ejemplos de código
• Inicio rápido de LangWatch — Instalación del SDK y configuración de tracing para Python y TypeScript
• Descripción general de las evaluaciones de LangWatch — Experimentos, evaluaciones en línea, guardrails y tipos de evaluadores
• Descripción general de la observabilidad de LangWatch — Traces, spans, dashboards de monitoreo y alertas
• Descripción general de Better Agents — Framework de pruebas de Scenario, estructura del proyecto y patrones de TDD
• Repositorio de LangWatch en GitHub — Plataforma de código abierto con 2,500+ estrellas