Opriți promptarea, începeți ingineria: 15 principii pentru a livra agentul dvs. AI la producție

Introduction

La început, încercați doar să comunicați cu ChatGPT prin API, aruncați în câteva rânduri de context și vă simțiți uimiți că răspunde deloc.

Așa se naște un agent.

Dacă ați petrecut, de asemenea, anul trecut strângând agenți de la scripturi și învelișuri, experimentând și tinching, și sunteți încă în căutarea unei modalități mai curate, mai durabile de a le construi - acest articol este pentru tine. am rătăcit prin repo și forumuri, întrebându-mă în mod repetat, "Cum fac alții?" > Am păstrat ceea ce a fost blocat - ceea ce sa simțit de fapt imediat după o utilizare reală, și a distilat treptat un set de principii de bază pentru a transforma o idee rece într-o soluție gata de producție.

Gândiți-vă la acest lucru ca la o foaie de cheat practică - o colecție de principii de inginerie care ajută la ghidarea unui agent de la cutia de nisip la producție: de la un simplu înveliș API la un sistem stabil, controlabil și scalabil.

Disclaimer

înAcest articol(Construirea agenților eficienți), Anthropic definește un agent ca un sistem în care LLM-urile își direcționează dinamic propriile procese și utilizarea instrumentelor, menținând controlul asupra modului în care îndeplinesc sarcinile.

În acest text, Agent = Sistemul Agentului, în cazul în care, din motive de stabilitate și control, mă voi apleca mai des spre fluxuri de lucru. sper că în viitorul apropiat vor exista încă 1-2 tururi ale evoluției și adevărații Agenți vor fi omniprezent, dar pentru moment acest lucru nu este cazul

1. Design the Foundation

Versiunile timpurii de agenți vin de obicei împreună repede: câteva funcții, câteva îndemnuri - și hei, funcționează.

Versiunile timpurii de agenți vin de obicei împreună repede: câteva funcții, câteva îndemnuri - și hei, funcționează.

“If it works, why make it complicated?”

La început, totulSe pareAgentul răspunde, execută cod, se comportă în mod rezonabil.Dar odată ce schimbați modelul, reporniți sistemul sau conectați o nouă interfață – dintr-o dată devine instabilă, imprevizibilă, dificil de depășit.

Și adesea, cauza rădăcină nu este în logică sau în îndemnuri, ci mult mai devreme: gestionarea defectuoasă a memoriei, personalul hardcoded, nici o modalitate de a relua sesiunile sau un singur punct de intrare rigid.

Această secțiune trece prin patru principii cheie care vă vor ajuta să construiți o fundație solidă - una pe care orice altceva poate crește în siguranță.

1. Keep State Outside

Problem:

1. You can’t resume the process. If the agent gets interrupted (a crash, a timeout, whatever), it should be able to pick up exactly where it left off.
2. Ai nevoie de o modalitate de a reproduce cu precizie ceea ce s-a întâmplat - pentru testare, debugging și alte plăceri similare.

Acest lucru nu este strict o problemă, dar totuși:

3. Mai devreme sau mai târziu veți dori să paralelizați logica agentului. Poate că trebuie să compare mai multe opțiuni în mijlocul dialogului („Care dintre acestea este mai bine?”).

(Memoria este o întreagă problemă separată - vom ajunge la asta în curând)

Solution:Mutați statuloutsideagentul - într-o bază de date, un cache, un strat de stocare - chiar și un fișier JSON va face.

Checklist:

• Agentul poate fi lansat din orice pas, având doar un session_id – identificatorul sesiunii – și starea externă (de exemplu, pași salvați într-o bază de date sau un fișier JSON).
• Caz de testare: un agent întrerupt nu pierde contextul, după repornire rezultatul este același
• Starea este serializabilă în orice moment fără pierderea funcționalității
• Puteți alimenta starea în mai multe instanțe în paralel în mijlocul unui dialog

2. Make Knowledge External

Problem: LLM-urile nu-și amintesc. Chiar și într-o singură sesiune, modelul poate uita ceea ce ați explicat deja, amestecă etapele, pierde firul de conversație sau începe să "umple" detalii care nu erau acolo. Și se pare că timpul trece, fereastra de context crește din ce în ce mai mare, încântați-ne cu noi posibilități. LinkedIn este plin de postări în care oamenii compară ce carte sau cât de multe ore de video YouTube se potrivesc acum în noua versiune de model.

Mai ales dacă:

• Dialogul este lung
• Documentele sunt largi
• Instrucțiunile sunt complexe
• și token-urile încă nu sunt infinite

Chiar și cu ferestrele contextuale în creștere (8k, 16k, 128k...), problemele rămân:

