Implementación de evaluaciones con LangWatch, Agno y AgentOS: de cero a producción

Puedes crear un agente de Agno capaz en una tarde. Lo más difícil es demostrar que sigue funcionando bien después de cambios en los prompts, modelos, herramientas y mecanismos de recuperación, y ante el tráfico de producción. Ahí es donde LangWatch encaja bien.

Al 31 de marzo de 2026, la documentación actual de Agno muestra la integración con LangWatch mediante langwatch.setup(instrumentors=[AgnoInstrumentor()]), mientras que la documentación actual de LangWatch presenta las evaluaciones como tres capas conectadas: experimentos offline, monitores online y guardrails en tiempo real. Dicho de otra forma: Agno/AgentOS ejecuta el sistema; LangWatch lo mide.

TL;DR

• Usa Agno para construir el agente, equipo o workflow y AgentOS para exponerlo en producción.
• Empieza por el tracing con LangWatch, porque todo flujo de evaluación útil depende de contar con datos de trazas limpios.
• Comienza con experimentos offline sobre un pequeño dataset de referencia antes de implementar monitores de producción.
• Para agentes de Agno con output_schema, evalúa los campos de negocio, no solo la calidad del texto libre.
• Mantén los guardrails síncronos y mueve las evaluaciones no bloqueantes a post-hooks de AgentOS en segundo plano.
• Usa las evaluaciones nativas de Agno para comprobar la exactitud, confiabilidad y rendimiento dentro del framework; usa LangWatch para datasets compartidos, experimentos, monitores, alertas y visibilidad entre ejecuciones.

Qué aprenderás aquí

• Cómo se dividen las responsabilidades entre LangWatch y Agno/AgentOS en un stack de agentes en producción
• Cómo instrumentar un agente de Agno para que LangWatch reciba trazas automáticamente
• Cómo ejecutar experimentos offline con agentes de Agno usando evaluadores integrados y funciones de puntuación personalizadas
• Cómo evaluar las salidas estructuradas producidas por output_schema
• Cómo agregar evaluación online y guardrails sin convertir tu entorno de ejecución en una trampa de latencia
• Cómo usar hooks de AgentOS para ejecutar evaluaciones en segundo plano de forma segura
• Cómo cerrar el ciclo, desde las trazas de producción hasta los datasets reutilizables

El modelo mental

Piensa en el stack de esta manera:

User / API Client
       │
       ▼
Agno Agent / Team / Workflow
       │
       ▼
AgentOS Runtime
  - sessions
  - auth
  - APIs
  - hooks
  - deployment surface
       │
       ▼
LangWatch
  - traces and spans
  - offline experiments
  - online monitors
  - guardrails
  - alerts and analytics

Esta división importa porque evita un error común: intentar que el framework sea la plataforma de evaluación o que la plataforma de evaluación sea el entorno de ejecución.

Una división práctica de responsabilidades

Si solo recuerdas una regla, que sea esta:

Agno decides what the agent does.
LangWatch decides how well it did.
AgentOS decides how it runs in production.

Un caso de uso real que podemos evaluar

Usaremos un agente de enrutamiento de soporte porque es realista y fácil de analizar:

• Lee un mensaje del usuario junto con el contexto recuperado de las políticas
• Determina la intención del usuario
• Decide si es necesario escalar el caso a una persona
• Genera una respuesta para el cliente
• Devuelve una salida estructurada que podemos evaluar de forma determinista

Es un buen caso para Agno y LangWatch porque combina:

• calidad de texto libre
• calidad de la recuperación
• cumplimiento de reglas de negocio
• observabilidad en tiempo de ejecución

Paso 1: Instrumentar Agno con LangWatch

La integración actual de Agno con LangWatch utiliza instrumentación de OpenInference, por lo que la configuración es sencilla:

uv pip install langwatch agno openai openinference-instrumentation-agno
export LANGWATCH_API_KEY="your-api-key"

import langwatch

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from openinference.instrumentation.agno import AgnoInstrumentor

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

agent = Agent(
    name="Support Router",
    model=OpenAIResponses(id="gpt-5.2"),
    instructions=[
        "Classify the user intent.",
        "Decide whether the case needs human escalation.",
        "Reply using only approved policy context.",
    ],
    debug_mode=True,
)

agent.print_response("I was billed twice. Can you refund one of the charges?")

Eso basta para que la actividad de Agno llegue a LangWatch. A partir de ahí, puedes inspeccionar las trazas incluso antes de agregar evaluaciones formales.

Por qué el tracing va primero

Sin trazas, tu capa de evaluación tiene poco contexto:

• no sabes qué versión del prompt produjo el resultado
• no sabes qué fragmentos recuperados se utilizaron
• no sabes si una falla provino del razonamiento, la recuperación o la ejecución de una herramienta

Con trazas, todas las evaluaciones posteriores son más útiles.

Paso 2: Hacer que el agente devuelva una salida tipada

output_schema de Agno es el punto de partida adecuado para la evaluación porque te da algo que puedes puntuar.

Si usas una versión anterior de Agno, es posible que todavía veas response_model en los ejemplos. La documentación actual usa output_schema, que es lo que utilizo en todo este artículo.

from typing import Literal

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from pydantic import BaseModel, Field


class SupportDecision(BaseModel):
    intent: Literal["refund", "bug", "shipping", "pricing", "other"]
    needs_human: bool = Field(description="True when a human agent should take over")
    customer_reply: str
    cited_policy_ids: list[str]


support_agent = Agent(
    name="Support Router",
    model=OpenAIResponses(id="gpt-5.2"),
    output_schema=SupportDecision,
    instructions=[
        "Classify the support intent.",
        "Set needs_human=true for billing disputes, legal issues, or unclear policy cases.",
        "Use only the provided policy context.",
        "Always cite the policy ids you relied on.",
    ],
)


def route_ticket(user_message: str, policy_context: str) -> SupportDecision:
    response = support_agent.run(
        f"User message: {user_message}\n\nPolicy context:\n{policy_context}"
    )
    return response.content

Esto ya mejora la confiabilidad, pero no significa que tu agente sea correcto. Solo significa que la salida tiene la estructura correcta.

Esa distinción es importante:

Schema-valid != business-correct

Paso 3: Ejecutar tu primer experimento offline

Ahora hacemos que el agente sea medible.

Los experimentos de LangWatch son la capa adecuada para:

• comparar prompts
• comparar modelos
• comparar mecanismos de recuperación
• detectar regresiones antes del despliegue

Un dataset de referencia sencillo

Puedes empezar con un CSV, pero los datasets de LangWatch son más útiles a largo plazo porque también puedes alimentarlos a partir de trazas.

import json
import langwatch


df = langwatch.dataset.get_dataset("support-routing-golden-set").to_pandas()
experiment = langwatch.experiment.init("support-routing-v1")


def score_decision(output: SupportDecision, expected_json: str) -> float:
    expected = json.loads(expected_json)

    checks = [
        output.intent == expected["intent"],
        output.needs_human == expected["needs_human"],
        set(output.cited_policy_ids) == set(expected["cited_policy_ids"]),
    ]
    return sum(checks) / len(checks)


for index, row in experiment.loop(df.iterrows()):
    with experiment.target(
        "gpt5-baseline",
        {"model": "openai/gpt-5.2", "prompt_version": "support-router-v1"},
    ):
        decision = route_ticket(
            user_message=row["user_message"],
            policy_context=row["policy_context"],
        )

        experiment.log_response(decision.model_dump_json())

        experiment.log(
            "routing_accuracy",
            index=index,
            score=score_decision(decision, row["expected_json"]),
            data={
                "intent": decision.intent,
                "needs_human": decision.needs_human,
                "cited_policy_ids": decision.cited_policy_ids,
            },
        )

        experiment.evaluate(
            "ragas/faithfulness",
            index=index,
            data={
                "input": row["user_message"],
                "output": decision.customer_reply,
                "contexts": row["retrieved_chunks"],
            },
            settings={"model": "openai/gpt-5.2"},
        )


experiment.print_summary()

Qué hace este experimento

• experiment.target(...) permite comparar la ejecución con futuros modelos o prompts
• experiment.log_response(...) almacena la salida real para inspeccionarla
• experiment.log(...) registra una métrica de negocio personalizada
• experiment.evaluate(...) ejecuta un evaluador integrado para comprobar si la respuesta está fundamentada

Este patrón en línea es más fácil de enseñar y genera más confianza en un artículo público. Si más adelante quieres un modelo de concurrencia más avanzado con envío explícito de tareas, documéntalo por separado y muestra el flujo correspondiente de espera o sincronización.

Este es el primer punto en el que LangWatch se convierte en algo más que observabilidad. Se convierte en un criterio de aprobación para releases.

Paso 4: Evaluar lo correcto en las salidas estructuradas

Muchos equipos que desarrollan agentes cometen el mismo error aquí: solo evalúan el texto de la respuesta.

Para agentes de Agno con salida estructurada, ese no suele ser el nivel adecuado.

Normalmente querrás evaluar al menos cuatro capas:

Esto ofrece una visión de la evaluación mucho mejor que una sola “puntuación de calidad”.

