Saltar al contenido principal
Cuando un agente de programación se comporta mal, su interfaz rara vez te dice por qué. Una llamada a herramienta no hace nada sin avisar, una petición falla con “provider error”, el modelo ignora tu prompt de sistema o una sesión corta cuesta mucho más de lo que esperabas. La mayoría de las veces, la respuesta está en el tráfico HTTP entre el agente y Venice, que normalmente no puedes ver. En esta guía, ejecutaremos un pequeño proxy en tu propio equipo que se sitúa entre el agente y la API de Venice. El agente habla con el proxy, el proxy reenvía todo a Venice sin cambios, y cada petición y respuesta se escribe en un archivo de registro local que puedes consultar con jq.

Ve la petición real

ID del modelo, mensajes, herramientas y parámetros exactamente como los envió el agente

Streaming intacto

Los fragmentos se reenvían a medida que llegan, así que el agente se comporta con normalidad

Sin dependencias

Un solo archivo, Node.js 18 o posterior, nada que instalar

Cómo funciona

El proxy reenvía la ruta completa y tu encabezado Authorization, así que tu clave de API se queda en la configuración del agente y todos los endpoints de Venice funcionan a través de él: /chat/completions, /responses, /models, /embeddings y el resto. El único cambio que haces en el agente es la URL base. Para cada petición, el proxy registra:
  • El método, la ruta y el cuerpo de la petición, con tu clave de API enmascarada salvo sus últimos cuatro caracteres
  • El estado y el cuerpo de la respuesta. Las respuestas en streaming se guardan como una lista de fragmentos analizados.
  • El uso de tokens, a partir del objeto usage que devuelve Venice
  • La duración total y el tiempo hasta el primer byte
  • Los encabezados de respuesta x-venice-* y x-ratelimit-*, como el saldo restante, el estado del límite de tasa y los avisos de retirada de modelos
Esta es una herramienta de depuración para tu propio equipo. Solo escucha en 127.0.0.1, no tiene autenticación propia y escribe prompts y código en disco en texto plano. No la despliegues como gateway compartido. Si necesitas uno, consulta Construir un LLM Gateway en Rust.

Requisitos previos


Configuración

1

Crea el proxy

Guarda esto como venice-debug-proxy.mjs en un directorio temporal:
venice-debug-proxy.mjs
Hay algunas cosas que vale la pena destacar:
  • El streaming funciona con normalidad. Cada fragmento de Venice se escribe hacia el agente en cuanto llega, y se guarda una copia para el registro. El agente ve el mismo flujo token a token que recibiría directamente de Venice.
  • La compresión se gestiona por ti. El fetch de Node descomprime la respuesta, así que el proxy elimina content-encoding antes de reenviar los encabezados. De lo contrario, el agente intentaría descomprimir texto plano y fallaría.
  • Las desconexiones se propagan. Si cancelas un turno en el agente, el proxy también aborta la petición upstream, para que Venice no siga generando tokens que nadie lee.
2

Inícialo

Deberías ver:
Define PORT o LOG_FILE en el entorno para cambiar cualquiera de los dos valores predeterminados.
3

Compruébalo con curl

En una segunda terminal, envía una petición a través del proxy:
El proxy imprime una línea por petición:
Son muchos tokens de prompt para “Say hello”. La mayoría son el prompt de sistema predeterminado de Venice, que se añade a las peticiones de chat salvo que establezcas venice_parameters.include_venice_system_prompt en false. Justo este tipo de cosas es lo que el proxy hace visible.
4

Apunta tu agente al proxy

En la configuración de Venice de tu agente, sustituye https://api.venice.ai por http://127.0.0.1:8787 y deja el resto de la URL como está. El proxy reenvía la ruta completa, así que lo que te indique la guía del agente sigue funcionando.El proveedor de Venice incluido en OpenCode y el proveedor nativo de Venice de Kilo Code no exponen una URL base, así que cambia al proveedor manual o compatible con OpenAI mientras depuras.En OpenCode, dale al proveedor de depuración su propio ID, como venice-debug, y ejecútalo con -m venice-debug/<model-id>. Si guardaste una clave con /connect, OpenCode envía esa clave almacenada para el ID de proveedor venice aunque tu configuración defina apiKey.Usa 127.0.0.1 en lugar de localhost. En algunos sistemas, localhost se resuelve a la dirección IPv6 ::1, en la que el proxy no escucha.
Esto no funciona con Cursor. Cursor envía las peticiones de modelos personalizados desde sus propios servidores, que no pueden llegar a un proxy en tu equipo.
5

Reproduce el problema

Usa el agente como siempre hasta que el problema vuelva a ocurrir y, después, revisa la salida del proxy en la terminal y el archivo de registro.

Leer los registros

Cada línea de venice-debug.jsonl es un objeto JSON completo, así que jq puede filtrarlo como necesites. Muestra la petición y la respuesta más recientes:
Muestra solo las peticiones fallidas o interrumpidas:
Comprueba qué modelo, parámetros y herramientas envió realmente el agente:
Reconstruye el texto de las chat completions en streaming:
Total de tokens por modelo en la sesión:
Encuentra las peticiones más lentas:

Qué buscar


Sin escribir código

Si prefieres revisar el tráfico haciendo clic en un navegador, mitmproxy puede funcionar como proxy inverso delante de Venice:
Apunta el agente a http://127.0.0.1:8787/api/v1 de la misma forma y luego inspecciona cada petición en la interfaz de mitmweb. El proxy de Node es más fácil de automatizar y guarda un registro que puedes consultar después con grep. mitmproxy es mejor para explorar una sesión de forma interactiva.

Mantén los registros privados

Venice no almacena tus prompts ni tus respuestas en la inferencia normal (consulta Privacidad), pero este archivo de registro sí. Contiene tu código, prompts, salida de herramientas y respuestas del modelo en texto plano.
  • Ejecuta el proxy fuera de tu proyecto o añade venice-debug.jsonl a .gitignore.
  • Borra el registro cuando termines de depurar.
  • No pegues entradas completas del registro en issues públicos. Extrae en su lugar status, error y la parte relevante de response.
Para los modelos E2EE, el agente cifra el contenido de los mensajes antes de que salga de tu equipo, así que el registro mostrará cargas cifradas en lugar de texto legible.

Para terminar

Cuando termines, detén el proxy con Ctrl+C y vuelve a poner la URL base del agente en https://api.venice.ai/api/v1. Si se te olvida, el agente fallará con un error de conexión en cuanto el proxy no esté en ejecución, lo que al menos es fácil de detectar. ¡Gracias por leer! Ojalá la próxima vez que un agente diga “something went wrong”, puedas ver exactamente qué salió mal.