• "Lost in the middle" - modelul acordă mai multă atenție începutului și sfârșitului (și poate slăbi detaliile din mijloc)
• Cost – mai multe token-uri = mai mulți bani;
• Ceea ce înseamnă că vor exista pierderi, distorsiuni sau halucinații. Atâta timp cât transformatorii lucrează pe auto-atenție cu complexitate pătrată (O(n2)), această limitare va fi cu noi.

Solution:Separați "memoria de lucru" de "stocare" - ca în sistemele clasice de calcul. Agentul ar trebui să poată lucra cu memoria externă: stoca, recupera, rezuma și actualiza cunoștințele în afara modelului.

Approaches

Memory Buffer

Cumpără ultimelekÎncearcă să faci prototipuri rapide.

+simplu, rapid, suficient pentru sarcini scurte

-pierde informații importante, nu scalează, nu își amintește „ieri”

Summarization Memory

Comprimați istoria pentru a se potrivi mai mult.

+economii de token, expansiune de memorie

-distorsiuni, pierderea nuanțelor, erori în compresia în mai multe etape

RAG (Retrieval-Augmented Generation)

Trage cunoștințele din bazele de date externe. Cea mai mare parte a timpului vei fi aici.

+Scalabil, proaspăt, verificabil

-setare complexă, sensibilă la calitatea recuperării, latență

Knowledge Graphs

Legături structurate între entități și fapte. întotdeauna elegant, sexy și greu, veți sfârși prin a face RAG oricum.

+logică, explicabilitate, stabilitate

-barieră ridicată de intrare, complexitatea integrării LLM

Checklist:

• Toate istoricul conversațiilor este accesibil într-un singur loc (în afara promptului)
• Sursele de cunoștințe sunt înregistrate și pot fi reutilizate
• Scale istorice fără riscul de a depăși fereastra de context

3. Model as a Config

Problem:LLM-urile evoluează rapid; Google, Anthropic, OpenAI etc. eliberează în mod constant actualizări, alergând unul împotriva celuilalt pe diferite criterii de referință. Aceasta este o sărbătoare pentru noi ca ingineri și vrem să profităm la maximum de ea. agentul nostru ar trebui să poată trece cu ușurință la un model mai bun (sau, dimpotrivă, mai ieftin) fără probleme.

Solution:

1. Implementarea configurației model_id: Utilizați un parametru model_id în fișierele de configurație sau în variabilele de mediu pentru a specifica modelul utilizat.
2. Utilizați interfețe abstracte: Creați interfețe sau clase de înfășurare care interacționează cu modelele printr-un API unificat.
3. Aplicați soluții middleware (cu atenție - vom vorbi despre frameworks puțin mai târziu)

Checklist:

• Înlocuirea modelului nu afectează restul codului și nu afectează funcționalitatea agentului, orchestrarea, memoria sau instrumentele
• Adăugarea unui nou model necesită doar configurare și, opțional, un adaptor (un strat simplu care aduce noul model la interfața necesară)
• Puteți schimba ușor și rapid modelele. În mod ideal - orice model, cel puțin - comutând în cadrul unei familii de modele

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

Problem:Chiar dacă inițial agentul este destinat să aibă doar o singură interfață de comunicare (de exemplu, UI), veți dori în cele din urmă să oferiți utilizatorilor mai multă flexibilitate și confort prin adăugarea de interacțiune prin Slack, WhatsApp sau, îndrăznesc să spun, SMS - orice.

Solution: Creating a unified input contractDezvoltați un API sau un alt mecanism care va servi ca o interfață universală pentru toate canalele.

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

  
  

  

  
  

II. Definirea comportamentului agentului

Deși există doar o singură sarcină, totul este simplu, ca și în postările evangheliștilor AI. Dar de îndată ce adăugați instrumente, logică de luare a deciziilor și mai multe etape, agentul se transformă într-un dezordine.

Deși există doar o singură sarcină, totul este simplu, ca și în postările evangheliștilor AI. Dar de îndată ce adăugați instrumente, logică de luare a deciziilor și mai multe etape, agentul se transformă într-un dezordine.

Se pierde, nu știe ce să facă cu greșelile, uită să sune instrumentul potrivit - și ești lăsat singur din nou cu jurnalele în care "bine, totul pare să fie scris acolo".

Pentru a evita acest lucru, agentul are nevoie de o clarăbehavioral modelCe face, ce instrumente are, cine ia decizii, cum intervin oamenii și ce să facă atunci când ceva nu merge bine.

Această secțiune acoperă principiile care vă vor ajuta să vă oferiți agentului dvs. o strategie de acțiune coerentă, în loc să sperați că "modelul va afla cumva".

5. Design for Tool Use

