Trazado

Una sesión reúne la conversación y el trabajo de tu agente. Una sesión puede contener varios turnos, cada uno de los cuales corresponde a un ciclo de trabajo. Una traza muestra los pasos de un turno: las respuestas del modelo, las llamadas a herramientas y el trabajo delegado a otros agentes.

El panel de trazas muestra lo que hizo tu agente, incluidas las entradas, las salidas, la duración y el estado que se registraron en cada paso.

Para consultar el estado de la sesión, los eventos en vivo, la salida guardada y los datos de uso a través de la API, empieza por Observabilidad.

El trazado está habilitado de forma predeterminada para las sesiones nuevas. Puedes inspeccionar las trazas en el panel o exportarlas a través de la API.

Abrir una traza

1. Abre Registros → Agentes y selecciona el proyecto en el que ejecutaste tu agente.
2. Encuentra tu sesión con Buscar en los registros. Usa Agregar filtro para filtrar por modelo, estado o fecha.
3. Selecciona la sesión para abrir su cronología y su lista de turnos.
4. Expande un turno y selecciona un paso en la cronología o en la lista de eventos para ver sus detalles.

El resumen de la sesión muestra el estado, el modelo, la hora de inicio, la última actividad, la cantidad de turnos y el uso de tokens registrado.

Leer una traza

Empieza por la sesión y luego examina un turno:

1. Sesión: cada entrada en Registros → Agentes corresponde a una sesión. Ábrela para ver su cronología y su lista de turnos. Por ejemplo, un usuario puede hacer una pregunta sobre un pedido y luego hacer otra pregunta sobre el mismo tema en esa sesión.
2. Turno: expande un turno para ver el trabajo realizado durante ese ciclo. Un turno puede incluir varias respuestas del modelo y llamadas a herramientas. Si se envía otro mensaje después de que termina el turno, comienza un nuevo turno en la misma sesión.
3. Pasos del turno: la traza agrupa las respuestas del modelo y las llamadas a herramientas bajo el agente raíz o el subagente que las realizó. Cada paso registrado se denomina span.

Selecciona un span para ver su estado, su duración, sus horas de inicio y fin, y los datos registrados:

Agente

Un span de agente agrupa el trabajo realizado por el agente raíz o por un subagente, es decir, otro agente al que se le encargó parte de la tarea. Las respuestas del modelo y las llamadas a herramientas aparecen bajo el agente que las realizó.

El panel de detalles muestra:

• Tipo de agente: agente raíz (root) o subagente (subagent).
• Agente: su ID, nombre, modelo e instrucciones, cuando se hayan registrado.
• Uso: los recuentos de tokens registrados para ese agente. Estos recuentos incluyen únicamente los tokens del propio agente y excluyen los de sus subagentes.
• Duración y Estado del resultado: cuánto duró el trabajo registrado y si se completó, falló o quedó incompleto.

Generación

Un span de generación agrupa las entradas y salidas registradas del modelo. Cada turno puede tener varias generaciones.

Durante la inferencia, el modelo lee su entrada y produce una respuesta. Esa respuesta puede solicitar el uso de una herramienta. Una vez que la herramienta responde, el modelo puede producir otra respuesta en una nueva generación.

• Entrada: las entradas registradas para esa respuesta, como un mensaje del usuario o el resultado de una herramienta.
• Salida: los elementos registrados que produjo el modelo, como el texto de una respuesta o una llamada a una herramienta.
• Modelo: el modelo utilizado para la respuesta, si se registró.

Herramienta

Un span de herramienta describe una llamada a una herramienta y el resultado registrado.

Los spans de herramienta incluyen llamadas a tus funciones y a herramientas de servidores MCP (Model Context Protocol). Las búsquedas web y la ejecución de comandos también pueden aparecer como spans de herramienta.

• Llamada: la solicitud a la herramienta, con su nombre y los argumentos, si se incluyen.
• Resultado: la respuesta registrada de la herramienta, si está disponible.
• Estado del resultado y Error: el resultado registrado y los detalles del error, si los hay.

En una llamada a una herramienta MCP, Llamada contiene la etiqueta del servidor (server_label), el nombre de la herramienta (name) y los argumentos (arguments). La respuesta y el error se registran allí como output y error, si están disponibles. El panel Resultado puede estar vacío porque la respuesta de MCP se guarda en Llamada.

Tiempos y estado

La cronología muestra el orden de los pasos y cuáles se superponen. Acercar permite ver los pasos más breves con mayor detalle. Ajustar cronología muestra la sesión completa.

Cada span muestra su duración y el estado del resultado. Los spans que fallaron también pueden incluir los detalles registrados del error.

La duración de un span de agente incluye la de sus pasos secundarios. Los pasos pueden superponerse: si dos subagentes se ejecutan al mismo tiempo durante 10 segundos, el tiempo transcurrido es de unos 10 segundos.

Uso de tokens

El campo Tokens del resumen de la sesión muestra el uso de toda la sesión. Uso en un span de agente muestra los recuentos de tokens registrados para ese agente.

Los datos de uso pueden llegar después de que termine el turno. Un valor en blanco o null indica que se desconoce el recuento. No significa que el agente haya usado cero tokens. Los recuentos pueden cambiar a medida que se reciben más datos de uso y no equivalen a una factura definitiva.

Cuándo están disponibles las trazas

Las trazas se generan una vez que termina el turno. La respuesta del agente puede aparecer antes de que estén disponibles su traza o sus datos de uso de tokens.

Los eventos de sesión en vivo muestran el progreso mientras el agente sigue trabajando.

Exportar las trazas de una sesión

