Vai al contenuto principale
Quando un agente di programmazione si comporta male, la sua interfaccia raramente ti dice perché. Una chiamata a uno strumento non fa nulla senza avvisare, una richiesta fallisce con “provider error”, il modello ignora il tuo prompt di sistema, oppure una breve sessione costa molto più del previsto. Nella maggior parte dei casi la risposta si trova nel traffico HTTP tra l’agente e Venice, che normalmente non puoi vedere. In questa guida eseguiremo un piccolo proxy sulla tua macchina, posizionato tra l’agente e l’API di Venice. L’agente parla con il proxy, il proxy inoltra tutto a Venice senza modifiche, e ogni richiesta e risposta viene scritta in un file di log locale che puoi interrogare con jq.

Vedi la richiesta reale

ID del modello, messaggi, strumenti e parametri esattamente come li ha inviati l’agente

Streaming intatto

I chunk vengono inoltrati appena arrivano, quindi l’agente si comporta normalmente

Nessuna dipendenza

Un solo file, Node.js 18 o successivo, niente da installare

Come funziona

Il proxy inoltra il percorso completo e il tuo header Authorization, quindi la tua chiave API resta nella configurazione dell’agente e ogni endpoint di Venice funziona attraverso il proxy: /chat/completions, /responses, /models, /embeddings e tutti gli altri. L’unica modifica da fare all’agente è l’URL di base. Per ogni richiesta, il proxy registra:
  • Il metodo, il percorso e il corpo della richiesta, con la tua chiave API mascherata tranne gli ultimi quattro caratteri
  • Lo stato e il corpo della risposta. Le risposte in streaming vengono salvate come elenco di chunk analizzati.
  • L’utilizzo dei token, dall’oggetto usage restituito da Venice
  • La durata totale e il tempo al primo byte
  • Gli header di risposta x-venice-* e x-ratelimit-*, come il saldo residuo, lo stato del rate limit e gli avvisi di deprecazione dei modelli
Questo è uno strumento di debug per la tua macchina. Ascolta solo su 127.0.0.1, non ha un’autenticazione propria e scrive prompt e codice su disco in chiaro. Non distribuirlo come gateway condiviso. Se te ne serve uno, consulta Costruire un gateway LLM in Rust.

Prerequisiti


Configurazione

1

Crea il proxy

Salva questo file come venice-debug-proxy.mjs in una directory temporanea:
venice-debug-proxy.mjs
Ci sono alcune cose che vale la pena sottolineare:
  • Lo streaming funziona normalmente. Ogni chunk di Venice viene scritto verso l’agente appena arriva, e una copia viene conservata per il log. L’agente vede lo stesso flusso token per token che riceverebbe direttamente da Venice.
  • La compressione è gestita per te. Il fetch di Node decomprime la risposta, quindi il proxy rimuove content-encoding prima di inoltrare gli header. Altrimenti l’agente proverebbe a decomprimere testo in chiaro e fallirebbe.
  • Le disconnessioni vengono propagate. Se annulli un turno nell’agente, il proxy interrompe anche la richiesta upstream, così Venice non continua a generare token che nessuno legge.
2

Avvialo

Dovresti vedere:
Imposta PORT o LOG_FILE nell’ambiente per cambiare uno dei due valori predefiniti.
3

Verificalo con curl

In un secondo terminale, invia una richiesta tramite il proxy:
Il proxy stampa una riga per ogni richiesta:
Sono molti token di prompt per “Say hello”. La maggior parte proviene dal prompt di sistema predefinito di Venice, che viene aggiunto alle richieste di chat a meno che tu non imposti venice_parameters.include_venice_system_prompt su false. È proprio questo il tipo di cosa che il proxy rende visibile.
4

Punta l'agente al proxy

Nelle impostazioni di Venice del tuo agente, sostituisci https://api.venice.ai con http://127.0.0.1:8787 e lascia invariato il resto dell’URL. Il proxy inoltra il percorso completo, quindi qualunque valore indicato dalla guida dell’agente continua a funzionare.Il provider Venice integrato in OpenCode e il provider Venice nativo di Kilo Code non espongono un URL di base, quindi durante il debug passa al provider manuale o compatibile con OpenAI.In OpenCode, assegna al provider di debug un ID proprio, come venice-debug, ed eseguilo con -m venice-debug/<model-id>. Se hai salvato una chiave con /connect, OpenCode invia quella chiave salvata per l’ID provider venice anche quando la tua configurazione imposta apiKey.Usa 127.0.0.1 invece di localhost. Su alcuni sistemi localhost si risolve nell’indirizzo IPv6 ::1, su cui il proxy non è in ascolto.
Questo non funziona con Cursor. Cursor invia le richieste dei modelli personalizzati dai propri server, che non possono raggiungere un proxy sulla tua macchina.
5

Riproduci il problema

Usa l’agente come fai di solito finché il problema non si ripresenta, poi controlla l’output del proxy nel terminale e il file di log.

Leggere i log

Ogni riga di venice-debug.jsonl è un oggetto JSON completo, quindi jq può analizzarla come preferisci. Mostra la richiesta e la risposta più recenti:
Mostra solo le richieste fallite o interrotte:
Verifica quale modello, quali parametri e quali strumenti ha effettivamente inviato l’agente:
Ricostruisci il testo delle chat completion in streaming:
Totale dei token per modello nella sessione:
Trova le richieste più lente:

Cosa cercare


Senza scrivere codice

Se preferisci esplorare il traffico con un browser, mitmproxy può funzionare come reverse proxy davanti a Venice:
Punta l’agente a http://127.0.0.1:8787/api/v1 nello stesso modo, poi ispeziona ogni richiesta nell’interfaccia di mitmweb. Il proxy Node è più facile da automatizzare con script e conserva un log che puoi cercare con grep in seguito. mitmproxy è più adatto per esplorare una sessione in modo interattivo.

Mantieni privati i log

Venice non memorizza i tuoi prompt né le tue risposte per l’inferenza normale (vedi Privacy), ma questo file di log sì. Contiene il tuo codice, i prompt, l’output degli strumenti e le risposte del modello in chiaro.
  • Esegui il proxy fuori dal tuo progetto, oppure aggiungi venice-debug.jsonl a .gitignore.
  • Elimina il log quando hai finito il debug.
  • Non incollare voci di log complete in issue pubbliche. Estrai invece status, error e la parte rilevante di response.
Per i modelli E2EE, l’agente cifra il contenuto dei messaggi prima che lasci la tua macchina, quindi il log mostrerà payload cifrati invece di testo leggibile.

Per concludere

Quando hai finito, arresta il proxy con Ctrl+C e reimposta l’URL di base dell’agente su https://api.venice.ai/api/v1. Se te ne dimentichi, l’agente fallirà con un errore di connessione non appena il proxy non sarà in esecuzione, il che almeno è facile da notare. Grazie per aver letto! Speriamo che la prossima volta che un agente dice “something went wrong”, tu possa vedere esattamente cosa è andato storto.