Problem:Acest punct poate părea evident, dar încă vă confruntați cu agenți construiți pe "Plain Prompting + Raw LLM output parsing." Este ca și cum ați încerca să controlați un mecanism complex prin tragere șiruri aleatorii și speranța pentru cel mai bun.

• Brittleness: Cea mai mică schimbare în formularea răspunsului LLM (un cuvânt adăugat, ordinea frazei schimbată) poate rupe întreaga analiză.
• Ambiguitate: Limbajul natural este inerent ambigu.Ceea ce pare evident unui om poate fi un puzzle pentru un anchetator. „Call John Smith” – care dintre cele trei John Smiths din baza ta de date?
• Complexitatea întreținerii: Codul de analiză crește, devine confuz și dificil de corectat.Fiecare nou agent "aptitudini" necesită scrierea de noi reguli de analiză.
• Capacități limitate: Este dificil să se facă modelul să apeleze în mod fiabil la mai multe instrumente sau să treacă structuri de date complexe prin ieșirea textului simplu.

Solution:Modelul returnează JSON (sau un alt format structurat) – sistemul execută.

Ideea cheie aici este de a lăsa responsabilitatea pentruInterpretareaUtilizatorul intenţionează şiAlegereainstrumente pentru LLM, în timp ce alocareaexecuţieDin această intenţie lasistemuluiPrin intermediul unei interfețe bine definite.

Din fericire, practic toți furnizorii (OpenAI, Google, Anthropic sau oricine altcineva preferați) suportă așa-numitele"function calling"sau capacitatea de a genera rezultate într-un format JSON strict definit.

Pentru a reface modul în care funcționează:

1. Descrierea instrumentului: Definiți funcțiile (instrumente) ca Schema JSON cu nume, descriere, parametri.
2. Trecerea la LLM: La fiecare apel, modelul primește scheme de instrumente împreună cu promptul.
3. Model output: Instead of text, the model returns JSON with:
   • name of the function to call
   • arguments—parameters according to schema
4. Execuție: Codul validă JSON și cheamă funcția corespunzătoare cu parametri.
5. Răspunsul modelului (opțional): rezultatul execuției este transmis înapoi la LLM pentru generarea răspunsului final.

Important:Descrierile instrumentelor sunt, de asemenea, prompturi. Descriere neclară = alegerea greșită a funcției.

What to do without function calling?

Dacă modelul nu acceptă apelurile la instrumente sau dacă doriți să le evitați din anumite motive:

• Solicitați modelului să returneze JSON în prompt. Asigurați-vă că specificați formatul; puteți adăuga exemple.
• Analizați răspunsul și validați-l cu ceva ca Pydantic. Există fani reali ai acestei abordări.

Checklist:

• Răspunsul este strict formalizat (de exemplu, JSON)
• Schemele sunt utilizate (JSON Schema sau Pydantic)
• Validarea se aplică înainte de apelurile de funcție
• Erorile de generare nu cauzează defecțiuni (gestionarea erorilor de formatare există)
• LLM = alegere funcție, execuție = cod

6. Own the Control Flow

Problem:De obicei, agenții funcționează ca „dialoguri” – mai întâi utilizatorul vorbește, apoi agentul răspunde.

Such an agent cannot:

• Fă ceva pe cont propriu, fără o cerere
• Efectuează acțiuni în paralel
• Planificați pașii în avans
• Faceți mai multe pași în secvență
• Verificați progresul și reveniți la pașii eșuați

În schimb, agentul ar trebui să-și gestioneze propriul "flux de execuție" - să decidă ce să facă în continuare și cum să o facă.

This means the agent:

• decide când să facă ceva de unul singur
• Puteți face pași unul după altul
• Puteți retrage pașii eșuați
• Puteți comuta între sarcini
• poate funcționa chiar și fără solicitări directe

Solution:În loc să lăsăm LLM să controleze toată logica, extragemcontrol flow into code. The model only helps within steps or suggests the next one. This is a shift from "writing prompts" to engineering a systemcu un comportament controlat.

Să ne uităm la trei abordări populare:

1. FSM (Finite State Machines)

• Ce este: Sarcina împărțită în state și tranziții clare.
• LLM: Determină următorul pas sau acționează într-un stat.
• Pro: Simplitate, predictibilitate, bun pentru scenarii liniare.
• Instrumente: StateFlow, Configurări YAML, Model de stat.

2. DAG (Directed Graphs)

• Ce este: sarcini nelineare sau paralele ca grafic: nodurile sunt acțiuni, marginile sunt dependențe.
• LLM: Poate fi un nod sau ajutor cu construcția planului.
• Avantaje: Flexibilitate, paralelism și vizualizabilitate.
• Instrumente: LangGraph, Trellis, LLMCompiler, diagrame DAG personalizate.

3. Planner + Executor