Un mejor flujo de evaluación

Agno output_schema
      │
      ├─ catches malformed structure
      │
      ▼
Custom scorer
  - intent correct?
  - escalation correct?
  - cited policy ids correct?
      │
      ▼
Built-in evaluator
  - faithful to retrieved context?
  - clear enough for a customer?

La idea importante es que la corrección según las reglas de negocio y la calidad del lenguaje son dimensiones separadas.

Paso 5: Comparar modelos, prompts o estrategias de recuperación

Una vez que tienes un experimento de referencia, el siguiente paso valioso es comparar.

Por ejemplo:

• gpt5-baseline frente a claude-sonnet
• recuperador de políticas v1 frente a recuperador híbrido v2
• prompt con reglas estrictas de escalamiento frente a prompt con reglas más flexibles

En LangWatch, los metadatos de target(...) sirven precisamente para eso.

with experiment.target(
    "hybrid-retriever-v2",
    {
        "model": "openai/gpt-5.2",
        "retriever": "hybrid",
        "prompt_version": "support-router-v2",
    },
):
    decision = route_ticket(
        user_message=row["user_message"],
        policy_context=row["hybrid_policy_context"],
    )

    experiment.log_response(decision.model_dump_json())
    experiment.log(
        "routing_accuracy",
        index=index,
        score=score_decision(decision, row["expected_json"]),
    )

Esta es la diferencia entre “creemos que v2 se siente mejor” y “v2 mejoró la exactitud del enrutamiento en 11 puntos mientras mantuvo estable la fidelidad”.

Esa es una mejor conversación tanto para ingeniería como para gestión de producto.

Paso 6: Agregar evaluación online para el tráfico de producción

Las evaluaciones offline te indican si es probable que un candidato a release sea seguro. No te dicen qué está pasando con el tráfico en vivo esta tarde.

La evaluación online de LangWatch cubre esa brecha. La documentación actual la describe mediante Monitors que puntúan las trazas entrantes y pueden activar dashboards o alertas cuando se superan ciertos umbrales.

El flujo es sencillo:

Live request
   │
   ▼
Agno / AgentOS handles request
   │
   ▼
LangWatch trace arrives
   │
   ▼
Monitor runs evaluator
   │
   ├─ score stored
   ├─ dashboard updated
   └─ alert fired if threshold is crossed

Buenos candidatos para monitores de producción

• fidelidad de las respuestas a clientes basadas en contexto recuperado
• filtración de PII en las salidas del agente
• detección de jailbreak en las entradas del agente
• confianza en el enrutamiento o corrección del escalamiento, mediante métricas personalizadas

El patrón clave es:

• los experimentos offline protegen los releases
• los monitores online protegen la producción

Necesitas ambos.

Paso 7: Agregar guardrails en tiempo real para rutas de riesgo

Los guardrails se diferencian de los monitores porque pueden cambiar el flujo de control de inmediato.

Por ejemplo, si expones un endpoint de la API de AgentOS directamente a los usuarios, podrías querer rechazar una inyección de prompt o impedir la filtración de PII antes de devolver un resultado.

import langwatch


@langwatch.trace(name="support_request")
def handle_support_request(user_message: str, policy_context: str) -> str:
    guardrail = langwatch.evaluation.evaluate(
        "azure/jailbreak",
        name="Jailbreak Detection",
        as_guardrail=True,
        data={"input": user_message},
    )

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

    decision = route_ticket(user_message, policy_context)

    langwatch.evaluation.evaluate(
        "presidio/pii_detection",
        name="PII Output Check",
        data={"output": decision.customer_reply},
    )

    return decision.customer_reply

Usa los guardrails con moderación. Forman parte de la ruta de la solicitud, por lo que afectan la latencia y la disponibilidad.

Una buena regla:

If the score must block the response, keep it synchronous.
If the score is for analytics or continuous improvement, move it out of band.

Paso 8: Usar hooks de AgentOS en segundo plano para evaluaciones no bloqueantes

Aquí es donde Agno y AgentOS se vuelven especialmente útiles.

La documentación actual de hooks de Agno admite explícitamente pre-hooks y post-hooks, y AgentOS puede ejecutar hooks en segundo plano con @hook(run_in_background=True). Esa misma documentación también advierte que los hooks en segundo plano no son el lugar adecuado para los guardrails porque no pueden modificar la solicitud ni la respuesta después de que ya se procesaron.

Esto te da un patrón claro para producción:

• guardrails síncronos para lo que debe bloquearse
• post-hooks en segundo plano para puntuación, logging, alertas y análisis

Ejemplo: post-hook en segundo plano que envía datos de evaluación personalizados a LangWatch

