AI Agent Builder

Questa pagina è la guida canonica per costruire agenti LLM con l'AI Agent Builder di DevUtilities. Usa il workflow guidato sopra mentre leggi, oppure salta a un argomento sotto. Schemas, JSON MCP, prompt e conteggi token restano nel browser — nulla viene caricato per l'inferenza.

AI Agent Builder è un laboratorio lato client per assemblare config di agenti pronti per la produzione: tool JSON Schema per il function calling OpenAI, validazione mcpServers per Cursor e Claude Desktop, system prompts, budget token combinati e artefatti esportabili per il passaggio di consegne al team.

Cosa ottieni

• Quattro modalità di workflow: agente completo, solo function calling, setup MCP, risposta strutturata
• Template iniziali: Filesystem MCP, OpenAI function calling, classificatore strutturato
• Inferenza esempio-JSON → JSON Schema con additionalProperties: false strict opzionale
• Lint MCP locale con errori e avvisi per JSON-pointer
• Budget token combinato tra prompt, tools minificati e JSON MCP
• Export: OpenAI tools JSON, response_format, config MCP, riepilogo markdown, bundle completo

Usa questo builder quando

• Ti serve OpenAI tools JSON e non vuoi scrivere JSON Schema a mano
• Stai collegando server MCP di Cursor o Claude Desktop e vuoi il lint prima di incollare
• Devi dimostrare che prompt + tools di un agente entrano ancora in una finestra di contesto
• Vuoi una sessione persistita che concatena schema → MCP → prompt → export

Preferisci uno strumento standalone quando

• Ti serve solo un confronto encoding approfondito o il calcolo dei costi → LLM Token Counter
• Ti serve solo un lint MCP una tantum senza prompt → MCP Validator
• Ti serve solo l'inferenza di schema da un campione → Structured Output Generator

Scegli una modalità prima di definire i tools. Le modalità nascondono i passaggi irrilevanti così non combatti con pannelli vuoti.

Percorso iniziale per un agente completo. Le scorciatoie dei template saltano diversi di questi passaggi.

1. Scegli Agente completo (o carica il template OpenAI function calling).
2. In Definisci tools, aggiungi ogni tool con nome chiaro, descrizione e JSON di argomenti di esempio rappresentativo.
3. Rivedi il JSON Schema inferito — abilita la modalità strict per structured outputs / strict tool calling OpenAI.
4. Incolla o modifica il JSON mcpServers se l'agente girerà in Cursor o Claude Desktop; correggi ogni errore prima di continuare.
5. Scrivi system instructions che dicano al modello quando chiamare quale tool e cosa non inventare mai.
6. Apri Budget token, scegli cl100k_base o o200k_base e conferma che il totale combinato entri nel tuo modello.
7. Esporta OpenAI tools JSON per l'API, config MCP per il client desktop e un riepilogo markdown per il team.
8. Opzionalmente esporta il bundle JSON completo così un altro engineer può ricaricare lo stesso stato di sessione più tardi.

Problema: ti serve un agente di supporto clienti che consulti meteo e ordini via OpenAI function calling, ma il JSON Schema scritto a mano continua a fallire la validazione strict.

Come lo risolve questo strumento

1. Seleziona la modalità Function calling o carica il template OpenAI function calling (meteo + lookup ordini).
2. Modifica l'esempio JSON così che ogni campo necessario in produzione compaia almeno una volta — le chiavi mancanti non diventano proprietà required.
3. Abilita la modalità strict così ogni oggetto emette additionalProperties: false.
4. Stringi il system prompt: conferma gli ID ordine, non inventare mai risultati dei tools, tieni le risposte concise.
5. Controlla il budget token sotto o200k_base se fai deploy su GPT-4o.
6. Esporta OpenAI tools JSON e incollalo nel client Chat Completions o Responses API.

Risultato: un array tools strict pronto per l'API più un prompt allineato agli schema — senza un editor di schema separato.