• Ce este: LLM construiește un plan, cod sau alți agenți îl execută.
• LLM: "Big" unul planuri, cele "mici" executa.
• Avantaje: Separarea preocupărilor, controlul costurilor, scalabilitatea.
• Planificare și execuție LangChain Plan-and-Execute

Why this matters:

• Crește controlabilitatea, fiabilitatea și scalabilitatea.
• Permite combinarea diferitelor modele și accelerarea execuției.
• Fluxul de sarcini devine vizibil și testabil.

Checklist:

• Folosește FSM, DAG sau scenariu cu tranziții explicite
• Modelul decide ce să facă, dar nu controlează fluxul
• Comportamentul poate fi vizualizat și testat
• Gestionarea erorilor este construită în flux

7. Include the Human in the Loop

Problem:Chiar dacă un agent utilizează instrumente structurate și are un flux clar de control, autonomia deplină a agenților LLM în lumea reală este încă mai mult un vis (sau un coșmar, în funcție de context). LLM-urile nu posedă o înțelegere adevărată și nu sunt responsabile pentru nimic.

Main risks of full autonomy:

• Greșeli permanente: Agentul poate efectua acțiuni cu consecințe grave (ștergerea datelor, trimiterea unui mesaj incorect unui client important, lansarea unei revolte a robotilor).
• Încălcări ale conformității: Agentul ar putea încălca accidental reglementările interne, cerințele legale sau ar putea răni sentimentele utilizatorului (dacă nu era planul, ignorați acest punct).
• Lack of common sense and ethics: LLMs might miss social nuances or act against "common sense."
• Pierderea încrederii utilizatorilor: Dacă agentul face greșeli frecvente, utilizatorii vor înceta să mai aibă încredere în el.
• Complexitatea auditului și a răspunderii: Cine este de vină atunci când un agent autonom "scoate"?

Solution: Convocarea strategică a formelor de viață bazate pe carbonIntegrarea oamenilor în procesul de luare a deciziilor în etapele cheie.

HITL Implementation Options

1. Approval Flow

• Când: acțiunea este critică, costisitoare, ireversibilă
• Cum: agentul formulează o propunere și așteaptă confirmarea

2. Confidence-aware Routing

• Când: modelul este incert
• How:
  • self-assessment (logits, LLM-as-a-judge, P(IK))
  • escalation when confidence falls below threshold

3. Human-as-a-Tool

• Când: date insuficiente sau formulare neclară a cererii
• Cum: agentul solicită clarificări (de exemplu, HumanTool în CrewAI)

4. Fallback Escalation

• Când: eroare repetată sau situație nerezolvată
• Cum: sarcina este transmisă operatorului cu context

5. RLHF (Human Feedback)

• Când: pentru îmbunătățirea modelului
• Cum: Omul evaluează răspunsurile, ele intră în formare

Checklist:

• Acțiunile care necesită aprobarea sunt definite
• Există un mecanism de evaluare a încrederii
• Agentul poate pune întrebări oamenilor
• Acțiunile critice necesită confirmare
• Există o interfață pentru introducerea răspunsurilor

8. Compact Errors into Context

Problem:Comportamentul standard al multor sisteme atunci când apare o eroare este de a "se prăbuși" sau pur și simplu de a raporta eroarea și de a opri. Pentru un agent care ar trebui să rezolve sarcinile în mod autonom, acest lucru nu este exact cel mai bun model de comportament.

Cu ce ne vom confrunta:

• Fragilitate: Orice eșec într-un instrument extern sau un răspuns neașteptat la LLM poate opri întregul proces sau îl poate duce în eroare.
• Eficiență: redeschiderea constantă și intervenția manuală consumă timp și resurse.
• Incapacitatea de a învăța (în sens larg): Dacă agentul nu-și "vede" greșelile în context, nu poate încerca să le repare sau să-și adapteze comportamentul.
• Halucinații din nou.

Solution:Erorile sunt incluse în prompt sau memorie. Ideea este de a încerca să pună în aplicare un fel de "auto-vindecare". agentul ar trebui să încerce cel puțin să-și corecteze comportamentul și să se adapteze.

În fluxul dur:

• Înțelegerea erorii
• 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.
• Request human help: If self-correction fails, the agent escalates the problem to a human (see Principle 7).

Checklist:

• Eroarea din pasul precedent este salvată în context
• Logica retrogradă există
• Fallback/escaladarea umană este utilizată pentru eșecuri repetate

9. Break Complexity into Agents

Problem:Să ne întoarcem la limitarea cheie LLM (acest lucru fereastra de context), dar să ne uităm la această problemă dintr-un alt unghi. Cu cât sarcina este mai mare și mai complexă, cu atât vor fi necesare mai multe etape, ceea ce înseamnă o fereastră de context mai lungă. Pe măsură ce contextul crește, LLM-urile sunt mai susceptibile să se piardă sau să piardă concentrarea. Prin concentrarea agenților pe domenii specifice cu 3-10, poate maximum 20 de etape, menținem ferestre de context gestionabile și o performanță LLM ridicată.

