Glosario
78 términos de «Observabilidad y depuración: ver cada paso que da tu agente». Pasa el cursor sobre la primera aparición en la lección para ver la definición.
| Término | Definición | Fuente |
|---|---|---|
| no determinista | Propiedad de un sistema donde entradas idénticas pueden producir respuestas distintas; los agentes son sistemas de este tipo, y eso rompe la intuición tradicional de depuración de «reprodúcelo y pon un punto de interrupción». | Writing effective tools for agents — with agents — Anthropic Engineering |
| divergencia de trayectoria | Cuando un paso falla y hace que el agente explore una trayectoria completamente distinta, con todos los turnos siguientes creciendo sobre la rama equivocada, llevando a resultados impredecibles. | How we built our multi-agent research system — Anthropic Engineering |
| acumulación entre turnos | Los agentes tienen estado y los errores se acumulan; pueden ejecutarse durante períodos largos manteniendo estado a lo largo de muchas llamadas a herramientas, así que los errores se van sumando turno a turno. | How we built our multi-agent research system — Anthropic Engineering |
| comportamiento emergente | Comportamientos de los sistemas multiagente que surgen sin haber sido programados específicamente — por ejemplo, cambios pequeños en el agente líder que cambian de forma impredecible el comportamiento de los subagentes. | How we built our multi-agent research system — Anthropic Engineering |
| vía de evaluación | La calificación del estado final, los validadores y los conjuntos de evaluación que construiste en el curso anterior — responde solo «¿se rompió?», no «por qué». | How we built our multi-agent research system — Anthropic Engineering |
| pensar como tus agentes | Construir una simulación usando exactamente los mismos prompts y herramientas de tu sistema, y después observar a los agentes trabajar paso a paso. | How we built our multi-agent research system — Anthropic Engineering |
| capas de abstracción | Las capas intermedias que agregan los frameworks para simplificar el llamado a los LLM, la definición de herramientas y el encadenado de llamadas — ocultan los prompts y las respuestas subyacentes. | Building Effective AI Agents — Anthropic Engineering |
| entorno aislado | Entorno separado donde los agentes que pueden tomar acciones pasan por pruebas extensivas, usado junto con los guardrails apropiados. | Building Effective AI Agents — Anthropic Engineering |
| frontera de herramienta | La superficie de contrato entre los sistemas deterministas y los agentes no deterministas; la única posición que deja rastro en los registros. | Building Effective AI Agents — Anthropic Engineering |
| ground truth | La retroalimentación real que el agente obtiene del entorno en cada paso durante la ejecución, como los resultados de llamadas a herramientas y de ejecución de código. | Building Effective AI Agents — Anthropic Engineering |
| transcripción cruda | Por cada llamada a herramienta de una ejecución, el nombre de la herramienta y los parámetros completos; por cada respuesta de herramienta, el valor de retorno completo o el error — evidencia de primera mano. | Writing effective tools for agents — with agents — Anthropic Engineering |
| autorreporte | Lo que el agente escribe sobre sí mismo: resúmenes de cierre, tramos de razonamiento, autoevaluaciones después de ejecutar una herramienta — material secundario. | Writing effective tools for agents — with agents — Anthropic Engineering |
| cadena de pensamiento (CoT) | El razonamiento que el modelo escribe antes de dar una respuesta, abreviado CoT. | Writing effective tools for agents — with agents — Anthropic Engineering |
| las cuatro preguntas (para leer transcripciones) | Lista de verificación para leer transcripciones: llamó a la herramienta equivocada, llamó a la correcta con parámetros equivocados, llamó a muy pocas herramientas, procesó mal la respuesta de la herramienta. | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_use | Bloque de contenido donde el modelo nombra qué herramienta llamar; contiene el nombre de la herramienta y un objeto de parámetros completo que el modelo generó. | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_result | El bloque que el arnés devuelve después de ejecutar realmente la herramienta — si tuvo éxito, el valor de retorno completo; si falló, el contenido del error más un marcador de error. | Writing effective tools for agents — with agents — Anthropic Engineering |
| is_error | Marcador de error sobre los resultados de herramienta, usado para distinguir «la herramienta devolvió contenido» de «la herramienta lanzó un error». | Writing effective tools for agents — with agents — Anthropic Engineering |
| granjas de contenido | Fuentes optimizadas para SEO y bien rankeadas pero de poca autoridad; las pruebas manuales encontraron que los agentes tempranos las preferían de forma consistente por encima de PDF académicos y blogs personales. | How we built our multi-agent research system — Anthropic Engineering |
| transcripción de sesión | Los mensajes de la conversación persistidos en disco, como los registros de sesión JSONL que Claude Code escribe a disco. | Monitoring — Claude Code Official Documentation |
| logs estructurados | Convertir cada paso en registros JSON con campos, para que la evidencia no solo la puedan leer humanos sino que también se pueda filtrar, agregar y analizar por distribución. | Writing effective tools for agents — with agents — Anthropic Engineering |
| logs en prosa | Escritura de logs que codifica la estructura dentro del lenguaje natural; se lee bien pero solo lo pueden decodificar humanos. | Writing effective tools for agents — with agents — Anthropic Engineering |
| JSON Lines | Un archivo donde cada línea es un objeto JSON completo, sin comas entre líneas y sin arreglo envolvente — comúnmente escrito JSONL. | Writing effective tools for agents — with agents — Anthropic Engineering |
| session_id | Identificador de una sesión de conversación, constante entre múltiples turnos, usado para responder «cuánto costó esta sesión en total, si cambió de modo de permisos». | Monitoring — Claude Code Official Documentation |
| prompt_id | Identificador de un prompt del usuario; todas las solicitudes al modelo y llamadas a herramientas que dispara comparten este valor. | Monitoring — Claude Code Official Documentation |
| ID de correlación | Un número de ID que se le da a «un evento disparador», y cada evento que ese disparador engendra lo copia — no hace falta infraestructura de ningún tipo, es apenas un campo. | Monitoring — Claude Code Official Documentation |
| duration_ms | Milisegundos que tomó un paso, usados para encontrar cuellos de botella de rendimiento y también para revisar «¿está trabado?». | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_input | Los parámetros enviados a la herramienta, provistos directamente en los payloads de `PostToolUse` como una mitad del registro completo de la llamada. | Hooks reference — Claude Code Official Documentation |
| tool_response | El resultado que devolvió la herramienta, parte del registro completo de ida y vuelta que `tool_input` y `tool_response` forman juntos en un solo disparo. | Hooks reference — Claude Code Official Documentation |
| error (campo del registro) | El campo `error` de los registros, presente solo cuando falla; el primer campo por el que filtrar al localizar. | Writing effective tools for agents — with agents — Anthropic Engineering |
| métricas | Un conjunto de números: tiempo de ejecución de llamadas a herramientas individuales y de tareas completas, conteo total de llamadas a herramientas, consumo total de tokens, errores de herramienta. | Writing effective tools for agents — with agents — Anthropic Engineering |
| llamadas redundantes | Muchas llamadas repetidas a herramientas, que suelen sugerir que hay que ajustar los parámetros de paginación o de límite de tokens. | Writing effective tools for agents — with agents — Anthropic Engineering |
| errores de parámetro inválido | Muchos errores por parámetros inválidos, que apuntan a que a las descripciones de herramientas les falta claridad o mejores ejemplos. | Writing effective tools for agents — with agents — Anthropic Engineering |
| tasa de error | Métrica de proporción, conteo de errores dividido por conteo de llamadas, usada en lugar de números absolutos para ver la salud. | Writing effective tools for agents — with agents — Anthropic Engineering |
| señal terminal | El evento de error que se emite solo después de que los reintentos internos se rinden por completo, y que representa «esta solicitud falló en última instancia». | Monitoring — Claude Code Official Documentation |
| estancamiento sospechoso | Estado donde el último registro de un prompt tiene error y no le siguen registros posteriores — frente a «se recuperó del error». | Monitoring — Claude Code Official Documentation |
| umbral | La línea que juzga «cuánto cuenta como anormal»; no hay números en los materiales de primera mano — ni presupuesto de error ni SLO. | Monitoring — Claude Code Official Documentation |
| SIEM | Sistema de Security Information and Event Management; la detección de anomalías, el cálculo de líneas base, la correlación entre sesiones y las alertas son todas responsabilidad de su lado. | Monitoring — Claude Code Official Documentation |
| rastro de auditoría | Con los atributos de identidad del usuario final adjuntos, las decisiones de herramientas, los resultados de herramientas, las conexiones MCP y los cambios de modo de permisos forman un registro por usuario. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| span | El registro de un trabajo con un principio y un final: tiene nombre, hora de inicio, hora de fin, varios atributos, y puede identificar a su span padre. | Monitoring — Claude Code Official Documentation |
| traza | Todo un árbol de spans conectados por relaciones padre-hijo; todo lo que ocurrió en una solicitud completa de principio a fin, leído como árbol. | Monitoring — Claude Code Official Documentation |
| claude_code.interaction | El nombre del span raíz que corresponde a cada prompt del usuario en el trazado de primera mano. | Monitoring — Claude Code Official Documentation |
| subagente | Agente de nivel inferior despachado a través de la herramienta Agent; sus solicitudes al modelo y sus spans de herramienta se anidan bajo el span de herramienta del agente padre. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| exportador | El código dentro del proceso encargado de empaquetar los spans y mandarlos afuera. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| colector | La estación de relevo o servicio backend que recibe los spans; el exportador le manda los datos y tú ves el árbol en su panel. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| fallo silencioso de exportación | El comportamiento por defecto donde, si el endpoint es inalcanzable o el backend rechaza los datos, el agente sigue ejecutándose con normalidad, la telemetría se descarta y no aparece ningún error en tu aplicación. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| exportación por lotes | El mecanismo de acumular la telemetría en lotes y mandarla a intervalos — por defecto las métricas cada 60 segundos, las trazas y los logs cada 5 segundos. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| service.name | Atributo de recurso que identifica de qué servicio vinieron los datos; la CLI por defecto lo reporta como `claude-code`. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| claude_code.session.count | Métrica de conteo que se emite apenas arranca una sesión; la sonda más barata para verificar que la configuración de exportación funcionó. | Monitoring — Claude Code Official Documentation |
| TRACEPARENT | Variable de entorno en formato estándar que lleva el id de traza y el id del span actual; los subprocesos de Bash y PowerShell la heredan automáticamente. | Monitoring — Claude Code Official Documentation |
| contexto de traza W3C | Cadena en formato estándar que contiene el id de traza y el id del span actual; quien la reciba sabe dónde engancharse. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| CLAUDE_CODE_ENHANCED_TELEMETRY_BETA | El interruptor que, al activarse, hace que cada paso del bucle del agente se vuelva un span inspeccionable en tu backend de trazado. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| hooks | Comandos de shell, endpoints HTTP o prompts de LLM definidos por el usuario que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code. | Hooks reference — Claude Code Official Documentation |
| matcher | La regla de coincidencia que determina cuándo se dispara un hook; omitido o puesto en comodín significa un-hook-registra-todo. | Hooks reference — Claude Code Official Documentation |
| PreToolUse | Evento que se ejecuta después de que el modelo crea los parámetros de la herramienta y antes de procesar la llamada. | Hooks reference — Claude Code Official Documentation |
| PostToolUse | Evento que se dispara tras la ejecución exitosa de una herramienta; la entrada lleva tanto `tool_input` como `tool_response`. | Hooks reference — Claude Code Official Documentation |
| SessionStart | Evento de la cadencia una-vez-por-sesión; se dispara cuando se abre una sesión nueva y también cuando se reanuda una existente. | Hooks reference — Claude Code Official Documentation |
| Stop | Evento de fin de turno en la cadencia una-vez-por-turno; emparejado con `UserPromptSubmit` permite calcular la duración de un turno. | Hooks reference — Claude Code Official Documentation |
| payload | El contexto JSON que se le entrega a tu manejador cuando un evento se dispara y el matcher coincide. | Hooks reference — Claude Code Official Documentation |
| OTEL_* | Conjunto de variables de entorno relacionadas con la exportación de telemetría; Claude Code las elimina de cada subproceso que lanza, incluidos los hooks. | Hooks reference — Claude Code Official Documentation |
| log de depuración | Archivo de log que registra qué hooks coincidieron, sus códigos de salida y el stdout y stderr completos. | Hooks reference — Claude Code Official Documentation |
| flujo de cinco pasos | La disposición de depuración que armó este curso: acotar por prompt id, encontrar la primera divergencia, reproducir y observar, machacar repetidamente el mismo componente, recuperar desde el punto de fallo después de arreglar. | How we built our multi-agent research system — Anthropic Engineering |
| acotar | Paso uno: filtrar por prompt id para encoger el alcance de «el agente se rompió» a «estos diez y pico de eventos bajo este id». | Monitoring — Claude Code Official Documentation |
| primera divergencia | El paso donde el comportamiento empieza a desviarse de lo esperado; los absurdos del final son en su mayoría ruido de río abajo. | How we built our multi-agent research system — Anthropic Engineering |
| contagio | Los pasos posteriores al punto de divergencia que se ven igual de absurdos pero apenas siguen empujando hacia adelante sobre la premisa equivocada. | How we built our multi-agent research system — Anthropic Engineering |
| reproducir y observar | Construir simulaciones usando prompts y herramientas idénticas, y mirar paso a paso para forzar de inmediato la salida de los modos de fallo. | How we built our multi-agent research system — Anthropic Engineering |
| cliente stub | Un reemplazo que no manda solicitudes de red y devuelve en orden objetos de respuesta preescritos de un arreglo fijo, volviendo reproducible el lado del modelo. | How we built our multi-agent research system — Anthropic Engineering |
| cola de respuestas | El arreglo del que el cliente stub va sacando en orden, con cada elemento llevando su `stop_reason`, sus bloques de contenido y su `usage` completos. | How we built our multi-agent research system — Anthropic Engineering |
| agente de prueba de herramientas | Agente al que le das una herramienta defectuosa, intenta usarla repetidamente y después reescribe la descripción de la herramienta para evitar los fallos; al probarla docenas de veces encuentra matices clave y bugs. | How we built our multi-agent research system — Anthropic Engineering |
| trace_id | Un id por ejecución, que hilvana los registros dispersos del mismo flujo de vuelta a la misma ejecución. | Monitoring — Claude Code Official Documentation |
| span_id | El id propio de este registro; otros registros lo apuntan para declarar «estoy debajo tuyo». | Monitoring — Claude Code Official Documentation |
| parent_id | Campo que apunta al id del registro padre; los árboles se reconstruyen con él desde el JSONL en disco. | Monitoring — Claude Code Official Documentation |
| MAX_ROUNDS | Compuerta dura sobre la cantidad de iteraciones del bucle; superarla lanza un error, registra una interrupción y sale con código distinto de cero. | Building Effective AI Agents — Anthropic Engineering |
| stop_reason | El campo de las respuestas del modelo que hace que el bucle del arnés continúe o termine. | Building Effective AI Agents — Anthropic Engineering |
| HEAD_CHARS | La línea que define cuántos caracteres como máximo conserva cada fragmento de contenido en los logs; ponlo en 0 y ni una palabra toca el disco. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| shape | Campo de los registros que describe el tipo y la escala de un valor: si es string u objeto, qué tan largo, qué claves. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| resumen de métricas | Una línea que saca rondas totales, cantidad de llamadas a herramientas, tokens, cantidad de errores y duración total — una de las tres piezas del kit de observabilidad. | Writing effective tools for agents — with agents — Anthropic Engineering |
| compare-runs.mjs | Script de comparación que lee los logs de dos ejecuciones, los compara lado a lado por tipo de registro y nombre de herramienta, y sale con código distinto de cero si hay errores. | Writing effective tools for agents — with agents — Anthropic Engineering |
| compuerta | Un juicio cableado a códigos de salida; el distinto de cero lo puede atrapar CI, cron o cualquier lugar donde «distinto de cero dispara alerta». | Writing effective tools for agents — with agents — Anthropic Engineering |