Problema: Cursor o Claude Desktop rifiutano il tuo mcp.json, oppure il server filesystem parte con la directory sbagliata e vede troppo del disco.

Come lo risolve questo strumento

1. Scegli la modalità Setup MCP o carica il template Filesystem MCP.
2. Sostituisci /path/to/allowed/dir con un percorso assoluto all'unica directory che l'agente può toccare.
3. Esegui la validazione — correggi command/args mancanti, URL non validi e valori env non string.
4. Usa valori env placeholder (non segreti di produzione) mentre fai lint nel browser.
5. Esporta il JSON mcpServers validato nella config di Cursor o Claude Desktop.
6. Aggiungi system instructions che richiedano conferma prima di operazioni file distruttive.

Risultato: una config client MCP lintata e un prompt allineato alle capacità del server prima di riavviare l'app desktop.

Problema: ti serve che il modello restituisca sentiment, confidenza, argomenti e un breve riepilogo come JSON — le risposte in prosa rompono il parser downstream.

Come lo risolve questo strumento

1. Scegli la modalità Risposta strutturata o carica il template del classificatore strutturato.
2. Modifica l'esempio JSON perché corrisponda esattamente alla forma attesa dalla pipeline.
3. Abilita la modalità strict così le chiavi non dichiarate vengono rifiutate in validazione.
4. Scrivi un system prompt che vieti la prosa fuori dall'oggetto JSON.
5. Esporta response_format json_schema per gli structured outputs OpenAI.
6. Verifica che il budget token lasci ancora spazio al documento di input da classificare.

Risultato: un unico schema di output da inserire nelle API structured-output con istruzioni corrispondenti.

Problema: dopo aver aggiunto tre tools e una lunga config MCP, il prompt combinato dell'agente non entra più nel budget pratico di GPT-4o una volta inclusa la cronologia chat.

Come lo risolve questo strumento

1. Apri il passaggio Budget token e annota il totale combinato di prompt + tools minificati + JSON MCP.
2. Accorcia le descrizioni dei tools e rimuovi i campi di esempio inutilizzati che gonfiano gli schema required.
3. Sposta il testo di policy verboso fuori dal system prompt sempre attivo verso il retrieval on-demand.
4. Se ti serve solo matematica di encoding più profonda, copia il payload assemblato in LLM Token Counter.
5. Riesporta solo quando il budget mostra margine comodo per cronologia e completions.

Risultato: intercetti l'overflow nel builder — non dopo il primo errore 400 in produzione.

L'esempio JSON deve essere JSON strict. Solo le chiavi presenti nell'esempio diventano proprietà required. Oggetti e array annidati inferiscono i tipi dai valori campione.

Regole pratiche

• Includi ogni campo che il modello deve poter inviare — omettere significa «non required», non «opzionale con un default».
• Usa enum realistici come campioni string, poi modifica a mano lo schema se ti serve un array enum esplicito.
• Abilita la modalità strict per emettere additionalProperties: false su ogni oggetto — consigliato per structured outputs e strict tool calling OpenAI.
• Gli array vuoti inferiscono tipi di item deboli — aggiungi almeno un elemento rappresentativo.

I server stdio richiedono command e tipicamente args. I server remoti richiedono un url http o https valido. I valori env devono essere string. Gli errori bloccano la fiducia nell'export; gli avvisi meritano un passaggio manuale.

Envelope client comuni

• La chiave di primo livello deve essere "mcpServers" secondo le convenzioni di Cursor e Claude Desktop
• I server filesystem devono usare percorsi assoluti in allow-list
• Preferisci placeholder env mentre modifichi nel browser; inietta i segreti reali solo sulla macchina locale

I conteggi token combinano system prompt, schema dei tools minificati e JSON MCP. Scegli cl100k_base per un'approssimazione GPT-4 / Claude oppure o200k_base per GPT-4o. I conteggi usano tabelle tiktoken locali — nessuna chiamata API.