Solution:Utilizați agenți mai mici care vizează sarcini specifice. Un agent = o sarcină; orchestrarea de sus.

Beneficiile agenților mici și concentrați:

• Context gestionabil: ferestrele de context mai mici înseamnă o performanță mai bună a LLM
• Clear responsibilities: Each agent has a well-defined scope and purpose
• Fiabilitate îmbunătățită: mai puține șanse de a vă pierde în fluxurile de lucru complexe
• Simpler testing: Easier to test and validate specific functionality
• Depanare îmbunătățită: mai ușor de identificat și de corectat problemele atunci când apar

Din păcate, nu există nicio heuristică clară pentru a înțelege când o bucată de logică este deja suficient de mare pentru a fi împărțită în mai mulți agenți. Sunt destul de sigur că în timp ce citiți acest text, LLM-urile au devenit mai inteligente undeva în laboratoare. Și ele continuă să devină mai bune și mai bune, astfel încât orice încercare de a formaliza această limită este condamnată de la început. Da, cu cât sarcina este mai mică, cu atât este mai simplă, dar cu cât devine mai mare, cu atât mai bine potențialul este realizat. Intuiția corectă va veni numai cu experiență.

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.

  
  

  

  
  

III. Modelul de interacțiune de control

The model handles generation. Everything else is on you.

Modelul se ocupă de generație.Tot restul depinde de tine.

Cum ați formulat cererea, ce ați trecut în context, ce instrucțiuni ați dat – toate acestea determină dacă rezultatul va fi coerent sau „creativ”.

LLM-urile nu citesc mințile, ele citesc jetoanele.

Ceea ce înseamnă că orice eroare de intrare se transformă într-o eroare de ieșire – pur și simplu nu este imediat vizibilă.

Această secțiune este despre a nu lăsa totul să se miște: prompts = cod, gestionarea explicită a contextului, constrângerea modelului în limite.

10. Treat Prompts as Code

Problem:Un model foarte comun, mai ales în rândul persoanelor fără fundal ML sau SE, este stocarea prompturilor direct în cod sau, în cel mai bun caz, stocarea nesistematică în fișiere externe.

Această abordare duce la mai multe dificultăți de întreținere și scalare:

• Navigarea, înțelegerea și modificarea devin complicate pe măsură ce complexitatea proiectului și numărul de solicitări cresc.
• Fără versiuni explicite, este foarte dificil să se urmărească evoluția promptă, motivele modificărilor și să se reîntoarcă la versiunile stabile anterioare în cazul degradării performanței.
• Procesul de îmbunătățire și de debugare ineficient: optimizarea promptă fără metrici și teste obiective devine un proces subiectiv și intens de muncă, cu rezultate instabile.
• Perception by other team members becomes complicated, including (and especially) future you.

Solution: Prompts in this context are not much different from code and the same basic engineering practices should be applied to them

This implies:

• Stochează separat și sistematic, folosind fișiere specializate (cum ar fi .txt, .md, .yaml, .json) sau chiar sisteme de gestionare a șabloanelor (de exemplu, Jinja2, Handlebars sau instrumente specializate cum ar fi BAML).
• Poți chiar să faci teste A/B cu diferite versiuni după aceea.
• 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.

Vom vorbi despre testare în detaliu în principiul 14.

Checklist:

• Prompte sunt stocate în fișiere separate, separate de logica de afaceri
• Există difuzie și schimbarea istoriei
• Testele sunt utilizate (dacă este necesar)
• (Opțional) Ce se întâmplă cu revizuirea promptă ca parte a revizuirii codului?

11.Contextul ingineriei

Problem:Am discutat deja despre "uitatul" LLM-urilor, rezolvând parțial acest lucru prin descărcarea istoricului în memoria externă și utilizarea de agenți diferiți pentru sarcini diferite. dar asta nu este tot.

Standard formats aren't always optimal:O listă simplă de mesaje în "conținutul de rol" (system/user/assistantFormatul este baza, dar poate fi greu, nu este suficient de informativ sau slab în transmiterea stării complexe a agentului.

Majoritatea clienților LLM folosesc formatul standard de mesaj (o listă de obiecte curole„Sistem”, „utilizator”, „asistent”,content, and sometimes tool_callsde câmpuri).

În timp ce acest lucru "funcționează foarte bine pentru majoritatea cazurilor", pentru amaximum efficiency(în ceea ce privește atât tokenurile, cât și atenția modelului), putem aborda formarea contextului mai creativ.

