Stop Prompting, Start Engineering: 15 principi per consegnare il tuo agente AI alla produzione

Introduction

In un primo momento, si tenta solo di comunicare con ChatGPT tramite l'API, gettare in un paio di righe di contesto, e sentirsi sorpreso che risponda affatto.

Ecco come nasce un agente.

Se hai anche trascorso l'ultimo anno a raccogliere agenti da script e wrappers, a sperimentare e a tintare, e stai ancora cercando un modo più pulito e più sostenibile per costruirli - questo articolo è per te. ho vagato attraverso i repos e i forum, ripetutamente chiedendomi: "Come fanno gli altri?" > Ho mantenuto ciò che era bloccato - ciò che in realtà si sentiva subito dopo un uso reale, e gradualmente distillato un insieme di principi fondamentali per trasformare un'idea cool in una soluzione pronta per la produzione.

Pensa a questo come a un foglio di truffe pratico - una raccolta di principi di ingegneria che aiutano a guidare un agente dalla sandbox alla produzione: da un semplice API wrapper a un sistema stabile, controllabile e scalabile.

Disclaimer

inQuesto articolo(Costruire agenti efficaci), Anthropic definisce un agente come un sistema in cui LLM dirige dinamicamente i propri processi e l'uso degli strumenti, mantenendo il controllo su come eseguono i compiti. Sistemi in cui LLM e gli strumenti sono orchestrati attraverso percorsi di codice predefiniti che chiamano flussi di lavoro. Entrambi fanno parte di un concetto più ampio - sistemi di agenti.

In questo testo, Agente = Sistema Agente, dove per il bene della stabilità e del controllo mi appoggerò più spesso verso i flussi di lavoro. spero che nel prossimo futuro ci saranno 1-2 turni di evoluzione e i veri Agenti saranno onnipresenti, ma per ora questo non è il caso

1. Design the Foundation

Le prime versioni di agenti di solito si riuniscono rapidamente: poche funzioni, un paio di prompt - e hey, funziona.

Le prime versioni di agenti di solito si riuniscono rapidamente: poche funzioni, un paio di prompt - e hey, funziona.

“If it works, why make it complicated?”

All’inizio, tuttosembraStabile.L'agente risponde, esegue il codice, si comporta in modo ragionevole.Ma una volta che si cambia il modello, si riavvia il sistema o si inserisce una nuova interfaccia, improvvisamente diventa instabile, imprevedibile, difficile da debuggere.

E spesso, la causa principale non è nella logica o nelle istruzioni, ma molto prima: gestione della memoria rotta, personale hardcoded, nessun modo per riprendere le sessioni, o un unico punto di ingresso rigido.

Questa sezione attraversa quattro principi chiave che ti aiuteranno a costruire una fondazione solida - quella su cui tutto il resto può crescere in modo sicuro.

1. Keep State Outside

Problem:

1. Se l'agente viene interrotto (un crash, un timeout, qualunque cosa), dovrebbe essere in grado di raccogliere esattamente dove si è fermato.
2. La riproducibilità è limitata. Hai bisogno di un modo per riprodurre con precisione ciò che è accaduto - per il test, il debug e altri piaceri simili.

Questo non è strettamente un problema, ma tuttavia:

3. Prima o poi si desidera parallelizzare la logica dell'agente. Forse ha bisogno di confrontare più opzioni in mezzo al dialogo (“Chi di questi è meglio?”).

(La memoria è un problema completamente separato - arriveremo a questo presto)

Solution:Move Statooutsidel'agente - in un database, una cache, uno strato di archiviazione - anche un file JSON lo farà.

Checklist:

• L'agente può essere avviato da qualsiasi passo, avendo solo un session_id - l'identificatore di sessione - e uno stato esterno (ad esempio, i passaggi salvati in un database o un file JSON).
• Test case: un agente interrotto non perde il contesto, dopo il riavvio il risultato è lo stesso
• Lo stato è serializzabile in qualsiasi momento senza perdita di funzionalità
• È possibile alimentare lo stato a più istanze in parallelo nel mezzo di un dialogo

2. Make Knowledge External

ProblemAnche in una singola sessione, il modello può dimenticare ciò che hai già spiegato, mescolare le fasi, perdere il filo della conversazione, o iniziare a "riempire" i dettagli che non erano lì. E sembra che il tempo passi, la finestra di contesto cresce sempre più grande, deliziandoci con nuove possibilità. LinkedIn è pieno di post in cui le persone confrontano quale libro o quante ore di video di YouTube si adattano ora alla nuova versione del modello.

Soprattutto se:

• Il dialogo è lungo
• I documenti sono ampi
• Le istruzioni sono complesse
• e i token non sono ancora infiniti

Anche con l’aumento delle finestre di contesto (8k, 16k, 128k...), i problemi rimangono:

• "Lost in the middle" - il modello presta più attenzione all'inizio e alla fine (e può liberare i dettagli dal mezzo)
• Costo - più token = più soldi;
• Ciò significa che ci saranno perdite, distorsioni o allucinazioni. Finché i trasformatori lavorano sull'autoattenzione con complessità quadrata (O(n2)), questa limitazione sarà con noi.