import langwatch

from agno.hooks import hook


def customer_reply_score(output: SupportDecision) -> float:
    score = 1.0
    if len(output.customer_reply) < 40:
        score -= 0.2
    if not output.cited_policy_ids:
        score -= 0.4
    if output.intent == "refund" and not output.needs_human:
        score -= 0.4
    return max(score, 0.0)


@hook(run_in_background=True)
async def evaluate_output_in_background(run_output, session=None, user_id=None):
    decision: SupportDecision = run_output.content

    with langwatch.trace(name="support-output-eval"):
        score = customer_reply_score(decision)

        langwatch.get_current_span().add_evaluation(
            name="business_rules",
            score=score,
            passed=score >= 0.8,
            details={
                "intent": decision.intent,
                "needs_human": decision.needs_human,
                "policy_ids": decision.cited_policy_ids,
                "session_id": getattr(session, "session_id", None),
                "user_id": user_id,
            },
        )

Adjunta el hook a tu agente de Agno:

support_agent = Agent(
    name="Support Router",
    model=OpenAIResponses(id="gpt-5.2"),
    output_schema=SupportDecision,
    post_hooks=[evaluate_output_in_background],
)

Y si lo expones mediante AgentOS:

from agno.os import AgentOS

agent_os = AgentOS(
    name="Support AgentOS",
    agents=[support_agent],
    tracing=True,
)

app = agent_os.get_app()

Por qué funciona este patrón

• el usuario recibe la respuesta de inmediato
• la evaluación sigue ejecutándose sobre salidas reales de producción
• LangWatch sigue recibiendo datos de evaluación estructurados
• puedes generar alertas por puntuaciones bajas sin ralentizar la solicitud principal

Para la mayoría de los productos basados en agentes, este es el punto de equilibrio ideal en producción.

Paso 9: Incorporar las fallas de producción a los datasets

La documentación actual de datasets de LangWatch permite poblar datasets continuamente a partir de trazas, una de las funciones más útiles de todo el sistema.

Esto crea un ciclo de calidad:

Production traffic
    │
    ▼
LangWatch traces
    │
    ▼
Monitors find low-scoring runs
    │
    ▼
Add those traces into a dataset
    │
    ▼
Re-run experiments before the next release

Así es como un stack de evaluación deja de ser un dashboard y se convierte en un sistema de aprendizaje.

En la práctica, esto es lo que recomiendo:

1. Empieza con un conjunto de referencia de 30 a 50 filas seleccionadas manualmente.
2. Agrega un segundo dataset para fallas reales de producción.
3. Incorpora las fallas recurrentes de producción al conjunto de referencia una vez que las comprendas.

Esto mantiene tu suite de evaluaciones basada en tráfico real en lugar de en un optimismo sintético.

Paso 10: Saber cuándo usar también las evaluaciones nativas de Agno

Agno ahora tiene su propio sistema de evaluación para exactitud, agent-as-judge, rendimiento y confiabilidad. Eso no es una razón para prescindir de LangWatch. Es una razón para elegir con criterio.

Esta es la división práctica:

Mi configuración preferida para producción es:

• usar las evaluaciones nativas de Agno para el comportamiento y rendimiento dentro del framework
• usar LangWatch para aprobar releases, compartir datasets, monitorear producción y analizar la calidad entre ejecuciones

Esto evita duplicar responsabilidades y, al mismo tiempo, aprovecha ambas herramientas.

Un patrón avanzado: pruebas de extremo a extremo del comportamiento del agente

Los experimentos offline basados en filas no son suficientes para todos los agentes. Si tu sistema con Agno es de múltiples turnos, usa muchas herramientas o se basa en workflows, tarde o temprano también querrás pruebas basadas en escenarios.

La capa de pruebas Scenario de LangWatch está diseñada para ese nivel más amplio:

Level 1: unit and integration tests
Level 2: offline evals on components and outputs
Level 3: scenario tests for full multi-turn behavior

Un patrón útil es:

• usar experimentos de LangWatch para evaluar la calidad de las salidas a nivel de fila
• usar Scenario para evaluar el comportamiento de una conversación completa
• usar hooks de AgentOS y monitores para detectar desviaciones en producción

Esto te da cobertura en todo el stack, en lugar de intentar forzar un solo tipo de prueba para todo.

Un plan de implementación de cero a avanzado

Si empiezas desde cero, lo implementaría en este orden:

