Ir al contenido principal
Español— Elegir un idioma
Menú

Seguimiento y observabilidad

Lección 14 de 25 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Seguimiento y observabilidad
  2. Seguimiento integrado
  3. Nombrar los seguimientos
  4. Dividir un flujo de trabajo en pasos
  5. Procesadores de seguimiento personalizados
  6. Exportar a sistemas externos
  7. No perder los últimos seguimientos
  8. Desactivar el seguimiento
  9. Métricas clave que debes monitorizar
  10. Puntos clave

Actualizado el 3 de noviembre de 2026. Anteriormente, los procesadores de seguimiento leían trace.start_time, trace.end_time y span.name, propiedades que no existen en el SDK: un seguimiento (trace) no tiene marca de tiempo y un intervalo (span) contiene started_at, ended_at y span_data. El procesador de exportación no implementaba on_trace_start, un método abstracto: instanciarlo provocaba un TypeError. Los «seguimientos anidados» creaban un nuevo seguimiento dentro de otro, algo que el SDK marca como un error probable: los pasos ahora utilizan custom_span(). Novedades: flush_traces(), gestión de datos sensibles y Retención Cero de Datos. Código verificado con openai-agents 0.24.0. Fuentes: Seguimiento (documentación del SDK) · openai-agents-python.

Seguimiento y observabilidad

Un agente en producción es una caja negra si no registras sus acciones. Cuando un cliente se queja de una respuesta absurda, no tienes ni la solicitud exacta, ni las herramientas llamadas, ni los valores que devolvieron. El seguimiento del SDK registra cada paso de la ejecución: llamadas al modelo, herramientas utilizadas, transferencias y barreras de seguridad. Esta es tu herramienta principal para depurar, optimizar y auditar tus agentes.

Seguimiento integrado

Buena noticia: no necesitas activar nada. El SDK realiza un seguimiento automático de cada ejecución y, por defecto, envía los datos al panel de control de OpenAI en platform.openai.com. El siguiente agente, escrito sin una sola instrucción de seguimiento, ya genera un registro utilizable.

from agents import Agent, Runner, function_tool

@function_tool
def search_product(name: str) -> str:
    """Busca un producto en el catálogo."""
    return f"Producto encontrado: {name}, precio 29,99 €"

agent = Agent(
    name="Shop Agent",
    instructions="Ayudas a los clientes a encontrar productos.",
    tools=[search_product],
    model="gpt-5.6-terra",
)

# Cada ejecución crea automáticamente un seguimiento
result = Runner.run_sync(agent, "Buscar el portátil pro")

Visita el panel de control para ver el seguimiento completo: duración, tokens consumidos, herramientas llamadas y la respuesta final.

Nombrar los seguimientos

Tras unas cientos de ejecuciones, el panel de control se convierte en una lista indiferenciada. Asigna nombres significativos a tus seguimientos para encontrarlos fácilmente; un nombre de proceso de negocio es mejor que un ID técnico.

from agents import trace

with trace("pedido-cliente-premium"):
    result = await Runner.run(
        agent,
        "Quiero pedir 5 portátiles para mi equipo",
    )

El nombre del seguimiento aparece en el panel de control y facilita el filtrado.

Dividir un flujo de trabajo en pasos

Para un flujo de trabajo con múltiples llamadas, abre un único seguimiento alrededor de todo el proceso y marca cada paso con custom_span(). No anides un trace() dentro de otro: el SDK registrará entonces la advertencia Trace already exists. Creating a new trace, but this is probably a mistake. Los intervalos (spans), en cambio, están diseñados para anidarse: cada uno se sitúa bajo el intervalo actual.

from agents import Runner, custom_span, trace