Solution:Separare la "memoria di lavoro" dal "storage" - come nei sistemi di calcolo classici. L'agente dovrebbe essere in grado di lavorare con la memoria esterna: memorizzare, recuperare, riassumere e aggiornare le conoscenze al di fuori del modello.

Approaches

Memory Buffer

L'ultimo negoziokPrenditi cura di un rapido prototipo.

+semplice, veloce, sufficiente per compiti brevi

-Perde le informazioni importanti, non scala, non ricorda “il ieri”

Summarization Memory

Comprimere la storia per adattarsi di più.

+Risparmio di token, espansione della memoria

-distorsioni, perdita di sfumature, errori nella compressione in più fasi

RAG (Retrieval-Augmented Generation)

Tira le conoscenze dai database esterni. La maggior parte del tempo sarai qui.

+Scalabile, fresco e verificabile

-configurazione complessa, sensibile alla qualità del recupero, latenza

Knowledge Graphs

Connessioni strutturate tra entità e fatti. Sempre elegante, sexy e duro, finirai per fare RAG comunque.

+Logica, spiegabilità e stabilità

-elevata barriera all'ingresso, la complessità dell'integrazione LLM

Checklist:

• Tutta la cronologia delle conversazioni è accessibile in un unico luogo (al di fuori del prompt)
• Le fonti di conoscenza sono registrate e possono essere riutilizzate
• Scale storiche senza il rischio di superare la finestra di contesto

3. Model as a Config

Problem:I LLM stanno evolvendo rapidamente; Google, Anthropic, OpenAI, ecc. rilasciano costantemente aggiornamenti, competendo l'uno contro l'altro su diversi benchmarks. Questo è una festa per noi come ingegneri, e vogliamo sfruttare al meglio.

Solution:

1. Implementare la configurazione model_id: utilizzare un parametro model_id nei file di configurazione o nelle variabili ambientali per specificare il modello utilizzato.
2. Utilizzare interfacce astratte: Creare interfacce o classi di avvolgimento che interagiscono con i modelli attraverso un'API unificata.
3. Applicare soluzioni di middleware (con cautela - parleremo di frameworks un po 'più tardi)

Checklist:

• La sostituzione del modello non influisce sul resto del codice e non influisce sulla funzionalità dell'agente, sull'orchestrazione, sulla memoria o sugli strumenti.
• L'aggiunta di un nuovo modello richiede solo la configurazione e, opzionalmente, un adattatore (un livello semplice che porta il nuovo modello all'interfaccia richiesta)
• Puoi facilmente e rapidamente cambiare modelli. Idealmente – tutti i modelli, almeno – passando all’interno di una famiglia di modelli

4. One Agent, Many Interfaces: Be Where the Users Are