Solution:Pentru a trata crearea întregului pachet de informații transmise LLM ca"Context Engineering."Aceasta înseamnă:

1. Control complet: Luarea de proprietate deplină asupra informațiilor care intră în fereastra de context a LLM, în ce formă, volum și secvență.
2. Crearea de formate particularizate: Nu ne limităm la listele standard de mesaje. Dezvoltarea propriilor noastre modalități optimizate pentru activități de reprezentare a contextului. De exemplu, ați putea lua în considerare utilizarea unei structuri asemănătoare XML pentru a împacheta dens diferite tipuri de informații (mesajele, apelurile la instrumente, rezultatele lor, erorile etc.) într-unul sau mai multe mesaje.
3. Abordare holistică: Privind contextul nu doar ca pe un istoric de dialog, ci ca pe suma totală a tot ceea ce modelul ar putea avea nevoie: promptul imediat, instrucțiunile, datele din sistemele RAG, istoricul apelurilor la instrumente, starea agentului, memoria din alte interacțiuni și chiar instrucțiunile privind formatul de ieșire dorit.

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

Dacă sunteți interesat de oricare dintre următoarele:

• Densitatea informaţiei: semnificaţie maximă cu zgomot minim.
• Reducerea numărului de token-uri în care putem obține o calitate comparabilă la un preț mai mic.
• Îmbunătățirea erorilor de manipulare.
• Gestionarea includerii informațiilor sensibile, controlul acesteia, filtrarea acesteia și încheierea cu răspunsul clasic "îmi pare rău, sunt doar un model de limbă mic și mare".

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

Problem:Am făcut deja multe în numele stabilității, dar nimic nu este un glonț de argint. Acest lucru înseamnă că merită să ne uităm la problemele potențiale cele mai critice separat și să luăm în mod explicit o anumită „asigurare”.

În acest principiu, ne gândim la:

• Dacă agentul dvs. va comunica direct cu un utilizator, trebuie să controlați ceea ce este alimentat ca intrare. În funcție de tipul de utilizator, puteți obține unul care dorește să vă întrerupă fluxul și să forțeze agentul să-și ignore obiectivele inițiale, să furnizeze informațiile greșite, să efectueze acțiuni dăunătoare sau să genereze conținut rău intenționat.
• Din motivul de mai sus, sau condus de "voci în cap", agentul poate dezvălui informații importante, cum ar fi datele personale ale utilizatorilor, secretele corporative etc.
• Generarea de conținut toxic sau rău intenționat. Dacă acest lucru este de proiectare, ignorați acest punct.
• A face lucruri atunci când informația este absentă. durerea eternă.
• Ridicarea mașinilor, amintiți-vă? Dar în mod serios, în procesul său de raționament, agentul ar putea ajunge la soluții foarte non-triviale, nu toate dintre care vor fi în cadrul comportamentului normal.

Securitatea și întemeierea unui agent LLM nu este o singură măsură, ci un sistem de protecție cu mai multe straturi ("apărare în profunzime") care acoperă întregul ciclu de viață al interacțiunii. Amenințările sunt diverse și nici o singură metodă de protecție nu este o panaceu.

Solution:Trebuie să ne angajăm într-un sistem de apărare cu mai multe straturi, să gândim și să tratăm în mod explicit toate cazurile de colț și scenariile potențiale și să avem un răspuns clar pregătit pentru orice s-ar putea întâmpla.

Într-o configurație de bază, ar trebui să luați în 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).

Sistemul final, totuși, depinde de sarcinile dvs. și de evaluarea riscurilor. În lista de verificare, vom încerca să schițăm câteva opțiuni.

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 agent care "funcționează" este un bug cu un efect întârziat.

Un agent care "funcționează" este un bug cu un efect întârziat.

Nu totul se rupe dintr-o data. si nu afli despre el imediat. uneori, nu afli deloc.

Această secţiune se referă la obiceiul deseeing what's happeningşichecking that everything is still workingJurnalele, urmărirea, testele – tot ceea ce face ca comportamentul unui agent să fie transparent și fiabil, chiar și atunci când dormi sau dezvolți următorul agent.

13. Trace Everything

Problem:Într-un fel sau altul, vă veți confrunta în mod constant cu situații în care agentul nu funcționează așa cum v-ați așteptat. În timpul dezvoltării, testării, efectuării de modificări sau în timpul funcționării normale. Acest lucru este inevitabil și, în acest moment, este normal într-o anumită măsură. Acest lucru înseamnă că sunteți condamnați să petreceți ore și zile debugând, încercând să înțelegeți ce este greșit, reproducând problema și corectând-o. Aș dori să cred că la acest punct ați implementat deja Principiul #1 (Keep State Outside) și #8 (Erori compacte în context). În majoritatea cazurilor, acest lucru va fi suficient pentru a vă face viața mult mai simplă.