async def process_order(message: str, conversation_id: str):
    with trace("flujo-pedido", group_id=conversation_id):
        with custom_span("paso-1-comprension"):
            result_understanding = await Runner.run(triage_agent, message)

        with custom_span("paso-2-procesamiento"):
            result_processing = await Runner.run(
                order_agent,
                result_understanding.to_input_list(),
            )

        with custom_span("paso-3-confirmacion", data={"step": 3}):
            result_final = await Runner.run(
                confirmation_agent,
                result_processing.to_input_list(),
            )

    return result_final.final_output

En el panel de control, el seguimiento flujo-pedido muestra los tres pasos y, bajo cada uno, los intervalos automáticos de ejecución: agente, llamadas al modelo, herramientas. El group_id vincula los seguimientos de la misma conversación, por ejemplo, usando el ID de tu hilo.

Por defecto, el SDK envuelve cada Runner.run() en un seguimiento llamado Agent workflow, y dentro de los seguimientos incluye el agente, cada generación del modelo, cada llamada a función, las barreras de seguridad y las transferencias. Para una jerarquía más compacta, la documentación sugiere excluir los intervalos automáticos de tarea y turno:

from agents import RunConfig

result = await Runner.run(
    agent,
    "Hola",
    run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)

Procesadores de seguimiento personalizados

El panel de control de OpenAI es cómodo, pero es probable que tu equipo de operaciones supervise todo lo demás en otro lugar. Para enviar seguimientos a tu propio sistema, escribe un procesador: este recibe eventos de inicio y fin, tanto para el seguimiento completo como para cada intervalo. Los seis métodos de TracingProcessor son abstractos: debes implementarlos todos, aunque estén vacíos, o la instanciación fallará.

Esto es lo que expone realmente cada objeto: un seguimiento tiene un trace_id y un name, y su método export() devuelve también group_id y metadata; no tiene marca de tiempo. Un intervalo tiene span_id, trace_id, parent_id, started_at y ended_at (cadenas ISO 8601), y span_data, cuyo atributo type es agent, generation, function, handoff, guardrail, custom, etc. Por tanto, la duración del seguimiento se mide en el procesador.

import time
from datetime import datetime
from typing import Any

from agents import add_trace_processor
from agents.tracing import Span, Trace, TracingProcessor


class MyTraceProcessor(TracingProcessor):
    def __init__(self) -> None:
        self._starts: dict[str, float] = {}

    def on_trace_start(self, trace: Trace) -> None:
        self._starts[trace.trace_id] = time.monotonic()
        print(f"[INICIO SEGUIMIENTO] {trace.name} - {trace.trace_id}")

    def on_trace_end(self, trace: Trace) -> None:
        duration = time.monotonic() - self._starts.pop(trace.trace_id, time.monotonic())
        print(f"[FIN SEGUIMIENTO] {trace.name} - duración: {duration:.2f} s")

    def on_span_start(self, span: Span[Any]) -> None:
        print(f"  [INICIO INTERVALO] {span.span_data.type}")

    def on_span_end(self, span: Span[Any]) -> None:
        if span.started_at and span.ended_at:
            duration = datetime.fromisoformat(span.ended_at) - datetime.fromisoformat(span.started_at)
            print(f"  [FIN INTERVALO] {span.span_data.type} - {duration.total_seconds():.2f} s")

    def shutdown(self) -> None:
        pass

    def force_flush(self) -> None:
        pass


add_trace_processor(MyTraceProcessor())

add_trace_processor() añade tu procesador al original: los seguimientos siguen yendo al panel de control de OpenAI. set_trace_processors() reemplaza los procesadores por defecto: ya no va nada a OpenAI, a menos que vuelvas a incluir su exportador en la lista manualmente.

Exportar a sistemas externos

Para una herramienta de observabilidad, solo necesitas reformatear los intervalos. El ejemplo siguiente escribe una línea JSON por intervalo finalizado, un formato que la mayoría de los recopiladores de registros saben ingerir; span.export() ya proporciona un diccionario completo.

import json
import logging
from typing import Any

from agents.tracing import Span, Trace, TracingProcessor

logger = logging.getLogger("agent-traces")