• Tratta il numero come un pavimento: cronologia chat e risultati dei tools aggiungono altro a runtime
• Ricontrolla dopo ogni modifica di schema o prompt
• Usa LLM Token Counter quando ti servono mappe di confine o schede di costo mensile su un payload personalizzato

Sintomi: OpenAI rifiuta il payload tools, oppure il modello non riesce a passare argomenti di cui l'app ha davvero bisogno.

Perché succede

Gli schema strict rifiutano chiavi non dichiarate. Se l'esempio JSON ha omesso un campo, non è mai diventato una proprietà. Se la modalità strict è spenta, i limiti structured-output di OpenAI possono comunque rifiutare oggetti aperti.

Diagnosi

Confronta le properties dello schema inferito con gli argomenti che invia l'applicazione. Verifica che la modalità strict sia attiva quando punti agli structured outputs OpenAI.

Fix

1. Aggiungi le chiavi mancanti all'esempio JSON e rigenera lo schema.
2. Abilita la modalità strict così additionalProperties: false è coerente sugli oggetti annidati.
3. Accorcia costrutti non supportati (oneOf profondamente annidati, tipi esotici) secondo i limiti structured output di OpenAI.
4. Riesporta tools JSON e ritesta con un payload di argomenti noto e valido.

Sintomi: errori di validazione su command/url, il client non riesce ad avviare il server, oppure il trasporto remoto non si connette mai.

Perché succede

Voci stdio senza command, remote senza URL http(s), valori env numerici o chiavi di primo livello sbagliate rompono i parser del client.

Diagnosi

Leggi il JSON pointer di ogni errore di lint. Conferma che l'envelope usi mcpServers e che ogni server sia stdio (command) oppure remoto (url), non un ibrido rotto.

Fix

1. Aggiungi command e args per i server stdio; metti tra virgolette tutti i valori env come string.
2. Usa URL http:// o https:// per i trasporti MCP remoti.
3. Correggi il nome della chiave di primo livello in mcpServers.
4. Riesegui la validazione finché non ci sono errori; priorizza gli avvisi prima dello shipping.

Sintomi: le API key compaiono nel JSON esportato, nei diff git o negli screenshot del builder.

Perché succede

I blocchi env MCP sono JSON semplice. Incollare segreti di produzione in uno strumento browser — anche locale — aumenta il rischio di leak via clipboard, condivisione schermo e commit accidentali.

Diagnosi

Cerca negli export e nel pannello MCP pattern sk-, Bearer o chiavi vendor. Verifica che le config commitate contengano solo placeholder.

Fix

1. Sostituisci i segreti con placeholder stile ${ENV_VAR} nel builder.
2. Inietta i valori reali solo nel client desktop locale o nello store di segreti del deploy.
3. Ruota qualsiasi chiave incollata in chat, ticket o schermi condivisi.
4. Aggiungi una scansione segreti pre-commit per mcp.json e i file di bundle dell'agente.

Questo workspace non carica la tua config — ma clipboard e git possono ancora farla trapelare.

• Non committare mai API key nei blocchi env MCP — usa placeholder di variabili d'ambiente
• Usa percorsi assoluti a minimo privilegio per i server MCP filesystem
• Rivedi il budget token prima di aggiungere grandi esempi few-shot ai prompt di produzione
• Preferisci schema strict così i tools non accettano chiavi inattese
• Tratta i bundle esportati come sensibili se contengono nomi di tools interni o host di infra

• Parti da un template, poi elimina i tools che non ti servono — schema più piccoli sono più economici e sicuri
• Nomina i tools con verbi chiari (lookup_order, get_weather) allineati alle istruzioni del system prompt
• Mantieni un'unica fonte di verità: esporta da questo builder invece di mantenere copie di schema divergenti
• Rivalida MCP dopo ogni cambio di percorso o command
• Documenta il budget token nell'export markdown così i reviewer vedono l'impatto di costo nelle PR
• Usa LLM Token Counter per diff encoding approfonditi; usa questo builder per l'agente assemblato