Chiar și așa (și mai ales dacă ați decis să nu vă deranjați cu ele pentru moment), are mult sens să vă gândiți la debugging în avans și să vă economisiți timp și nervi în viitor, aderând la acest principiu.

Solution:Înregistrați întreaga cale de la cerere la acțiune. Chiar dacă aveți deja jurnalele pentru componente individuale, urmărirea întregului lanț poate fi o problemă. Chiar dacă sunteți un mare fan al puzzle-urilor sau Lego, la un moment dat, va înceta să mai fie distractiv. Prin urmare, jurnalele trebuie să existe, trebuie să fie de la capăt la capăt și trebuie să acopere totul.

Why it's needed:

• Debugging – Găsiți rapid unde au mers lucrurile greșit.
• Analiza – Află unde sunt blocajele și cum să le îmbunătățești.
• Evaluarea calității – vezi cum schimbările afectează comportamentul.
• Reproductibilitate – Puteți reconstrui cu precizie pașii.
• Audit – un jurnal al tuturor deciziilor și acțiunilor agenților.

The basic "gentleman's set" looks like this:

• Introducere: Cererea inițială a utilizatorului, parametrii primiți din pasul anterior.
• Starea agentului: variabile cheie ale stării agentului înainte de executarea pasului.
• Prompt: Textul complet al promptului trimis la LLM, inclusiv instrucțiunile de sistem, istoricul dialogului, contextul RAG recuperat, descrierile instrumentelor etc.
• LLM Output: Răspunsul complet, brut din LLM, înainte de orice analiză sau procesare.
• Instrument Call: Dacă LLM a decis să sune un instrument – numele instrumentului și parametrii exacți cu care a fost apelat (în funcție de ieșirea structurată).
• Rezultatul instrumentului: Răspunsul pe care instrumentul l-a returnat, inclusiv atât rezultatele reușite, cât și mesajele de eroare.
• Decizia agentului: Ce decizie a luat agentul pe baza răspunsului LLM sau a rezultatului instrumentului (de exemplu, ce pas următor să facă, ce răspuns să dea utilizatorului).
• Metadate: timpul de execuție pas, modelul LLM utilizat, costul apelului (dacă este disponibil), versiunea de cod / prompt.

Note:Verificați instrumentele de urmărire existente; în anumite condiții, acestea vă vor face viața mult mai ușoară. LangSmith, de exemplu, oferă o vizualizare detaliată a lanțurilor de apeluri, a apelurilor, a răspunsurilor și a utilizării instrumentelor. De asemenea, puteți adapta instrumente precum Arize, Weights & Biases, OpenTelemetry etc. pentru nevoile dvs. Dar, mai întâi, consultați Principiul #15.

Checklist:

• Toate pașii agenților sunt înregistrați (versiunea dvs. a „setului domnilor”).
• Pașii sunt legați de un session_id și de un step_id.
• Există o interfață pentru a vizualiza întregul lanț.
• Promptul trimis la LLM poate fi reprodus în orice etapă.

14. Test Before You Ship

Problem:Până în acest moment, cel mai probabil aveți un fel de soluție practic terminată. Funcționează, poate chiar așa cum ați vrut.păstreazăfuncționează? Chiar și după următoarea actualizare minoră?Da, ne conduc la tema testării.

Evident, actualizările în sistemele LLM, la fel ca în orice altceva – fie că este vorba de modificări ale codului aplicației, actualizări ale seturilor de date pentru fine-tuning sau RAG, o nouă versiune a LLM-ului de bază, sau chiar ajustări minore ale instrucțiunilor – conduc adesea la întreruperi involuntare în logica existentă și la comportamente neașteptate, uneori degradante, ale agenților.

• Poate că furnizorul și-a actualizat modelul, poate că natura datelor de intrare sa schimbat (driftul datelor) – ceea ce a funcționat ieri ar putea să nu mai funcționeze astăzi.
• Chiar și o mică schimbare la un prompt poate rupe logica stabilită și denatura rezultatul.
• Non-determinismul LLM-urilor: După cum știți, multe LLM-uri sunt nedeterministe (mai ales cu temperatura > 0), ceea ce înseamnă că vor genera răspunsuri diferite la aceeași intrare la fiecare apel.
• Va fi mai ușor pentru dvs. dacă ați implementat primul principiu, dar reproducerea unei erori specifice pentru debugare poate fi dificilă chiar și cu date și stări fixe.
• În sistemele complexe, actualizarea unui singur element (cum ar fi un model sau o promptă) poate casca printr-un lanț de API-uri, baze de date, instrumente etc. și poate duce la o schimbare a comportamentului în altă parte.
• cu halucinaţii.