class JsonExportProcessor(TracingProcessor):
    """Escribe cada intervalo finalizado como JSON, para un recopilador de registros."""

    def on_trace_start(self, trace: Trace) -> None:
        pass

    def on_trace_end(self, trace: Trace) -> None:
        logger.info(json.dumps(trace.export(), default=str))

    def on_span_start(self, span: Span[Any]) -> None:
        pass

    def on_span_end(self, span: Span[Any]) -> None:
        logger.info(json.dumps(span.export(), default=str))

    def shutdown(self) -> None:
        pass

    def force_flush(self) -> None:
        pass

Vigila lo que exportas: por defecto, los intervalos de generación contienen las entradas y salidas del modelo, y los intervalos de función contienen los argumentos y resultados de las herramientas. Para excluirlos, pasa RunConfig(trace_include_sensitive_data=False) o establece la variable de entorno OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Para integraciones listas para usar, la documentación del SDK enumera muchas herramientas de terceros que proporcionan su propio procesador.

No perder los últimos seguimientos

El exportador por defecto envía los seguimientos en segundo plano cada pocos segundos. En un worker que procesa tareas y no se detiene, o en un script corto, llama a flush_traces() después de cerrar el seguimiento para forzar el envío:

from agents import flush_traces

with trace("procesamiento-nocturno"):
    await Runner.run(agent, "Resumir los tickets de hoy")
flush_traces()  # después de que termine el seguimiento, nunca en medio

Desactivar el seguimiento

Hay un caso en el que el seguimiento estorba más de lo que ayuda: una suite de pruebas que ejecuta cientos de agentes simulados y ensucia tu panel de control. En pruebas o durante el desarrollo local, puedes desactivarlo, ya sea globalmente o para una única ejecución.

from agents import RunConfig, set_tracing_disabled

# Desactivar completamente (o variable de entorno OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)

# O para una única ejecución
result = await Runner.run(agent, "Mensaje de prueba", run_config=RunConfig(tracing_disabled=True))

Un último punto, este contractual: según la documentación, el seguimiento hacia OpenAI no está disponible para organizaciones sujetas a una política de Retención Cero de Datos. En este caso, solo tu propio procesador, instalado con set_trace_processors(), te proporcionará seguimientos.

Métricas clave que debes monitorizar

Ahora bien, ¿qué debes observar? En producción, seis indicadores bastan para calificar la salud de un agente. La latencia total —el tiempo entre la solicitud y la respuesta final— es lo que perciben tus usuarios; suele explicarse principalmente por el número de turnos, es decir, las veces que se ejecutó el bucle del agente. Los tokens consumidos, tanto de entrada como de salida por ejecución, determinan tu factura.

Los otros tres se relacionan con la calidad. La tasa de fallo de herramientas, el porcentaje de herramientas que devuelven un error, revela una API de terceros inestable o argumentos mal generados. La tasa de activación de barreras, visible en los intervalos guardrail, mide la frecuencia de los bloqueos: un pico repentino señala ya sea un ataque o una barrera que se ha vuelto demasiado estricta. Por último, la distribución de transferencias te indica qué agente responde con más frecuencia y, por tanto, si tu triaje está enviando las solicitudes adonde deben ir.

Puntos clave

  • El SDK realiza un seguimiento automático de cada ejecución hacia el panel de control de OpenAI (excepto para organizaciones con Retención Cero de Datos)
  • Un trace() por flujo de trabajo; marca los pasos con custom_span() y usa group_id para vincular seguimientos de una conversación
  • Un seguimiento no tiene marca de tiempo; un intervalo tiene started_at, ended_at y span_data.type
  • Un TracingProcessor implementa sus seis métodos; add_trace_processor() añade, set_trace_processors() reemplaza
  • trace_include_sensitive_data=False excluye entradas y salidas; flush_traces() fuerza el envío
  • Desactiva el seguimiento en las pruebas con set_tracing_disabled(True) o RunConfig(tracing_disabled=True)