La Línea de Registro que Vercel Connect No Escribirá Para Ti
Envías un agente que habla con Slack, luego Salesforce, luego una API personalizada. A las 14:31, un token se revoca a mitad de turno. A las 14:32, la tercera llamada de herramienta de tu agente falla. Vercel Connect te muestra el evento de revocación de token. No te mostrará por qué tu agente se rompió.
La nueva observabilidad de Vercel Connect es un progreso real. Obtienes eventos de token emitido, actualizado y revocado. Obtienes eventos de tiempo de ejecución: conector invocado, acierto/fallo de caché, latencia, estado. Obtienes IDs de correlación con alcance a cada llamada de conector. Pero la vista del mundo de un conector se detiene en el límite del conector. No ve el bucle de razonamiento del agente, la llamada de herramienta que desencadenó la invocación, o la decisión del siguiente turno que se torció porque hubo un éxito parcial silencioso dos pasos atrás.
La costura invisible es donde se pierde el tiempo y se esconden las causas raíz. Tu agente tomó una decisión en el turno 4 para llamar a la Herramienta X. El conector actualizó un token, golpeó un límite de velocidad, y tuvo éxito en el reintento. El agente recuperó una carga útil e la interpretó como "operación completada". Pero la interpretación era obsoleta. El siguiente paso de razonamiento envió al agente por una madriguera de conejo. Los registros del conector muestran el reintento. No muestran la interpretación defectuosa que conectó el fallo silencioso al error posterior.
Con Alcance de Conector vs Con Alcance de Agente: El Problema de Cardinalidad
Los IDs de correlación de Connect son por invocación de conector. La correlación de tu agente debe ser por ejecución de agente. Un turno de agente puede desencadenar 4–8 llamadas de conector más 2–3 llamadas de LLM. Multiplica eso por 50 turnos y estás persiguiendo IDs en tres sistemas por incidente. En la práctica, pasas 15–40 minutos por incidente persiguiendo IDs en tres sistemas.
La causa raíz es que los registros del conector y los registros del agente registran diferentes niveles de detalle. Un registro de conector responde: "¿Se actualizó correctamente el token?" Un registro de agente necesita responder: "¿Por qué el agente decidió llamar a esta herramienta?" y "¿Qué hizo con la respuesta?" Estas preguntas operan en diferentes niveles. Cuando intentas unirlas, tus consultas se rompen bajo reintentos y llamadas paralelas.
La propagación de trace_id de OpenTelemetry se rompe en el límite del conector. Vercel posee el span del conector, y tu bucle de agente no lo hereda, tiene que inyectarlo. Puedes envolverlo en un encabezado personalizado, pero ahora estás gestionando dos espacios de nombres de ID de traza y un puente manual entre ellos. Aquí es donde la mayoría de los equipos comienzan a sangrar. Nos hemos equivocado antes: construimos un sistema de enrutamiento que emitía IDs de traza a un lugar, agentes a otro, y dejó a un ingeniero junior a medianoche intentando coserlos juntos a mano.
La solución requiere un contrato de ID de correlación que se extienda desde el punto de entrada de la API a través de cada llamada de herramienta, incluyendo en Vercel Connect. Lee más sobre registros de caché-razón como patrón de observabilidad para ver cómo la granularidad agrava el problema en las capas de recuperación también.
El Contrato de ID de Correlación que Ahora Pedimos a Cada Agente que Honre
Comienza con un único agent_run_id generado en el borde de entrada, tu ruta de API, tu consumidor de cola, donde sea que comience el bucle de turno del agente. Nunca lo regeneres aguas abajo. Emparéjalo con turn_id y tool_call_id como una tupla de 3. Pasa los tres en cada encabezado saliente: x-agent-run-id, x-agent-turn-id, x-tool-call-id.
Cuando llames a Vercel Connect, inyecta x-agent-run-id para que los eventos de tiempo de ejecución del conector hereden el contexto de traza de tu agente. Vercel aún no lo usa, pero fluirá a través de sus registros y tu propio flujo, y cuando exportes los eventos de tiempo de ejecución de Connect a tu backend de registro, ese ID ya está allí.
Tu esquema de registro estructurado debería verse así: {run_id, turn_id, tool, connector, status, latency_ms, tokens_in, tokens_out, cost_usd}. Registra los tokens que el LLM gastó planeando entre llamadas de herramienta junto con la llamada de herramienta en sí, no como un evento separado. Un turno de agente debería emitir una línea de registro de resumen que te permita ver todo el turno en 10 segundos. Costo de razón, costo de herramienta, resultado y clase de error en un lugar.
Almacena 30 días en caliente en Clickhouse o Axiom. Archiva el resto en S3. El volumen típico es 2–5KB por turno. A 50 turnos por ejecución de agente y 100 ejecuciones de agente por hora, estás mirando 10–25MB al día. Nada que rompa un presupuesto, pero suficiente para que quieras almacenamiento frío barato.
Ve cómo se aplica este patrón aguas arriba en tu capa de enrutamiento de tokens a escala en nuestro análisis de arquitectura de agente y el problema de enrutamiento de tokens.
Modos de Fallo que Solo Ves con Trazas con Alcance de Agente
Éxito parcial silencioso: un conector devuelve 200, el agente interpreta la carga útil como "operación completada", y la siguiente llamada de herramienta procede con datos obsoletos. Los registros del conector muestran el 200. Los registros del agente solo no mostrarán la interpretación errónea. Una traza de correlación los conecta.
Tormentas de reintento: el LLM ve una llamada de herramienta fallar (aunque el conector ya manejó el 429 y reintentó internamente) y replantea enviar otra solicitud al mismo conector de todas formas. La segunda llamada también golpea el límite de velocidad. Ahora tienes dos reintentos, dos actualizaciones de token, costo duplicado, y un turno de 30 segundos que debería haber sido de 5 segundos.
Carrera de actualización de token: Connect actualiza un token a mitad de turno. Tu agente ha almacenado en caché la respuesta anterior de una llamada anterior al mismo conector. El paso de razonamiento del siguiente turno usa credenciales obsoletas o un conjunto de permisos obsoleto y la operación falla dos turnos después. Los registros del conector muestran la actualización. Los registros del agente muestran el fallo. Una traza de correlación muestra que es el mismo incidente.
Explosiones de costo de bucles de razonamiento que nunca golpean un conector. El LLM gasta 40k tokens planeando porque tu indicación no le dio restricciones lo suficientemente claras. Los registros del conector no ven nada. Los registros del agente solo muestran el costo, pero no por qué. Necesitas ambos.
El tiempo de espera fantasma: tu tiempo de espera de Vercel Connect es de 30 segundos. Tu presupuesto de turno general del agente es de 90 segundos. Una llamada de herramienta golpea el tiempo de espera de 30 segundos, el agente ve el fallo, replantea, y hace otra llamada. La segunda llamada también agota el tiempo de espera. Ahora el agente ha quemado 60 segundos y tres llamadas de LLM en una única invocación de herramienta. Los registros del conector muestran dos tiempos de espera. Los registros del agente muestran un turno confundido. Una traza de correlación muestra que fue una cascada de tiempo de espera sistemática, no un accidente.
Para ejemplos de producción concretos, consulta el estudio de caso de asociación HP y OpenAI Frontier sobre observabilidad de agentes.
Qué Instrumentar Esta Semana
Emite agent_run_id en el borde de entrada y nunca lo regeneres aguas abajo. Pásalo a Connect a través de x-agent-run-id. Envuelve cada llamada de Connect en una función adaptadora ligera que inyecte los encabezados y refleje los eventos de tiempo de ejecución de Connect en tu propio flujo de registro para que tengas un esquema unificado para consultar.
Añade una única línea de registro de "resumen de turno de agente". Entradas, llamadas de herramienta, costo, resultado, clase de error. Si tu línea de resumen de turno es más larga que dos líneas de JSON, tienes demasiados campos.
Construye una consulta de panel: "Muéstrame todos los turnos donde cualquier llamada posterior falló, agrupados por herramienta." Ejecútala. Si los resultados son ruidosos, tienes un problema de confiabilidad de herramienta o una incomprensión sobre lo que se supone que debe devolver tu conector. De cualquier forma, esa es la prioridad.
Ejecuta un día de juego. Mata un token a mitad de turno. Mide cuánto tiempo tarda un encargado de turno en encontrar la causa raíz. Si la respuesta es "más de cinco minutos", añade x-agent-run-id a cada llamada de Connect esta semana y mídelo de nuevo. Si la respuesta es "mucho menos", has justificado el costo de la instrumentación.
El Movimiento de Cierre
Elige tu agente más ruidoso en producción. Añade encabezados agent_run_id, turn_id y tool_call_id a cada llamada de Vercel Connect. Emite una línea de registro de resumen de turno estructurado por turno de agente. Ejecuta un incidente de producción con estos datos disponibles. Mide tu MTTR. Si cae 10 minutos o más, has encontrado un patrón que vale la pena enviar al resto de tu flota. Si no se mueve, puedes tener un problema diferente, tal vez la observabilidad no es el cuello de botella, o tal vez los modos de fallo de tu agente no se muestren limpiamente en los registros en absoluto. De cualquier forma, lo sabrás. Cuando estés listo para escalar esto en tu pila de agentes, podemos ayudarte.