Dar înțelegem deja că testele tradiționale, axate pe verificarea logicii explicite a codului, nu sunt pe deplin capabile să acopere aceste probleme.

Solution:Va trebui să elaborăm o abordare complexă și cuprinzătoare care să acopere multe aspecte, combinând soluții clasice și specifice domeniului.

• Testarea pe mai multe niveluri: O combinație de diferite tipuri de teste care vizează diferite aspecte ale sistemului: de la testarea unităților la nivel scăzut pentru funcții individuale și invitații la scenarii complexe care verifică fluxul de lucru de la capăt la capăt al agentului și interacțiunea utilizatorului.
• Accent pe comportamentul și calitatea LLM: Testarea ar trebui să evalueze nu numai corectitudinea funcțională, ci și caracteristicile calitative ale răspunsurilor LLM, cum ar fi relevanța, acuratețea, coerența, absența conținutului dăunător sau părtinitor și aderarea la instrucțiuni și un anumit stil.
• Testele de regresie și de calitate care includ "seturi de date de aur" care conțin exemple de intrare diverse și referințe (sau intervale acceptabile de) de ieșiri.
• Automatizare și integrare în CI/CD.
• Evaluarea umană: Etapele specifice ale LLM-eval ar trebui să includă un om pentru calibrarea metricilor și revizuirea cazurilor complexe sau critice.
• O abordare iterativă a dezvoltării prompte și a testării prompte: Ingineria prompt ar trebui tratată ca un proces iterativ în care fiecare versiune a unui prompt este testată și evaluată temeinic înainte de implementare.
• 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

Acesta este un meta-principiu; rulează prin toate cele enumerate mai sus.

Din fericire, astăzi avem zeci de instrumente și cadre pentru orice sarcină.

Aproape întotdeauna, alegerea unei soluții gata făcute înseamnă otrade-offAi viteză și un start ușor, dar pierziflexibility, control, and, potentially, security.

Acest lucru este deosebit de important în dezvoltarea agenților, unde este important să se gestioneze:

• imprevizibilitatea LLM-urilor
• logică complexă pentru tranziții și auto-corecție,
• să fie pregătit pentru adaptarea și evoluția sistemului, chiar dacă sarcinile sale de bază rămân neschimbate.

Cadrul aduceinversion of control: ei decid pentru tine cum ar trebui să funcționeze agentul. Acest lucru poate simplifica un prototip, dar complică dezvoltarea sa pe termen lung.

Multe dintre principiile descrise mai sus pot fi implementate folosind soluții off-the-shelf – și acest lucru este adesea justificat.explicit implementation of the core logic takes a comparable amount of timeOferă incomparabil mai multtransparency, manageability, and adaptability.

Exista si extrema opusa -over-engineering, dorința de a scrie totul de la zero. Aceasta este, de asemenea, o eroare.

This is why the key is balance.Inginerul alege pentru sine: în cazul în care este rezonabil să se bazeze pe un cadru, și în cazul în care este important să se mențină controlul.

Trebuie să vă amintiți: industria continuă să se formeze.Multe instrumente au fost create înainte de apariția standardelor actuale.Mâine, ele ar putea deveni depășite - dar limitările pe care le-ați gătit astăzi în arhitectura dvs. vor rămâne.

Conclusion

Bine, am trecut peste 15 principii care, arată experiența, ajută la transformarea emoției inițiale a "este în viață!" în încrederea că agentul dvs. LLM va lucra într-un mod stabil, previzibil și util în condiții reale.

Ar trebui să luați în considerare fiecare dintre ele pentru a vedea dacă are sens să o aplicați proiectului dvs. În cele din urmă, este proiectul dvs., sarcina dvs. și creația dvs.

Key takeaways to carry with you:

1. O abordare de inginerie este cheia: Nu vă bazați pe "magia" LLM-urilor. structura, predictibilitatea, gestionarea și testarea sunt cei mai buni prieteni.
2. LLM este o componentă puternică, dar totuși doar o componentă: Tratați LLM ca o componentă foarte inteligentă, dar totuși unică a sistemului dumneavoastră.
3. Iterarea și feedback-ul sunt cheile succesului: Este rar să creați agentul perfect la prima încercare. fiți pregătiți pentru experimente, măsurători, analiza erorilor și îmbunătățirea continuă - atât a agentului în sine, cât și a proceselor de dezvoltare.
4. Comunitate și deschidere: Domeniul agenților LLM evoluează rapid. Păstrați un ochi pe noi cercetări, instrumente și cele mai bune practici și împărtășiți-vă propriile experiențe.

Sper că ați găsit ceva nou și util aici, și poate veți dori chiar să reveniți la acest lucru în timp ce proiectați următorul agent.