Descarga las trazas de la sesión para inspeccionarlas en otra herramienta de trazado. El punto de acceso GET /v1/agents/sessions/{session_id}/traces devuelve una página de trazas con datos en formato JSON de OpenTelemetry Protocol (OTLP).

Configura OPENAI_API_KEY y reemplaza sess_123 por el ID de tu sesión. Este ejemplo usa cURL y jq para guardar una página como traces.otlp.json:

1
2
3
4
5
6curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  --output trace-page.json && \
jq '{resourceSpans: [.data[].otlp.resourceSpans[]]}' trace-page.json > traces.otlp.json

El comando combina las trazas de esa página en una sola carga útil de OTLP. Envíala al punto de acceso OTLP/HTTP de tu proveedor de trazado con el método de autenticación del proveedor.

Para exportar toda la sesión, revisa trace-page.json. Si has_more es true, solicita la siguiente página usando el valor de last_id como after y conserva el mismo valor de order. Guarda o sube cada página antes de solicitar la siguiente y repite el proceso hasta que has_more sea false.

Las exportaciones solo incluyen las trazas disponibles en el momento de cada solicitud. Para exportar datos históricos, espera a que terminen los turnos de la sesión y da tiempo a que aparezcan las trazas. La exportación no configura la entrega automática de trazas futuras.

Exportar las trazas de un agente

Para exportar las trazas de las distintas sesiones de un agente, primero obtén la lista de sesiones con el filtro agent_id. Reemplaza agent_123 por el ID de tu agente:

1
2
3
4curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions?agent_id=agent_123&limit=100&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

1. Para cada sesión de data, usa su id para exportar todas sus páginas de trazas como se describió antes.
2. Si la lista de sesiones indica has_more: true, pasa el valor de last_id de esa lista como after para obtener la siguiente página. Conserva los mismos valores de agent_id y order.
3. Repite el proceso hasta que la lista de sesiones indique has_more: false.

El filtro busca coincidencias con el agente raíz de la sesión. Mantén el cursor de la lista de sesiones separado del cursor de las trazas de cada sesión.

Ejemplo: un turno con dos subagentes

Este ejemplo se basa en una sesión registrada. El agente raíz llama a una herramienta MCP mientras un subagente ejecuta un comando y otro obtiene documentos. A continuación se usan nombres simplificados para los subagentes. Los recuentos y las duraciones provienen de la traza registrada.

Sesión y turno

El encabezado de la sesión muestra 1 turno, 10 llamadas a herramientas y 252 468 tokens. El estado de la sesión es Inactiva y el Turno 1 figura como Completado, con una duración de 1 min 37 s.

Al expandir el turno, se ven el agente raíz y sus pasos secundarios. La traza contiene 3 spans de agente (el agente raíz y dos subagentes), 11 spans de generación y 10 spans de herramienta.

Este árbol agrupa las generaciones y las llamadas a herramientas que se repiten. El árbol muestra la jerarquía de los pasos y la cronología muestra cuándo se ejecutó cada uno.

Session: Idle
└── Turn 1: Completed                              1m 37s
    └── Root agent                                1m 37s
        ├── 6 generations
        ├── 2 tools: spawn_agent_call
        ├── Subagent A                               24s
        │   ├── 2 generations
        │   └── Tool: command_execution               2s
        ├── Subagent B                               21s
        │   ├── 3 generations
        │   ├── 2 tools: notion.fetch              2s each
        │   └── Tool: send_input_call                 0ms
        ├── Tool: demo_capability_probe              87ms
        └── 3 tools: wait_for_agents_call

Trabajo del modelo y delegación

La primera Generación del agente raíz incluye el mensaje del usuario en Entrada. Su Salida contiene mensajes y dos elementos spawn_agent_call. Esas llamadas también aparecen como spans de Herramienta, y los subagentes que se crean aparecen como spans de Agente bajo el agente raíz.

El subagente A tiene sus propias generaciones y una llamada a la herramienta command_execution. El subagente B tiene tres generaciones, dos llamadas MCP a notion.fetch y una llamada a send_input_call. Las respuestas del modelo y las herramientas de cada subagente pertenecen a su span correspondiente.

El agente raíz también tiene tres spans de herramienta wait_for_agents_call. Su última generación contiene un mensaje y tiene una duración registrada de 6 s.

Una llamada a una herramienta MCP

El span demo_capability_probe del agente raíz es un span de Herramienta completado que duró 87 ms. Su Tipo de herramienta es mcp_call.

El panel Llamada incluye estos campos:

123456{
  "type": "mcp_call",
  "server_label": "demo_local",
  "name": "demo_capability_probe",
  "status": "completed"
}

Este fragmento muestra parte de la llamada registrada. El mismo panel contiene sus arguments y la respuesta de MCP en output. El panel Resultado, que se muestra por separado, tiene el valor null. El campo Span principal apunta al agente raíz.

Los dos spans de notion.fetch del subagente B tienen la misma estructura: el tipo de herramienta es mcp_call, la respuesta de MCP está en Llamada y el subagente es el elemento principal de ambos spans.

Tiempos y uso en esta sesión

Los spans de los dos subagentes se superponen en la cronología. El subagente A tarda 24 s y el subagente B tarda 21 s. Ambos se ejecutan dentro del span de 1 min 37 s del agente raíz. El panel redondea las duraciones que muestra.

El panel Uso de cada span de agente muestra los recuentos de tokens registrados para ese agente:

En esta sesión registrada, la suma de los totales de los tres agentes coincide con los 252 468 tokens que aparecen en el encabezado de la sesión.