Seguimiento de trazas

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 es un ciclo de trabajo. Una traza muestra los pasos de un turno: respuestas del modelo, llamadas a herramientas y trabajo delegado a otros agentes.

El panel de seguimiento de trazas muestra lo que hizo tu agente, incluidos los datos registrados de cada paso: entradas, salidas, duración y estado.

Para consultar el estado de la sesión, los eventos en vivo, las salidas guardadas y el uso a través de la API, comienza por Observabilidad.

El seguimiento de trazas 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 donde ejecutaste tu agente.
2. Encuentra tu sesión con Buscar registros. Usa Agregar filtro para filtrar por modelo, estado o fecha.
3. Selecciona la sesión para abrir su línea de tiempo y su lista de turnos.
4. Expande un turno y luego selecciona un paso en la línea de tiempo o en la lista de eventos para ver sus detalles.

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

Leer una traza

Comienza por la sesión y luego explora un turno:

1. Sesión: cada entrada en Registros → Agentes es una sesión. Ábrela para ver su línea de tiempo y su lista de turnos. Por ejemplo, un usuario puede preguntar sobre un pedido y luego hacer una pregunta de seguimiento en la misma 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. Un mensaje de seguimiento enviado después de que termina el turno inicia otro turno en la misma sesión.
3. Pasos dentro 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, duración, horas de inicio y finalización, y datos registrados:

Agente

Un span de agente agrupa el trabajo realizado por el agente raíz o por un subagente: otro agente al que se le encarga 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 conteos de tokens registrados de ese agente. Estos conteos corresponden al agente en sí; no incluyen a sus subagentes.
• Duración y Estado del resultado: cuánto tardó el trabajo registrado y si se completó, falló o está 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 devuelve un resultado, el modelo puede producir otra respuesta en una nueva generación.

• Entrada: las entradas registradas asociadas con 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, cuando se haya registrado.

Herramienta

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

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

• Llamada: la solicitud a la herramienta, incluidos su nombre y sus argumentos cuando estén presentes.
• Resultado: la respuesta registrada de la herramienta, cuando esté disponible.
• Estado del resultado y Error: el resultado registrado y los detalles del error, cuando estén presentes.

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). Su respuesta y su error se registran allí como output y error, cuando estén disponibles. El panel independiente Resultado puede estar vacío porque la respuesta MCP se almacena en Llamada.

Tiempos y estado

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

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

La duración de un span de agente incluye sus pasos secundarios. Los pasos pueden superponerse: dos subagentes que se ejecutan al mismo tiempo durante 10 segundos abarcan aproximadamente 10 segundos de tiempo transcurrido.

Uso de tokens

Tokens, en el resumen de la sesión, muestra el uso de la sesión. Uso, en un span de agente, muestra los conteos de tokens registrados de ese agente.

Los datos de uso pueden llegar después de que termina el turno. Un valor en blanco o null significa que se desconoce el conteo. No significa que el agente haya usado cero tokens. Los conteos pueden cambiar a medida que haya más datos de uso disponibles y no constituyen una factura definitiva.

Cuándo están listas las trazas

Las trazas se generan después de que termina un turno. La respuesta del agente puede aparecer antes de que su traza o sus datos de uso de tokens estén listos.

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

Exportar trazas de sesiones

Descarga las trazas de la sesión para inspeccionarlas en otra herramienta de seguimiento de trazas. El punto de acceso GET /v1/agents/sessions/{session_id}/traces devuelve una página de trazas que contienen datos 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 OTLP. Envíala al punto de acceso OTLP/HTTP de tu proveedor de seguimiento de trazas con la autenticación del proveedor.

Para exportar la sesión completa, revisa trace-page.json. Cuando has_more sea true, solicita la siguiente página con last_id como valor de after, manteniendo el mismo valor de order. Guarda o sube cada página antes de obtener la siguiente y repite el proceso hasta que has_more sea false.

Las exportaciones incluyen solo las trazas disponibles al realizar cada solicitud. Para exportar el historial, espera a que terminen los turnos de la sesión y deja tiempo para que aparezcan las trazas. La exportación no configura la entrega automática de trazas futuras.

Exportar trazas de un agente

Para exportar 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 en data, usa su id para exportar todas las páginas de trazas de la sesión como se describió antes.
2. Cuando la lista de sesiones tenga has_more: true, pasa el valor de last_id de esa lista como after para obtener la siguiente página. Mantén los mismos valores de agent_id y order.
3. Repite el proceso hasta que la lista de sesiones tenga 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 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 dos subagentes ejecutan un comando y obtienen documentos. A continuación se simplifican los nombres de los subagentes; los conteos 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 está Completado, con una duración de 1m 37s.

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

Este árbol agrupa las generaciones y las llamadas a herramientas repetidas. Muestra las relaciones jerárquicas; la línea de tiempo muestra cuándo se ejecutó cada paso.

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 resultantes 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 send_input_call. Sus respuestas del modelo y herramientas pertenecen a los spans respectivos de esos subagentes.

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

Una llamada a una herramienta MCP

El span demo_capability_probe del agente raíz es un span de Herramienta completado con una duración de 87ms. 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 MCP en output. El panel independiente Resultado muestra null. El campo Span padre del span apunta al agente raíz.

Los dos spans notion.fetch del subagente B tienen la misma estructura: mcp_call como tipo de herramienta, la respuesta MCP en Llamada y el subagente como padre.

Tiempos y uso en esta sesión

Los dos spans de subagente se superponen en la línea de tiempo. El subagente A tarda 24s y el subagente B tarda 21s, ambos dentro del span de 1m 37s del agente raíz. El panel redondea estas duraciones al mostrarlas.

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

En esta sesión registrada, los totales de los tres agentes suman los 252 468 tokens que se muestran en el encabezado de la sesión.