Seguimientos de agente

Acerca de los seguimientos

Traces are detailed records of everything an agent does during a run, including steps taken, data processed, decisions made, and results generated. Each trace captures a complete timeline of the agent’s behavior, including timestamps, errors, inputs/outputs, and contextual metadata. Use traces for:

• Depuración y resolución de problemas: identifica exactamente dónde falló o se comportó de forma inesperada un agente.
• Análisis de rendimiento: evalúa la latencia, los errores y el rendimiento en las ejecuciones de agentes para optimizar el comportamiento.
• Cumplimiento y auditoría: mantiene un registro verificable de lo que hizo el agente, cuándo y cómo. Es esencial para las auditorías o los flujos de trabajo regulados.
• Mejora continua: utiliza información de seguimiento para ajustar la lógica del agente, adaptar el comportamiento o entrenar nuevos modelos.

En la siguiente tabla se describen los casos de uso comunes en los que la visualización del seguimiento puede mejorar tu capacidad para depurar, analizar y optimizar el comportamiento del agente. Cada ejemplo resalta cómo los datos de seguimiento ayudan a descubrir información y a impulsar una mejor toma de decisiones durante el desarrollo y la supervisión del runtime.

Use case	Qué te ayudan a hacer los seguimientos
Fallos de agente durante la llamada a la herramienta	Busca e inspecciona el paso exacto, las entradas, las salidas y el error
Rendimiento bajo	Usa marcas de tiempo para localizar cuellos de botella
Investigar un pico de errores	Filtra ejecuciones por estado y sigue el patrón
Verificar una corrección de producción	Reproduce la ejecución original y confirma que la incidencia ya no se produce
Preparar un informe de auditoría	Exporta o revisa seguimientos que muestren las rutas de decisión y los datos gestionados

Tipos de seguimiento

Los seguimientos son de dos tipos diferentes, cada uno con un propósito específico para comprender y analizar el comportamiento del agente:

• Seguimientos de ejecución de agente: estos seguimientos capturan la ejecución paso a paso de un agente durante una ejecución en vivo o programada. Muestran cómo el agente procesa datos, invoca herramientas, gestiona condiciones y responde a diferentes estados en tiempo real.
• Seguimientos de ejecución de evaluación: los seguimientos de evaluación se generan cuando un agente se prueba con entradas predefinidas, normalmente durante evaluaciones de modelos, validaciones de escenarios o casos de prueba. Estos ayudan a evaluar la precisión del agente, la calidad de la decisión y el comportamiento en condiciones controladas.

Acceder a los seguimientos

Puedes acceder a ambos tipos de seguimientos desde dos ubicaciones clave:

• Agent Builder: mientras diseñas o pruebas tu agente, los seguimientos están disponibles directamente en el creador:
  • El panel inferior se abre automáticamente en la pestaña Seguimiento de ejecución cuando ejecutas tu agente, mostrando seguimientos en vivo para la ejecución actual. También puedes cambiar a la pestaña Historial para ver las ejecuciones anteriores y añadirlas directamente a los conjuntos de evaluación.
  • Las pestañas Evaluaciones y Salida proporcionan otra vista de las ejecuciones recientes, donde puedes inspeccionar el comportamiento y los resultados junto con la definición de tu agente.
• Página Instancias de agente : ve a la sección Agentes > Instancias . Desde aquí, selecciona un agente específico y selecciona cualquier ejecución para abrir su vista de seguimiento, que incluye el panel visual completo de seguimiento y registro.

Al ver los seguimientos para las ejecuciones de agente o las ejecuciones de evaluación, obtienes visibilidad de la ejecución del agente. Puedes:

• Consulta los resultados de la ejecución, como se indica con los nodos codificados por colores: correcto, error o reintentar.
• Pasa el cursor sobre cualquier nodo para obtener una vista previa: marcas de tiempo de inicio y fin, estado de ejecución, fragmentos de entrada y salida.
• Selecciona un nodo para ver los detalles, incluyendo: cargas útiles JSON completas, registros y errores, métricas de runtime (uso de tokens, latencia).