1. Instrumenta Agno con LangWatch e inspecciona algunas trazas manualmente.
2. Agrega output_schema al agente para que la salida sea tipada.
3. Crea un pequeño dataset de referencia en LangWatch.
4. Agrega una función de puntuación determinista personalizada para comprobar el cumplimiento de las reglas de negocio.
5. Agrega un evaluador integrado para fundamentación, seguridad o claridad.
6. Compara dos targets: versiones de prompts, modelos o recuperadores.
7. Agrega un guardrail síncrono para la ruta de mayor riesgo.
8. Mueve las evaluaciones no críticas a post-hooks de AgentOS en segundo plano.
9. Agrega continuamente a un dataset las trazas con puntuaciones bajas.
10. Agrega pruebas de escenarios si el sistema es de múltiples turnos o depende mucho de workflows.

Ese camino te da señales útiles rápidamente sin tener que construir una plataforma de evaluación enorme de una sola vez.

Errores comunes

• Tratar el tracing y la evaluación como si fueran lo mismo. El tracing es la base; la evaluación es la capa de juicio.
• Evaluar solo el texto de la respuesta final e ignorar los campos de negocio estructurados.
• Usar guardrails para todo y luego preguntarse por qué aumentó la latencia.
• Encargar a hooks en segundo plano decisiones de flujo de control que no pueden hacer cumplir de forma segura.
• Crear un dataset sintético y nunca actualizarlo con fallas de producción.
• Comparar prompts o modelos sin adjuntar metadatos a los targets.

Conclusión

Si usas Agno y AgentOS, LangWatch no es solo “otro dashboard”. Es la parte del stack que te permite pasar de una calidad anecdótica a una calidad medible.

El camino de cero a avanzado es directo:

• instrumenta primero
• tipa las salidas
• ejecuta experimentos por lotes
• agrega monitores online
• mantén síncrona la lógica bloqueante
• mueve la evaluación no bloqueante a hooks de AgentOS en segundo plano
• reincorpora continuamente las fallas de producción a los datasets

Esa combinación es sólida porque cada capa se concentra en lo que hace mejor:

Agno builds the agent.
AgentOS runs the agent.
LangWatch tells you whether the agent is actually getting better.

Otras alternativas a LangWatch

LangWatch encaja bien para equipos que quieren una sola plataforma para tracing, datasets, experimentos, monitores y guardrails. No es la única buena opción.

Si estás evaluando plataformas para un stack con Agno o AgentOS, estas son las alternativas que revisaría primero:

Una regla sencilla para elegir

If your main problem is "evaluate and monitor my production agent stack":
  LangWatch is a strong default

If your main problem is "my stack is already LangChain / LangGraph":
  LangSmith is the easiest natural fit

If your main problem is "I want open source plus a broad platform":
  Langfuse or Phoenix are both worth serious consideration

If your main problem is "I want evals to be the center of the workflow":
  Braintrust is especially compelling

If your main problem is "I want gateway + observability and I can bring my own evaluators":
  Helicone is a practical alternative

Lo importante no es elegir la “mejor” marca. Es hacer coincidir la plataforma con el papel que desempeñará en tu sistema:

• evaluación cercana al entorno de ejecución
• flujo de experimentación
• depuración de trazas
• análisis del gateway
• gestión de prompts y datasets

Para quienes usan Agno y AgentOS en particular, LangWatch sigue siendo atractivo porque se ajusta claramente a las mismas necesidades de producción en las que se centró este artículo: trazas, experimentos offline, monitores online y guardrails. Pero si tu organización ya ha estandarizado una de las alternativas anteriores, también puedes desarrollar allí una práctica de evaluación sólida.

Fuentes

• Descripción general de las evaluaciones de LangWatch
• Experimentos de LangWatch mediante el SDK
• Evaluadores integrados de LangWatch
• Puntuación personalizada de LangWatch
• Descripción general de la evaluación online de LangWatch
• Descripción general de los datasets de LangWatch
• Crear datasets automáticamente a partir de trazas con LangWatch
• Caso de uso de salidas estructuradas de LangWatch
• Integración de Agno con LangWatch
• Agente de Agno con salida estructurada
• Descripción general de las evaluaciones de Agno
• Evaluaciones agent-as-judge de Agno
• Descripción general de los hooks de Agno
• Descripción general de Agno AgentOS
• Hooks en segundo plano de Agno en AgentOS
• Descripción general de la documentación de LangSmith
• Descripción general de la documentación de Langfuse
• Inicio rápido de evaluación de Braintrust
• Observa tu aplicación con Braintrust
• Evaluaciones remotas de Braintrust
• SDK de evaluaciones del lado del cliente de Phoenix
• Ejecutar evaluaciones sobre trazas de Phoenix
• Inicio rápido de Helicone
• Puntuaciones de evaluación de Helicone