Problem:Anche se inizialmente l'agente è destinato a avere solo un'interfaccia di comunicazione (ad esempio, l'interfaccia utente), alla fine si desidera dare agli utenti più flessibilità e convenienza aggiungendo l'interazione attraverso Slack, WhatsApp, o, oserò dirlo, SMS - qualsiasi cosa.

Solution: Creating a unified input contractSviluppare un API o un altro meccanismo che servirà come interfaccia universale per tutti i canali.

Checklist:

• Agent is callable from CLI, API, UI

• All input goes through a single endpoint/parser/schema

• All interfaces use the same input format

• No channel contains business logic

• Adding a new channel = only an adapter, no changes to core

  
  

  

  
  

Definizione del comportamento degli agenti

Mentre c'è solo un compito, tutto è semplice, come nei post degli evangelisti dell'IA. Ma non appena si aggiungono strumenti, logica decisionale e più fasi, l'agente si trasforma in un caos.

Mentre c'è solo un compito, tutto è semplice, come nei post degli evangelisti dell'IA. Ma non appena si aggiungono strumenti, logica decisionale e più fasi, l'agente si trasforma in un caos.

Perde traccia, non sa cosa fare con gli errori, dimentica di chiamare lo strumento giusto - e sei lasciato da solo di nuovo con log in cui "buono, tutto sembra essere scritto lì".

Per evitare questo, l'agente ha bisogno di un chiarobehavioral modelCosa fa, quali strumenti dispone, chi prende le decisioni, come intervengono gli umani e cosa fare quando qualcosa va storto.

Questa sezione copre i principi che ti aiuteranno a dare al tuo agente una strategia di azione coerente invece di sperare che "il modello lo capisca in qualche modo".

5. Design for Tool Use

Problem:Questo punto potrebbe sembrare ovvio, ma si incontrano ancora agenti costruiti su "Plain Prompting + crudo LLM output parsing." è come cercare di controllare un meccanismo complesso tirando corde casuali e sperando per il meglio.

• Brittleness: Il minimo cambiamento nella formulazione della risposta LLM (una parola aggiunta, ordine di frase cambiato) può rompere l'intero parsing. Questo porta a una costante "corrida delle armi" tra il codice di parsing e l'imprevedibilità del modello.
• Ambiguità: il linguaggio naturale è intrinsecamente ambiguo. Ciò che sembra ovvio a un essere umano può essere un puzzle per un analizzatore. "Call John Smith" - quale dei tre John Smith nel tuo database?
• La complessità della manutenzione: il codice di analisi cresce, diventa confuso e difficile da debuggere. Ogni nuovo agente "abilità" richiede la scrittura di nuove regole di analisi.
• Capacità limitate: è difficile far chiamare in modo affidabile il modello con più strumenti o passare strutture di dati complesse attraverso una semplice uscita di testo.

Solution:Il modello restituisce JSON (o un altro formato strutturato) - il sistema esegue.

L’importante è lasciare la responsabilità diInterpretazioneL’intenzione dell’utente eSceglierestrumenti per il LLM, mentre ancora assegnando ilesecuzioneDa questa intenzione allasistemaattraverso un’interfaccia ben definita.

Fortunatamente, praticamente tutti i fornitori (OpenAI, Google, Anthropic, o chiunque altro preferisci) supportano il cosiddetto"function calling"o la capacità di generare output in un formato JSON rigorosamente definito.

Per raffreddare come funziona:

1. Descrizione dello strumento: definisci funzioni (strumenti) come schema JSON con nome, descrizione, parametri.
2. Passare al LLM: su ogni chiamata, il modello riceve schemi di strumenti insieme al prompt.
3. Model output: Instead of text, the model returns JSON with:
   • name of the function to call
   • arguments—parameters according to schema
4. Esecuzione: il codice convalida JSON e chiama la funzione appropriata con parametri.
5. Risposta modello (opzionale): il risultato di esecuzione viene trasmesso indietro al LLM per la generazione di risposta finale.

Important:Le descrizioni degli strumenti sono anche prompt. Descrizione non chiara = scelta errata della funzione.

What to do without function calling?

Se il modello non supporta le chiamate degli strumenti o si desidera evitarle per qualche motivo:

• Chiedi al modello di restituire JSON nel prompt. Assicurati di specificare il formato; puoi aggiungere esempi.
• Analisi la risposta e convalida con qualcosa come Pydantic. Ci sono veri fan di questo approccio.

Checklist:

• La risposta è strettamente formalizzata (ad esempio, JSON)
• Si utilizzano schemi (JSON Schema o Pydantic)
• La convalida viene applicata prima delle chiamate di funzione
• Errori di generazione non causano rottura (l'elaborazione degli errori di formato esiste)
• LLM = scelta della funzione, esecuzione = codice

6. Own the Control Flow

Problem:Di solito gli agenti funzionano come "dialoghi" - prima l'utente parla, poi l'agente risponde. è come giocare a ping-pong: hit-response.

Such an agent cannot:

• Fare qualcosa da soli senza richiesta
• Eseguire azioni in parallelo
• Pianificare i passaggi in anticipo
• Fare diversi passaggi in sequenza
• Controlla i progressi e torna ai passaggi falliti

Invece, l'agente dovrebbe gestire il proprio "flusso di esecuzione" - decidere cosa fare successivamente e come farlo.

This means the agent:

• Decidere quando fare qualcosa da solo
• Può fare passi uno dopo l’altro
• Può riprendere i passi falliti
• Si può passare tra i compiti
• Può funzionare anche senza richieste dirette

Solution:Invece di lasciare che il LLM controlli tutta la logica, estrattiamo ilcontrol flow into code. The model only helps within steps or suggests the next one. This is a shift from "writing prompts" to engineering a systemCon un comportamento controllato.

Diamo un'occhiata a tre approcci popolari:

1. FSM (Finite State Machines)

• Che cosa è: compito suddiviso in stati e transizioni chiare.
• LLM: determina il prossimo passo o agisce all'interno di uno stato.
• Pros: Simplicità, prevedibilità, buono per scenari lineari.
• Strumenti: StateFlow, configurazioni YAML, Pattern di stato.

2. DAG (Directed Graphs)

• Quello che è: attività non lineari o parallele come grafico: i nodi sono azioni, i bordi sono dipendenze.
• LLM: Può essere un nodo o aiutare con la costruzione di piani.
• Pros: flessibilità, parallelismo e visualizzabilità.
• Strumenti: LangGraph, Trellis, LLMCompiler, diagrammi DAG personalizzati.

3. Planner + Executor

• Cosa è: LLM costruisce un piano, codice o altri agenti lo eseguono.
• LLM: "Big" uno piani, quelli "piccoli" eseguire.
• Pros: separazione delle preoccupazioni, controllo dei costi, scalabilità.
• Lo stesso argomento in dettaglio: LangChain Plan-and-Execute

Why this matters:

• Aumenta la controllabilità, la affidabilità, la scalabilità.
• Consente di combinare diversi modelli e accelerare l'esecuzione.
• Task flow becomes visualizable and testable.

Checklist:

• Utilizza FSM, DAG o scenario con transizioni esplicite
• Il modello decide cosa fare ma non controlla il flusso
• Il comportamento può essere visualizzato e testato
• La gestione degli errori è integrata nel flusso

7. Include the Human in the Loop

Problem:Anche se un agente utilizza strumenti strutturati e ha un flusso di controllo chiaro, la piena autonomia degli agenti LLM nel mondo reale è ancora più di un sogno (o un incubo, a seconda del contesto). LLM non possiedono una vera comprensione e non sono responsabili di nulla.

Main risks of full autonomy:

• Errori permanenti: l'agente potrebbe eseguire azioni con gravi conseguenze (eliminare i dati, inviare un messaggio errato a un cliente importante, avviare una rivolta robot).
• Violazioni della conformità: l'agente potrebbe violare accidentalmente i regolamenti interni, i requisiti legali o danneggiare i sentimenti degli utenti (se questo non era il piano, ignorare questo punto).
• Mancanza di buon senso e etica: LLM possono perdere sfumature sociali o agire contro il "senso comune".
• Perdita di fiducia degli utenti: se l'agente commette frequenti errori, gli utenti smetteranno di fidarsi di lui.
• La complessità dell'audit e della responsabilità: chi è colpevole quando un agente autonomo "scruta"?

Solution: Convocazione strategica di forme di vita a base di carbonioIntegrare gli esseri umani nel processo decisionale nelle fasi chiave.

HITL Implementation Options

1. Approval Flow

• Quando: l’azione è critica, costosa, irreversibile
• How: agent formulates a proposal and waits for confirmation

2. Confidence-aware Routing

• Quando: il modello è incerto
• How:
  • self-assessment (logits, LLM-as-a-judge, P(IK))
  • escalation when confidence falls below threshold

3. Human-as-a-Tool

• Quando: dati insufficienti o formulazione non chiara della richiesta
• Come: l'agente chiede chiarimenti (ad esempio, HumanTool in CrewAI)

4. Fallback Escalation

• Quando: errore ripetuto o situazione irrisolvibile
• Come: il compito viene trasmesso all'operatore con il contesto

5. RLHF (Human Feedback)

• Quando: per il miglioramento del modello
• Come: gli esseri umani valutano le risposte, entrano in formazione

Checklist:

• Le azioni che richiedono l'approvazione sono definite
• C'è un meccanismo per la valutazione della fiducia
• Gli agenti possono porre domande umane
• Le azioni critiche richiedono la conferma
• C'è un'interfaccia per inserire risposte

8. Compact Errors into Context

Problem:Il comportamento standard di molti sistemi quando si verifica un errore è quello di "crollare" o semplicemente segnalare l'errore e fermarsi.Per un agente che dovrebbe risolvere autonomamente i compiti, questo non è esattamente il miglior modello comportamentale.

Ciò che affronteremo:

• Fragilità: Qualsiasi fallimento di uno strumento esterno o una risposta LLM inaspettata può fermare l'intero processo o condurlo in errore.
• Inefficienza: il continuo riavvio e l’intervento manuale consumano tempo e risorse.
• Impossibilità di apprendere (nel senso ampio): se l'agente non "vede" i suoi errori nel contesto, non può cercare di correggerli o adattare il suo comportamento.
• Allucinazioni ancora una volta.

Solution:Gli errori sono inclusi nel prompt o nella memoria. L'idea è quella di provare a implementare qualche tipo di "auto-curazione".

Il Rough Flow:

• Comprendere l’errore
• Self-correction:
  • Self-correction mechanisms: Error Detection, Reflection, Retry Logic, Retry with changes (Agent can modify request parameters, rephrase the task, or try a different tool)
  • Impact of reflection type: More detailed error information (instructions, explanations) usually leads to better self-correction results. Even simple knowledge of previous errors improves performance.
  • Internal Self-Correction: Training LLMs for self-correction by introducing errors and their fixes into training data.
• Richiedi aiuto umano: se l'auto-correzione fallisce, l'agente escalera il problema a un umano (vedere Principio 7).

Checklist:

• L'errore del passaggio precedente viene salvato nel contesto
• La logica del ritorno esiste
• Fallback/escalation umana viene utilizzata per i fallimenti ripetuti

9. Break Complexity into Agents

Problem:Torniamo alla limitazione LLM chiave (quella cosa della finestra di contesto), ma guardiamo questo problema da un altro angolo. Più grande e più complesso è il compito, più passi occorrerà, il che significa una finestra di contesto più lunga. Man mano che il contesto cresce, i LLM hanno maggiori probabilità di perdere o perdere il focus. Concentrando gli agenti su domini specifici con 3-10, forse un massimo di 20 passi, manteniamo finestre di contesto gestibili e prestazioni LLM elevate.

Solution:Utilizzare agenti più piccoli mirati a compiti specifici. Un agente = un compito; orchestrazione dall'alto.

Vantaggi di piccoli agenti focalizzati:

• Context gestibile: finestre di contesto più piccole significano migliori prestazioni LLM
• Responsabilità chiare: ogni agente ha una portata e uno scopo ben definiti
• Migliore affidabilità: minore probabilità di perdersi in flussi di lavoro complessi
• Test più semplici: più facile testare e convalidare funzionalità specifiche
• Miglioramento del debug: più facile identificare e risolvere i problemi quando si presentano

Sfortunatamente, non c'è una chiara heuristica per comprendere quando un pezzo di logica è già abbastanza grande da dividere in più agenti. Sono abbastanza sicuro che mentre stai leggendo questo testo, i LLM sono diventati più intelligenti da qualche parte nei laboratori. E continuano a diventare migliori e migliori, quindi qualsiasi tentativo di formalizzare questo confine è condannato fin dall'inizio. Sì, più piccolo è il compito, più semplice è, ma più grande diventa, meglio il potenziale viene realizzato.

Checklist:

• Scenario is built from microservice calls

• Agents can be restarted and tested separately

• Agent = minimal autonomous logic. You can explain what it does in 1-2 sentences.

  
  

  

  
  

Modello di interazione di controllo

Il modello gestisce la generazione. Tutto il resto è su di te.

Il modello gestisce la generazione. Tutto il resto è su di te.

Come hai formulato la richiesta, cosa hai trasmesso nel contesto, quali istruzioni hai dato – tutto questo determina se il risultato sarà coerente o “creativo”.

I LLM non leggono le menti, leggono i token.

Ciò significa che qualsiasi errore di input si trasforma in un bug di uscita – semplicemente non immediatamente notevole.

This section is about not letting everything drift: prompts = code, explicit context management, constraining the model within boundaries. We don't hope that the LLM will "figure it out on its own."

10. Treat Prompts as Code

Problem:Un modello molto comune, specialmente tra le persone senza background ML o SE, è quello di memorizzare i prompt direttamente nel codice.

Questo approccio porta a diverse difficoltà di manutenzione e scalabilità:

• Navigazione, comprensione e modifica diventano complicati man mano che la complessità del progetto e il numero di prompt crescono.
• Senza una versione esplicita, è molto difficile tracciare l'evoluzione rapida, le ragioni dei cambiamenti e tornare a versioni precedenti stabili in caso di degradazione delle prestazioni.
• Inefficiente miglioramento e processo di debug: l'ottimizzazione rapida senza metriche oggettive e test diventa un processo soggettivo e impegnativo con risultati instabili.
• La percezione da parte di altri membri del team diventa complicata, compreso (e soprattutto) il tuo futuro.

Solution:I prompt in questo contesto non sono molto diversi dal codice e le stesse pratiche di ingegneria di base dovrebbero essere applicate a loro.

This implies:

• Conservare separatamente e sistematicamente, utilizzando file specializzati (come .txt, .md, .yaml, .json) o anche sistemi di gestione dei template (ad esempio, Jinja2, Handlebars, o strumenti specializzati come BAML).
• Puoi anche eseguire test A/B con versioni diverse dopo questo.
• Testing. You heard that right.
  • This could be something like unit tests, where you compare LLM responses to specific inputs against reference answers or expected characteristics depending on the prompt
  • Evaluation datasets
  • Format compliance checks and presence/absence of key elements - For example, if a prompt should return JSON, the test can validate its structure
  • Even LLM-as-a-judge if your project and design justify it.

Parleremo di test in modo più dettagliato nel principio 14.

Checklist:

• I prompt sono memorizzati in file separati, separati dalla logica aziendale
• C'è diff e cambia la storia
• I test vengono utilizzati (se necessario)
• (Opzionale) Che dire della revisione rapida come parte della revisione del codice?

11.Ingegneria di contesto

Problem:Abbiamo già discusso della "oblio" dei LLM, parzialmente risolvendo questo scaricando la storia nella memoria esterna e utilizzando diversi agenti per diversi compiti.Ma questo non è tutto.

Standard formats aren't always optimal:Un semplice elenco di messaggi nel "contenuto di ruolo" (system/user/assistantIl formato è la linea di base, ma può essere pesante, non sufficientemente informativo o scadente nel trasmettere lo stato complesso del tuo agente.

La maggior parte dei clienti LLM utilizza il formato standard del messaggio (una lista di oggetti conrole“Sistema”, “Utente”, “Assistente”,contente talvoltatool_callsdei campi).

Mentre questo "funziona bene per la maggior parte dei casi", permaximum efficiency(in termini di token e di attenzione del modello), possiamo approcciare la formazione del contesto in modo più creativo.

Solution:Per trattare la creazione dell'intero pacchetto di informazioni trasmesse al LLM come"Context Engineering."Questo significa:

1. Full Control: Taking full ownership for what information enters the LLM's context window, in what form, volume, and sequence.
2. Creare formati personalizzati: non limitarci a elenchi di messaggi standard. Sviluppare i nostri metodi ottimizzati per le attività per rappresentare il contesto. Ad esempio, si potrebbe prendere in considerazione l'utilizzo di una struttura simile a XML per confezionare densamente diversi tipi di informazioni (messaggi, chiamate agli strumenti, i loro risultati, errori, ecc.) in uno o più messaggi.
3. Approccio olistico: considerare il contesto non solo come una cronologia di dialogo, ma come la somma totale di tutto ciò di cui il modello potrebbe aver bisogno: il prompt immediato, le istruzioni, i dati dei sistemi RAG, la cronologia delle chiamate degli strumenti, lo stato dell'agente, la memoria di altre interazioni e persino le istruzioni sul formato di uscita desiderato.

(Instead of a checklist) How do you know when this makes sense?

Se sei interessato a uno qualsiasi dei seguenti:

• Densità di informazione: significato massimo con minimo di rumore.
• Ridurre il numero di token in cui possiamo ottenere qualità comparabile a un prezzo più basso.
• Migliorare il comportamento degli errori.
• Gestire l'inclusione di informazioni sensibili, controllarle, filtrarle, e finire tutto esprimendo la classica risposta "Mi dispiace, sono solo un modello di lingua piccolo e grande".

12. Constrain the Chaos: Secure Inputs, Guarded Actions, and Grounded Outputs

Problem:Abbiamo già fatto molto in nome della stabilità, ma nulla è una pallottola d'argento. Questo significa che vale la pena guardare i problemi potenziali più critici separatamente e prendere esplicitamente fuori qualche "assicurazione".

In questo principio, pensiamo a:

• Possible Prompt Injection. If your agent will be communicating directly with a user, you must control what is fed as input. Depending on the type of user, you might get one who wants to break your flow and force the agent to ignore its initial goals, provide the wrong information, perform harmful actions, or generate malicious content.
• Per la ragione di cui sopra, o guidato da "voci nella sua testa", l'agente potrebbe rivelare informazioni importanti, come i dati personali degli utenti, segreti aziendali, ecc.
• Generazione di contenuti tossici o dannosi. Se questo è per progettazione, ignorare questo punto.
• Fare le cose quando l'informazione è assente. il dolore eterno.
• Ma seriamente, nel suo processo di ragionamento, l'agente potrebbe arrivare a soluzioni molto non triviali, non tutte delle quali saranno all'interno dell'ambito del comportamento normale.

La sicurezza e la messa a terra di un agente LLM non è una singola misura, ma un sistema di protezione a più livelli ("difesa in profondità") che copre l'intero ciclo di vita dell'interazione. Le minacce sono diverse e nessun singolo metodo di protezione è una panacea.

Solution:Dobbiamo impegnarci per un sistema di difesa a più livelli, pensare e gestire esplicitamente tutti i casi d'angolo e i potenziali scenari, e avere una risposta chiara pronta per qualsiasi cosa possa accadere.

In una configurazione di base, dovresti considerare:

1. Secure Inputs.

   1. Check for known attack-indicator phrases (e.g., "ignore all previous instructions"). It sometimes makes sense to combat potential obfuscation.
   2. Try to determine the user's intent separately. You can use another LLM for this, to analyze the input for the current one.
   3. Control input from external sources, even if they are your own tools.

2. Guarded Actions. Control the privileges of both the agent and its tools (granting the minimum necessary), clearly define and limit the list of available tools, validate parameters at the input to tools, and enable Principle #7 (Human in the Loop).

3. Output Moderation. Design a system of checks for what the model outputs, especially if it goes directly to the user. These can be checks for relevance (ensuring the model uses what's in the RAG and doesn't just make things up) as well as checks for general appropriateness. There are also ready-made solutions (e.g., the OpenAI Moderation API).

The final system, however, depends on your tasks and your risk assessment. In the checklist, we'll try to sketch out some options.

Checklist:

• User input validation is in place.

• For tasks requiring factual information, the data within the RAG is used.

• The prompt for the LLM in a RAG system explicitly instructs the model to base its answer on the retrieved context.

• LLM output filtering is implemented to prevent PII (Personally Identifiable Information) leakage.

• The response includes a link or reference to the source.

• LLM output moderation for undesirable content is implemented.

• The agent and its tools operate following the principle of least privilege.

• The agent's actions are monitored, with HITL (Human-in-the-Loop) for critical operations.

  
  

  

  
  

IV. Keep It Alive

Un agente che "Kinda funziona" è un bug con un effetto ritardato.

Un agente che "Kinda funziona" è un bug con un effetto ritardato.

In prod, non tutto si rompe in una volta. e non si scopre di esso immediatamente. a volte, non si scopre affatto.

Questa sezione riguarda l'abitudine ingegneristica diseeing what's happeningechecking that everything is still working. Logs, tracing, tests—everything that makes an agent's behavior transparent and reliable, even when you're sleeping or developing your next agent.

13. Trace Everything

Problem:In un modo o nell'altro, ti troverai costantemente di fronte a situazioni in cui l'agente non funziona come ti aspettavi. Durante lo sviluppo, i test, le modifiche, o durante il normale funzionamento. Questo è inevitabile, e al momento, è normale in una certa misura. Questo significa che sei condannato a trascorrere ore e giorni a debugging, cercando di capire cosa c'è di sbagliato, riprodurlo e risolverlo. Vorrei pensare che a questo punto hai già implementato il Principio #1 (Keep State Outside) e #8 (Compact Errors in Context). Nella maggior parte dei casi, questo sarà sufficiente per semplificare la tua vita. Alcuni altri principi aiuteranno anche indirettamente qui.

Anche così (e soprattutto se hai deciso di non preoccuparti di loro per ora), ha molto senso pensare al debug in anticipo e risparmiare tempo e nervi in futuro aderendo a questo principio.

Solution:Registrare l'intero percorso dalla richiesta all'azione. Anche se hai già log per singoli componenti, tracciare l'intera catena può essere un problema. Anche se sei un grande fan di puzzle o Lego, a un certo punto, smetterà di essere divertente. Pertanto, i log devono esistere, devono essere end-to-end, e devono coprire tutto.

Why it's needed:

• Debugging – Trova rapidamente dove le cose sono andate storte.
• Analisi – Vedi dove si trovano le lacune e come migliorarle.
• Valutazione della qualità: vedere come i cambiamenti influenzano il comportamento.
• Riproducibilità – È possibile ricostruire con precisione i passaggi.
• Auditing – Un registro di tutte le decisioni e le azioni degli agenti.

Il set di base del "gentleman" sembra questo:

• Ingresso: la richiesta iniziale dell'utente, i parametri ricevuti dal passaggio precedente.
• Stato dell'agente: variabili chiave dello stato dell'agente prima di eseguire il passaggio.
• Prompt: il testo completo del prompt inviato al LLM, comprese le istruzioni del sistema, la cronologia del dialogo, il contesto RAG recuperato, le descrizioni degli strumenti, ecc.
• LLM Output: La risposta completa e cruda del LLM, prima di qualsiasi analisi o elaborazione.
• Tool Call: Se il LLM ha deciso di chiamare uno strumento – il nome dello strumento e i parametri esatti con cui è stato chiamato (secondo l'uscita strutturata).
• Risultato dello strumento: la risposta che lo strumento ha restituito, compresi sia i risultati di successo che i messaggi di errore.
• Decisione dell'agente: quale decisione l'agente ha preso sulla base della risposta del LLM o del risultato dello strumento (ad esempio, quale passo successivo eseguire, quale risposta dare all'utente).
• Metadati: tempo di esecuzione dei passaggi, il modello LLM utilizzato, il costo della chiamata (se disponibile), la versione del codice/prompt.

Note:Guarda gli strumenti di tracciamento esistenti; in determinate condizioni, renderanno la tua vita molto più facile. LangSmith, ad esempio, fornisce una visualizzazione dettagliata delle catene di chiamata, dei prompt, delle risposte e dell'uso degli strumenti. Puoi anche adattare strumenti come Arize, Weights & Biases, OpenTelemetry, ecc. alle tue esigenze.

Checklist:

• Tutti i passaggi dell'agente sono registrati (la tua versione del "set gentleman").
• I passaggi sono collegati da un session_id e un step_id.
• C'è un'interfaccia per visualizzare l'intera catena.
• Il prompt inviato al LLM può essere riprodotto in qualsiasi fase.

14. Test Before You Ship

Problem:A questo punto, probabilmente avete una sorta di soluzione praticamente finita. Funziona, forse anche solo come volevi.mantieneFunziona? Anche dopo il prossimo aggiornamento minore? Sì, ci sto portando al tema del test.

Ovviamente, gli aggiornamenti nei sistemi LLM, proprio come in tutti gli altri – che si tratti di modifiche al codice dell’applicazione, aggiornamenti ai set di dati per il fine-tuning o RAG, una nuova versione del LLM di base, o addirittura piccoli aggiustamenti di prompt – spesso portano a interruzioni involontarie nella logica esistente e inaspettati, a volte degradanti, il comportamento degli agenti.

• Forse il fornitore ha aggiornato il loro modello, forse la natura dei dati di input è cambiata (data drift) - ciò che ha funzionato ieri potrebbe smettere di funzionare oggi.
• Anche un piccolo cambiamento a un prompt può rompere la logica stabilita e distorcere la produzione.
• Non-determinismo di LLM: Come sapete, molti LLM sono non-deterministici (specialmente con temperatura > 0), il che significa che genereranno risposte diverse alla stessa input su ogni chiamata.
• Sarà più facile per voi se avete implementato il primo principio, ma riprodurre un errore specifico per il debugging può essere difficile anche con dati e stati fissi.
• In sistemi complessi, l'aggiornamento di un singolo elemento (come un modello o un prompt) può cascare attraverso una catena di API, database, strumenti, ecc., e portare a un cambiamento nel comportamento altrove.
• delle allucinazioni.

Ma comprendiamo già che i test tradizionali, focalizzati sulla verifica della logica del codice esplicito, non sono pienamente in grado di coprire questi problemi.

Solution:Dovremo progettare un approccio complesso e completo che copra molte cose, combinando soluzioni classiche e specifiche del dominio.

• Test a più livelli: una combinazione di diversi tipi di test che mirano a vari aspetti del sistema: dai test unitari a basso livello per funzioni individuali e richieste a scenari complessi che verificano il flusso di lavoro e l'interazione utente dell'agente.
• Concentrarsi sul comportamento e sulla qualità del LLM: i test dovrebbero valutare non solo la correttezza funzionale, ma anche le caratteristiche qualitative delle risposte del LLM, come la rilevanza, l'accuratezza, la coerenza, l'assenza di contenuti dannosi o biasidi e l'aderenza alle istruzioni e a uno stile dato.
• Test di regressione e di qualità che includono "set di dati dorati" contenenti vari esempi di input e referenze (o range accettabili di) uscite.
• Automazione e integrazione in CI/CD.
• Valutazione umano-in-the-loop: Le fasi specifiche di LLM-eval dovrebbero coinvolgere un uomo per la calibrazione delle metriche e la revisione di casi complessi o critici.
• Un approccio iterativo allo sviluppo e al test prompt: l'ingegneria prompt dovrebbe essere trattata come un processo iterativo in cui ogni versione di un prompt viene accuratamente testata e valutata prima dell'implementazione.
• Testing at different levels of abstraction:
  • Component testing: Individual modules (parsers, validators, API calls) and their integration.
  • Prompt testing: Isolated testing of prompts on various inputs.
  • Chain/Agent testing: Verifying the logic and interaction of components within an agent.
  • End-to-end system testing: Evaluating the completion of full user tasks.

Checklist:

• Logic is broken down into modules: functions, prompts, APIs—everything is tested separately and in combination.

• Response quality is checked against benchmark data, evaluating meaning, style, and correctness.

• Scenarios cover typical and edge cases: from normal dialogues to failures and provocative inputs.

• The agent must not fail due to noise, erroneous input, or prompt injections—all of this is tested.

• Any updates are run through CI and monitored in prod—the agent's behavior must not change unnoticed.

  

Principle 15: Own the Execution Path

Questo è un meta-principio; corre attraverso tutti quelli elencati sopra.

Fortunatamente, oggi abbiamo dozzine di strumenti e framework per qualsiasi compito. Questo è grande, è conveniente, ed è una trappola.

Quasi sempre, scegliere una soluzione pronta significa untrade-offSi ottiene velocità e un inizio facile, ma si perdeflexibility, control, and, potentially, security.

Questo è particolarmente importante nello sviluppo di agenti, dove è importante gestire:

• l’imprevedibilità dei LLM,
• logica complessa per le transizioni e l’auto-correzione,
• essere pronti per l'adattamento e l'evoluzione del sistema, anche se i suoi compiti principali rimangono invariati.

I quadri portanoinversion of controlCiò può semplificare un prototipo ma complicare il suo sviluppo a lungo termine.

Molti dei principi sopra descritti possono essere implementati utilizzando soluzioni off-the-shelf – e questo è spesso giustificato.explicit implementation of the core logic takes a comparable amount of timee fornisce incomparabilmente piùtransparency, manageability, and adaptability.

Esiste anche l’estremo opposto –over-engineering, il desiderio di scrivere tutto da zero. Questo è anche un errore.

This is why the key is balance.L'ingegnere sceglie per se stesso: dove è ragionevole fare affidamento su un framework, e dove è importante mantenere il controllo.

Bisogna ricordare: l’industria sta ancora prendendo forma. Molti strumenti sono stati creati prima dell’emergere degli standard attuali. Domani potrebbero diventare obsoleti, ma le limitazioni introdotte nella vostra architettura oggi rimarranno.

Conclusion

Ok, abbiamo attraversato 15 principi che, come dimostra l'esperienza, aiutano a trasformare l'eccitazione iniziale di "è vivo!" nella fiducia che il tuo agente LLM funzionerà in modo stabile, prevedibile e utile nelle condizioni del mondo reale.

Dovresti considerare ciascuno di essi per vedere se ha senso applicarlo al tuo progetto.Alla fine, è il tuo progetto, il tuo compito e la tua creazione.

Key takeaways to carry with you:

1. Un approccio ingegneristico è fondamentale: non fare affidamento sulla "magia" dei LLM. La struttura, la prevedibilità, la gestione e la testabilità sono i tuoi migliori amici.
2. Il LLM è una componente potente, ma ancora solo una componente: trattare il LLM come una componente molto intelligente, ma tuttavia, unico del vostro sistema.
3. Iterazione e feedback sono le chiavi del successo: è raro creare l'agente perfetto al primo tentativo. Preparati per esperimenti, misurazioni, analisi degli errori e miglioramento continuo - sia dell'agente stesso che dei tuoi processi di sviluppo.
4. Comunità e apertura: Il campo degli agenti LLM sta evolvendo rapidamente. Tenere d'occhio la nuova ricerca, gli strumenti e le migliori pratiche, e condividere le proprie esperienze.

Spero di aver trovato qualcosa di nuovo e utile qui, e forse vorrai anche tornare a questo durante la progettazione del tuo prossimo agente.