Gestión del acceso a datos de seguimiento

Esta sección describe cómo los administradores pueden configurar el acceso a los datos de seguimiento utilizando el modelo de control de acceso basado en roles.

Para ver los registros de seguimiento necesitas los siguientes permisos:

• Logs.View
• Jobs.View

Para obtener más información sobre los permisos de los roles predeterminados, consulta Roles predeterminados.

La siguiente matriz explica los resultados de visibilidad en función de las combinaciones de permisos. Estas combinaciones definen qué detalles de seguimiento puedes ver dependiendo de tus permisos basados en rol.

Logs.View	Jobs.View	Acceder al resultado
Habilitar	Habilitar	Todos los atributos
Habilitar	Deshabilitar	Todos los atributos
Deshabilitar	Habilitar	Atributos parciales (por ejemplo, nombre, tipo).
Deshabilitar	Deshabilitar	Sin acceso

Cuando no tienes los permisos necesarios para ver los datos de seguimiento, verás un mensaje que explica si el acceso está total o parcialmente limitado y ofrece orientación para solicitar el permiso necesario.

Feedback on agent runs (Preview)

Feedback is a critical mechanism for interpreting and improving agent runtimes. It enables you to review behavior, diagnose issues, and document meaningful patterns in how an agent makes decisions.

Beyond debugging, feedback acts as the core input to feedback-based episodic memory, allowing the agent to refine its decision policy gradually—without requiring full prompt rewrites for every adjustment.

The relationship between feedback and memory

While feedback acts as an annotation tool, its most powerful application is influencing episodic memory.

Providing feedback on a trace highlights behaviors the agent should replicate or avoid in future runs.

• Evolution over repetition: Unlike static resolutions, feedback-based memory allows the agent's behavior to improve over time. The agent learns to recognize patterns flagged as correct or incorrect.
• Targeted improvement: This approach is most valuable in flows where the agent is frequently "almost right" or where the decision policy is still developing.
• Selective memory: Not all feedback automatically becomes memory. You must actively determine which annotations represent high-value learning opportunities, to prevent low-quality or inconsistent feedback from degrading performance.

Where to apply feedback

You can provide feedback on any span within an agent trace. This flexibility allows you to annotate specific tool calls, guardrail checks, or LLM outputs when reviewing or diagnosing behavior.

Only feedback applied to the agent run span is eligible for episodic memory. While you may annotate any part of the trace for analysis, only feedback attached directly to the agent run span will be stored and retrieved as memory in future runs.

When to apply feedback

While providing feedback on all traces would maximize iterative learning, in practice you should concentrate on traces that offer the highest value for optimization.

Focus on the following scenarios:

• Critical scenarios: Traces involving high-stakes decisions or high-impact errors.
• Recurring patterns: Areas where the agent consistently struggles or exhibits repetitive faults.
• Difficult decisions: Instances where the agent faced a complex choice.
• Negative sentiment: Runs that resulted in a poor user experience.
• Model behavior: Examples that clearly illustrate a specific behavior you want the agent to strictly copy or strictly avoid.

Applying feedback is crucial for continuous improvement. It allows you to encode better behaviors incrementally, making agent runs more reliable and consistent.

• Prioritize traces: Focus on traces from critical scenarios, high-impact errors, or recurring patterns where the agent struggles.
• High-value scenarios: Prioritize runs that represent difficult decisions for the agent, show negative user sentiment, or clearly illustrate a behavior you want the agent to copy or avoid.
• Focus areas: Clearly identify what you are providing feedback on:
  • Output: Did the final result meet expectations?
  • Plan execution (trajectory): Did the agent perform the task steps in the expected order?
  • Comments: Use comments to enrich the feedback and inform memory retrieval.