Lopeta kehotus, aloita suunnittelu: 15 periaatetta AI-agenttisi tuottamiseksi tuotantoon

Introduction

Aluksi yrität vain kommunikoida ChatGPT: n kanssa API: n kautta, heittää pari riviä kontekstiin ja hämmästyttää, että se reagoi ollenkaan.

Näin agentti syntyy.

Jos olet myös viettänyt viimeisen vuoden kopioimalla agentteja käsikirjoituksista ja pakkauksista, kokeilemalla ja tinkering, ja etsit edelleen puhtaampaa, kestävämpää tapaa rakentaa niitä - tämä artikkeli on sinulle. olen vaeltanut repoja ja foorumeita, toistuvasti kysyen itseltäni: "Miten muut tekevät sen?" > Pidin kiinni - mitä todella tuntui heti todellisen käytön jälkeen, ja vähitellen tislattu joukko ydinperiaatteita viileän idean muuttamiseksi tuotantopäälliseksi ratkaisuksi.

Ajattele sitä käytännöllisenä huijauslehtinä - kokoelma tekniikan periaatteita, jotka auttavat ohjaamaan agenttia hiekkalaatikosta tuotantoon: yksinkertaisesta API-pakkauksesta vakaaseen, hallittavaan ja skaalautuvaan järjestelmään.

Disclaimer

jaTämä artikkeli(Tehokkaiden agenttien rakentaminen) Anthropic määrittelee agentin järjestelmäksi, jossa LLM: t ohjaavat dynaamisesti omia prosessejaan ja työkalujen käyttöä säilyttäen hallinnan siitä, miten he suorittavat tehtäviä.

Tässä tekstissä agentti = agenttijärjestelmä, jossa vakauden ja valvonnan vuoksi luotan useammin työnkulkuihin.Toivon, että lähitulevaisuudessa on vielä 1-2 kierrosta evoluutiossa ja todelliset agentit ovat kaikkialla, mutta tällä hetkellä näin ei ole

1. Design the Foundation

Varhaiset versiot agenteista tulevat yleensä yhteen nopeasti: muutama toiminto, pari kehotusta - ja hei, se toimii.

Varhaiset versiot agenteista tulevat yleensä yhteen nopeasti: muutama toiminto, pari kehotusta - ja hei, se toimii.

“If it works, why make it complicated?”

Alussa kaikkiNäyttääAgentti reagoi, suorittaa koodia, käyttäytyy järkevästi.Mutta kun vaihdat mallia, käynnistät järjestelmän uudelleen tai kytket uuden rajapinnan - yhtäkkiä siitä tulee epävakaa, arvaamaton, vaikea korjata.

Ja usein perimmäinen syy ei ole logiikassa tai kehotuksissa, vaan paljon aikaisemmin: rikki muistin hallinta, kovakoodattu henkilökunta, ei tapa jatkaa istuntoja tai yksi jäykkä sisäänkäyntipiste.

Tässä osiossa käydään läpi neljä keskeistä periaatetta, jotka auttavat sinua rakentamaan vankan perustan - sellaisen, jonka päälle kaikki muu voi turvallisesti kasvaa.

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. Toistettavuus on rajoitettua. Tarvitset tavan toistaa tarkasti, mitä tapahtui - testaamiseen, hävittämiseen ja muihin tällaisiin nautintoihin.

Tämä ei ole tiukasti ongelma, mutta silti:

3. Ehkä se tarvitsee vertailla useita vaihtoehtoja keskellä vuoropuhelua (“Mikä näistä on parempi?”).

(Muisti on täysin erillinen asia - pääsemme siihen pian)

Solution:Liikkuva valtiooutsideagentti - tietokantaan, välimuistiin, tallennuskerrokseen - jopa JSON-tiedosto tekee.

Checklist:

• Agentti voidaan käynnistää mistä tahansa vaiheesta, sillä on vain session_id – istunnon tunniste – ja ulkoinen tila (esimerkiksi tallennetut vaiheet tietokantaan tai JSON-tiedostoon).
• Testitapaus: keskeytetty agentti ei menetä kontekstia, uudelleenkäynnistyksen jälkeen tulos on sama
• Valtio on serialisoitavissa milloin tahansa menettämättä toiminnallisuutta
• Voit syöttää tilan useisiin samanaikaisiin tapauksiin vuoropuhelun keskellä

2. Make Knowledge External

Problem: LLM: t eivät muista. Jopa yhden istunnon sisällä malli voi unohtaa, mitä olet jo selittänyt, sekoittaa vaiheita, menettää keskustelun lankaa tai alkaa "täyttää" yksityiskohtia, joita ei ollut siellä. Ja näyttää siltä, että aika kuluu, kontekstiikkuna kasvaa suuremmaksi ja suuremmaksi, ilahduttaen meitä uusilla mahdollisuuksilla. LinkedIn on täynnä viestejä, joissa ihmiset vertaavat, mikä kirja tai kuinka monta tuntia YouTube-videota sopii nyt uuteen malliversioon.

Erityisesti jos:

• Vuoropuhelu on pitkä
• Asiakirjat ovat laajoja
• Ohjeet ovat monimutkaisia
• ja tokenit eivät ole vielä loputtomia

Jopa kasvavien kontekstiikkunoiden (8k, 16k, 128k...), ongelmat pysyvät:

• "Kadonnut keskellä" - malli kiinnittää enemmän huomiota alkuun ja loppuun (ja voi irrottaa yksityiskohtia keskeltä)
• Kustannukset - enemmän tokeneja = enemmän rahaa;
• Ja se ei vieläkään sovi. mikä tarkoittaa, että menetys, vääristyminen tai hallusinaatiot tapahtuvat. Niin kauan kuin muuntajat työskentelevät itsetuntemuksella neliön monimutkaisuudella (O(n2)), tämä rajoitus on kanssamme.

Solution:Erillinen "työmuisti" ja "varastointi" - kuten klassisissa tietojenkäsittelyjärjestelmissä. Agentin pitäisi pystyä työskentelemään ulkoisen muistin kanssa: tallentaa, hakea, tiivistää ja päivittää tietoa mallin ulkopuolella.

Approaches

Memory Buffer

Viimeisimmät kaupatkTutustu nopeisiin prototyyppeihin.

+helppo, nopea, riittävä lyhyisiin tehtäviin

-menettää tärkeitä tietoja, ei skaalaudu, ei muista "eilen"

Summarization Memory

Tiivistää historiaa, jotta se sopii enemmän.

+Token säästöt, muistin laajentaminen

-vääristymät, vivahteiden menetys, virheet monivaiheisessa puristuksessa

RAG (Retrieval-Augmented Generation)

Vedä tietoa ulkoisista tietokannoista. Useimmiten olet täällä.

+värikkäitä, tarkistettavissa olevia

-monimutkainen asennus, herkkä palautuksen laatuun, viive

Knowledge Graphs

Aina tyylikäs, seksikäs ja kova, päädyt tekemään RAG joka tapauksessa.

+Logiikka, selittävyys ja vakaus

-korkea este pääsyyn, monimutkaisuus LLM integraatio

Checklist:

• Kaikki keskusteluhistoria on käytettävissä yhdessä paikassa (puhelun ulkopuolella)
• Tietolähteet tallennetaan ja niitä voidaan käyttää uudelleen
• Historian asteikot ilman riskiä ylittää kontekstiikkuna

3. Model as a Config

Problem:LLM: t kehittyvät nopeasti; Google, Anthropic, OpenAI jne. Julkaisevat jatkuvasti päivityksiä, kilpailevat toisiaan vastaan eri vertailuarvoissa. Tämä on juhla meille insinööreinä, ja haluamme hyödyntää sitä. agenttimme pitäisi pystyä helposti vaihtamaan parempaan (tai päinvastoin halvempaan) malliin saumattomasti.

Solution:

1. Implemente model_id configuration: Käytä model_id-parametria konfigurointitiedostoissa tai ympäristömuuttujissa määrittääksesi käytettävän mallin.
2. Käytä abstrakteja rajapintoja: Luo rajapintoja tai kääreitä, jotka ovat vuorovaikutuksessa mallien kanssa yhtenäisen API:n kautta.
3. Käytä middleware-ratkaisuja (varovaisesti - puhumme kehyksistä hieman myöhemmin)

Checklist:

• Mallien korvaaminen ei vaikuta muuhun koodiin eikä vaikuta agenttien toimintaan, orkestrointiin, muistiin tai työkaluihin.
• Uuden mallin lisääminen edellyttää vain konfiguraatiota ja valinnaisesti adapteria (yksinkertainen kerros, joka tuo uuden mallin vaadittuun käyttöliittymään)
• Voit helposti ja nopeasti vaihtaa malleja. Ihannetapauksessa - kaikki mallit, vähintään - vaihtaa malliperheen sisällä

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

Problem:Vaikka alun perin agentilla olisi tarkoitus olla vain yksi viestintäliittymä (esimerkiksi käyttöliittymä), haluat lopulta antaa käyttäjille enemmän joustavuutta ja mukavuutta lisäämällä vuorovaikutusta Slackin, WhatsAppin tai, uskallan sanoa sen, SMS: n kautta - mitä tahansa. API voi muuttua CLI: ksi (tai haluat yhden vianmääritykseen). Rakenna tämä suunnitteluun alusta alkaen; voit käyttää agenttiasi missä tahansa se on kätevä.

Solution: Creating a unified input contract: Kehitä API tai muu mekanismi, joka toimii yleismaailmallisena käyttöliittymänä kaikille kanaville.

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

  
  

  

  
  

2. Määrittele agenttien käyttäytyminen

Vaikka on vain yksi tehtävä, kaikki on yksinkertaista, kuten AI-evangelistien viesteissä.Mutta heti kun lisäät työkaluja, päätöksenteon logiikkaa ja useita vaiheita, agentti muuttuu sotkuiseksi.

Vaikka on vain yksi tehtävä, kaikki on yksinkertaista, kuten AI-evangelistien viesteissä.Mutta heti kun lisäät työkaluja, päätöksenteon logiikkaa ja useita vaiheita, agentti muuttuu sotkuiseksi.

Se menettää jälkensä, ei tiedä, mitä tehdä virheillä, unohtaa soittaa oikealle työkalulle - ja olet jäljellä yksin jälleen lokeilla, joissa "no, kaikki näyttää olevan kirjoitettu sinne."

Tämän välttämiseksi työntekijä tarvitsee selkeänbehavioral modelMitä se tekee, mitä työkaluja sillä on, kuka tekee päätöksiä, miten ihmiset puuttuvat ja mitä tehdä, kun jokin menee pieleen.

Tässä osiossa käsitellään periaatteita, jotka auttavat sinua antamaan agentillesi johdonmukaisen toimintastrategian sen sijaan, että toivoisi "mallin selvittävän sen jotenkin".

5. Design for Tool Use

Problem:Tämä kohta saattaa tuntua ilmeiseltä, mutta kohtaat edelleen agentteja, jotka on rakennettu "Plain Prompting + raaka LLM-tulostuksen analysointiin." Se on kuin yrittää hallita monimutkaista mekanismia vetämällä satunnaisia merkkijonoja ja toivomalla parasta.

• Brittleness: Pienin muutos LLM vastaus sanamuoto (sana lisätty, lauseen järjestys muuttui) voi rikkoa koko parsing.
• Epäselvyys: Luonnollinen kieli on luonnostaan epäselvä. Mikä ihmiselle tuntuu ilmeiseltä, voi olla palapeli analyytikolle. ”Soita John Smithille” – kumpi kolmesta John Smithistä tietokannassasi?
• Huollon monimutkaisuus: Parsing-koodi kasvaa, muuttuu hämmentyneeksi ja vaikeaksi korjata. Jokainen uusi agentti "taito" vaatii kirjoittamaan uusia parsing-sääntöjä.
• Rajoitetut ominaisuudet: On vaikea tehdä mallista luotettavasti useita työkaluja tai siirtää monimutkaisia tietorakenteita yksinkertaisen tekstin tulostuksen kautta.

Solution:Malli palauttaa JSON:n (tai muun jäsennellyn muodon) – järjestelmä suorittaa.

Tärkein ajatus tässä on jättää vastuutatulkitseminenKäyttäjän tarkoitus jaValitsetyökaluja LLM: lle, samalla kun määrätäänteloitusTästä pyrkimyksestä kohtiJärjestelmäselkeästi määritellyn käyttöliittymän kautta.

Onneksi lähes kaikki palveluntarjoajat (OpenAI, Google, Anthropic tai kuka tahansa muu haluat) tukevat ns."function calling"tai kyky tuottaa tulosta tiukasti määritellyssä JSON-muodossa.

Jäädä miettimään, miten tämä toimii:

1. Työkalun kuvaus: Määrität toiminnot (työkalut) nimellä JSON Schema, jossa on nimi, kuvaus, parametrit.
2. Siirtyminen LLM:iin: Kussakin puhelussa malli vastaanottaa työkalujärjestelmiä yhdessä kehotuksen kanssa.
3. Model output: Instead of text, the model returns JSON with:
   • name of the function to call
   • arguments—parameters according to schema
4. Täytäntöönpano: Koodi validoi JSON:n ja kutsuu sopivan toiminnon parametreilla.
5. Malli vastaus (valinnainen): Täytäntöönpanon tulos siirretään takaisin LLM: lle lopullisen vastauksen tuottamiseksi.

Important:Työkalun kuvaukset ovat myös kehotuksia. epäselvä kuvaus = virheellinen toiminto valinta.

What to do without function calling?

If the model doesn't support tool calls or you want to avoid them for some reason:

• Pyydä mallia palauttamaan JSON-muodossa. Varmista, että määrität muodon; voit lisätä esimerkkejä.
• Parse the response and validate it with something like Pydantic. There are real fans of this approach.

Checklist:

• Vastaus on tiukasti muodollistettu (esim. JSON)
• Käytetään kaavioita (JSON Schema tai Pydantic)
• Validointi suoritetaan ennen funktioiden soittamista
• Tuotantovirheet eivät aiheuta rikkoutumista (formaattivirheiden käsittely on olemassa)
• LLM = toiminnon valinta, toteutus = koodi

6. Own the Control Flow

Problem: Usually agents work as "dialogues"—first the user speaks, then the agent responds. It's like playing ping-pong: hit-response. Convenient, but limiting.

Such an agent cannot:

• Tee jotain itse ilman pyyntöä
• Toimii rinnakkain
• Suunnittele askeleet etukäteen
• Tee useita vaiheita peräkkäin
• Tarkista edistyminen ja palaa epäonnistuneisiin vaiheisiin

Sen sijaan agentin pitäisi hallita omaa "toimeenpanovirtaa" - päättää, mitä tehdä seuraavaksi ja miten se tehdään.

This means the agent:

• päättää, milloin tehdä jotain itse
• voi ottaa askeleita yksi toisensa jälkeen
• Epäonnistuneita askelia voi palauttaa
• Voit vaihtaa tehtävien välillä
• can work even without direct requests

Solution:Sen sijaan, että annamme LLM: n hallita kaikkea logiikkaa, otamme poiscontrol flowmalli auttaa vain vaiheissa tai ehdottaa seuraavaa. Tämä on siirtyminen "kirjoittamisesta"engineering a systemja kontrolloitua käyttäytymistä.

Katsotaanpa kolmea suosittua lähestymistapaa:

1. FSM (Finite State Machines)

• Mitä se on: Tehtävä jaettu valtioihin ja selkeisiin siirtymiin.
• LLM: Määrittää seuraavan vaiheen tai toimii valtion sisällä.
• Edut: Yksinkertaisuus, ennustettavuus, hyvä lineaarisiin skenaarioihin.
• Työkalut: StateFlow, YAML konfiguraatiot, Valtion malli.

2. DAG (Directed Graphs)

• Mitä se on: Ei-lineaariset tai rinnakkaiset tehtävät kaaviona: solmut ovat toimia, reunat ovat riippuvuuksia.
• LLM: Voi olla solmu tai auttaa suunnitelman rakentamisessa.
• Hyödyt: Joustavuus, rinnakkaisuus ja visualisointi.
• Tools: LangGraph, Trellis, LLMCompiler, custom DAG diagrams.

3. Planner + Executor

• Mitä se on: LLM rakentaa suunnitelman, koodin tai muiden agenttien toteuttaa sen.
• LLM: "Suuri" yksi suunnitelmia, "pieni" ne toteuttaa.
• Edut: Huolenaiheiden erottaminen, kustannusten hallinta, skaalautuvuus.
• Työkalut: LangChain Plan-and-Execute

Why this matters:

• Parantaa hallittavuutta, luotettavuutta ja skaalautuvuutta.
• Mahdollistaa eri mallien yhdistämisen ja nopeuttaa toteuttamista.
• Työnkulku muuttuu visualisoitavaksi ja testattavaksi.

Checklist:

• Käyttää FSM:tä, DAG:tä tai skenaariota, jossa on selkeät siirtymät
• Malli päättää, mitä tehdä, mutta ei hallitse virtausta
• Käyttäytymistä voidaan visualisoida ja testata
• Error handling is built into the flow

7. Include the Human in the Loop

Problem:Vaikka agentti käyttää jäsenneltyjä työkaluja ja sillä on selkeä hallintavirta, LLM-agenttien täysi itsenäisyys todellisessa maailmassa on edelleen enemmän unelma (tai painajainen, riippuen asiayhteydestä). LLM: llä ei ole todellista ymmärrystä eikä heitä ole vastuussa mistään.

Main risks of full autonomy:

• Pysyvät virheet: Agentti voi suorittaa toimia, joilla on vakavia seurauksia (tietojen poistaminen, virheellisen viestin lähettäminen tärkeälle asiakkaalle, robottien kapinan käynnistäminen).
• Vaatimustenmukaisuusrikkomukset: Agentti saattaa vahingossa rikkoa sisäisiä säännöksiä, lakisääteisiä vaatimuksia tai vahingoittaa käyttäjän tunteita (jos se ei ollut suunnitelma, jätä tämä kohta huomiotta).
• Lack of common sense and ethics: LLMs might miss social nuances or act against "common sense."
• Käyttäjien luottamuksen menetys: Jos agentti tekee usein virheitä, käyttäjät lakkaavat luottamasta siihen.
• Audit and accountability complexity: Who's to blame when an autonomous agent "screws up"?

Solution: Hiilipohjaisten elämänmuotojen strateginen kutsuminenIntegroida ihmiset päätöksentekoprosessiin keskeisissä vaiheissa.

HITL Implementation Options

1. Approval Flow

• Milloin: toiminta on kriittistä, kallista, peruuttamatonta
• Miten: agentti laatii ehdotuksen ja odottaa vahvistusta

2. Confidence-aware Routing

• Milloin: malli on epävarma
• How:
  • self-assessment (logits, LLM-as-a-judge, P(IK))
  • escalation when confidence falls below threshold

3. Human-as-a-Tool

• Milloin: riittämättömät tiedot tai epäselvä pyynnön muotoilu
• Miten: agentti pyytää selvennystä (esim. HumanTool in CrewAI)

4. Fallback Escalation

• When: repeated error or unresolvable situation
• Miten: Tehtävä siirretään kontekstissa olevaan operaattoriin

5. RLHF (Human Feedback)

• When: for model improvement
• Miten: ihminen arvioi vastauksia, he menevät koulutukseen

Checklist:

• Hyväksyntää vaativat toimenpiteet määritellään
• On olemassa mekanismi luottamuksen arviointiin
• Agentti voi esittää ihmisten kysymyksiä
• Kriittiset toimet vaativat vahvistusta
• On olemassa käyttöliittymä vastausten syöttämiseen

8. Compact Errors into Context

Problem:Monien järjestelmien vakiokäyttäytyminen, kun virhe ilmenee, on joko "onnettomuus" tai yksinkertaisesti virheen ilmoittaminen ja pysäyttäminen. Agentille, joka pitäisi ratkaista tehtäviä itsenäisesti, tämä ei ole juuri paras käyttäytymismalli.

Mitä me kohtaamme:

• Hauraus: Mikä tahansa ulkoisen työkalun epäonnistuminen tai odottamaton LLM-vaste voi pysäyttää koko prosessin tai johtaa siihen harhaan.
• Tehottomuus: Jatkuva uudelleenkäynnistys ja manuaalinen toimenpide kuluttavat aikaa ja resursseja.
• Kyvyttömyys oppia (laajassa merkityksessä): Jos agentti ei "näe" virheitään kontekstissa, hän ei voi yrittää korjata niitä tai mukauttaa käyttäytymistään.
• Hallucinations. Again.

Solution:Virheet sisältyvät kehotukseen tai muistiin. Ajatuksena on yrittää toteuttaa jonkinlainen "itsensä parantaminen". Agentin pitäisi ainakin yrittää korjata käyttäytymisensä ja sopeutua.

Kovaa virtausta :

• Virheen ymmärtäminen
• 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.
• Pyydä ihmisen apua: Jos itsekorjaus epäonnistuu, tekijä kiihdyttää ongelmaa ihmiselle (ks. periaate 7).

Checklist:

• Edellisen vaiheen virhe tallennetaan kontekstiin
• Logiikka on olemassa
• Fallback/Human escalation käytetään toistuviin epäonnistumisiin

9. Break Complexity into Agents

Problem:Palataan keskeiseen LLM: n rajoittamiseen (tämä kontekstiikkuna asia), mutta tarkastellaan tätä ongelmaa eri näkökulmasta. Mitä suurempi ja monimutkaisempi tehtävä, sitä enemmän vaiheita se vie, mikä tarkoittaa pidempää kontekstiikkunaa. Kun konteksti kasvaa, LLM: t todennäköisemmin menettävät tai menettävät keskittymisensä. Keskittymällä agentteihin tietyillä verkkotunnuksilla 3-10, ehkä enintään 20 askelta, ylläpidetään hallittavissa olevia kontekstiikkunoita ja korkeaa LLM: n suorituskykyä.

Solution:Käytä pienempiä toimijoita, jotka kohdistuvat tiettyihin tehtäviin. Yksi agentti = yksi tehtävä; ylemmältä suunnittelu.

Pienten, keskittyneiden agenttien edut:

• Hallittavissa oleva konteksti: Pienemmät kontekstiikkunat tarkoittavat parempaa LLM: n suorituskykyä
• Selkeät vastuut: Jokaisella toimijalla on hyvin määritelty soveltamisala ja tarkoitus
• Parempi luotettavuus: vähemmän mahdollisuuksia eksyä monimutkaisissa työnkulkuissa
• Yksinkertaisempi testaus: Yksinkertaisempi testata ja validoida tiettyjä toimintoja
• Parannettu vianmääritys: Ongelmia on helpompi tunnistaa ja korjata, kun ne ilmenevät

Valitettavasti ei ole selkeää heuristiikkaa ymmärtääkseen, milloin logiikka on jo tarpeeksi suuri jakautumaan useisiin agentteihin. Olen varma, että kun luet tätä tekstiä, LLM: t ovat saaneet älykkäämpiä jossain laboratoriossa. Ja ne ovat yhä parempia ja parempia, joten jokainen yritys muodollistaa tämä raja on tuomittu alusta alkaen. Kyllä, mitä pienempi tehtävä, sitä yksinkertaisempi se on, mutta mitä suurempi se saa, sitä parempi potentiaali toteutetaan. Oikea intuitio tulee vain kokemuksella.

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.

  
  

  

  
  

3. Hallintamallin vuorovaikutus

Malli käsittelee sukupolvia.Kaikki muu on sinun.

Malli käsittelee sukupolvia.Kaikki muu on sinun.

Miten olet muotoillut pyynnön, mitä olet antanut kontekstissa, mitä ohjeita olet antanut - kaikki tämä määrittää, onko tulos johdonmukainen tai "luova".

LLM: t eivät lue mieltä, he lukevat tokeneja.

Mikä tarkoittaa, että jokainen syöttövirhe muuttuu tulostusvirheksi – ei vain heti havaittavissa.

Tässä osassa on kyse siitä, että kaikki ei liiku: kehotukset = koodi, nimenomainen kontekstinhallinta, rajoittamalla mallia rajojen sisällä.

10. Treat Prompts as Code

Problem:Erittäin yleinen malli, varsinkin ihmisten keskuudessa, joilla ei ole ML- tai SE-taustaa, tallentaa kehotuksia suoraan koodiin tai parhaimmillaan epäjärjestelmälliseen tallentamiseen ulkoisiin tiedostoihin.

Tämä lähestymistapa johtaa useisiin ylläpito- ja skaalausvaikeuksiin:

• Navigointi, ymmärtäminen ja muokkaaminen monimutkaistuvat projektin monimutkaisuuden ja kehotusten määrän kasvaessa.
• Ilman nimenomaista versiointia on hyvin vaikea seurata nopeaa kehitystä, muutosten syitä ja siirtyä takaisin aiempiin vakaisiin versioihin suorituskyvyn heikkenemisen tapauksessa.
• Tehoton parannus- ja korjausprosessi: Nopea optimointi ilman objektiivisia mittareita ja testausta muuttuu subjektiiviseksi ja työvoimavaltaiseksi prosessiksi, jossa tulokset ovat epävakaat.
• Muiden tiimin jäsenten havaitseminen muuttuu monimutkaiseksi, mukaan lukien (ja erityisesti) tulevaisuuden sinä.

Solution:Promptit tässä yhteydessä eivät eroa paljon koodista ja niihin olisi sovellettava samoja perusteknisiä käytäntöjä.

This implies:

• Tallenna erikseen ja järjestelmällisesti käyttämällä erikoistuneita tiedostoja (kuten .txt, .md, .yaml, .json) tai jopa mallinhallintajärjestelmiä (kuten Jinja2, Handlebars tai erikoistuneet työkalut kuten BAML).
• Voit jopa tehdä A/B-testejä eri versioilla tämän jälkeen.
• 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.

Puhumme testauksesta tarkemmin periaatteessa 14.

Checklist:

• Promptit tallennetaan erillisiin tiedostoihin, erillään liiketoiminnan logiikasta
• On diff ja muuttaa historiaa
• Testit käytetään (tarvittaessa)
• (Valinnainen) Entä nopea tarkistus osana koodin tarkastelua?

11.Kontekstitekniikka

Problem:Olemme jo keskustelleet LLM: n "unohdettavuudesta", osittain ratkaisemalla tämä poistamalla historian ulkoiseen muistiin ja käyttämällä eri agentteja eri tehtäviin.Mutta se ei ole kaikki. ehdotan, että harkitsemme myös nimenomaista kontekstiikkunan hallintaa (ja tässä en puhu vain historian puristamisesta sopivaksi optimaaliseen kokoon tai edellisten vaiheiden virheiden sisällyttämisestä kontekstiin).

Standard formats aren't always optimal:Yksinkertainen luettelo viesteistä roolipohjaisessa sisällössä (system/user/assistant) muoto on lähtökohta, mutta se voi olla raskas, ei riittävän informatiivinen tai huono välittää agenttisi monimutkaista tilaa.

Useimmat LLM-asiakkaat käyttävät vakiotiedostomuotoa (luettelo kohteista, joissa onrole• ”järjestelmä”, ”käyttäjä”, ”avustaja”,contentJa joskustool_callsja kentät)

Vaikka tämä "toimii erinomaisesti useimmissa tapauksissa",maximum efficiency(sekä tokenien että mallin huomion osalta) voimme lähestyä kontekstin muodostumista luovemmin.

Solution:Käsittelemään koko LLM: lle toimitetun tietopaketin luomista"Context Engineering."Tämä tarkoittaa:

1. Täydellinen valvonta: Ota täysi omistajuus siitä, mitä tietoja tulee LLM: n kontekstiikkunassa, missä muodossa, volyymissa ja järjestyksessä.
2. Mukautettujen muotojen luominen: Emme rajoita itseämme tavanomaisiin viestiluetteloihin. Kehitämme omia, tehtäviin optimoituja tapoja edustaa kontekstia. Voit esimerkiksi harkita XML-tyyppisen rakenteen käyttämistä erilaisten tietojen (viestit, työkalukutsut, niiden tulokset, virheet jne.) tiheään pakkaamiseen yhteen tai useampaan viestiin.
3. Kokonaisvaltainen lähestymistapa: konteksti ei ole pelkästään dialogihistoria, vaan kaiken, mitä malli tarvitsee: välittömät ohjeet, ohjeet, tiedot RAG-järjestelmistä, työkalukutsujen historia, agentin tila, muisti muista vuorovaikutuksista ja jopa ohjeet halutusta tulostusmuodosta.

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

Jos olet kiinnostunut jostakin seuraavista:

• Maksimaalinen merkitys minimaalisella melulla.
• Kustannustehokkuus. Vähentämällä tokenien määrää, jossa voimme saada vertailukelpoisen laadun alhaisemmalla hinnalla.
• Parannettu virheiden käsittely.
• Turvallisuus. käsittelee arkaluonteisten tietojen sisällyttämistä, ohjaa sitä, suodattaa sitä ja lopettaa kaiken antamalla klassisen " Anteeksi, olen vain pieni iso kielen malli" vastaus.

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

Problem:Olemme jo tehneet paljon vakauden nimissä, mutta mikään ei ole hopeaa.Tämä tarkoittaa, että on syytä tarkastella kriittisimpiä mahdollisia ongelmia erikseen ja nimenomaisesti ottaa joitakin "vakuutuksia".

Tässä periaatteessa ajattelemme:

• Mahdollinen Prompt Injection. Jos agentti kommunikoi suoraan käyttäjän kanssa, sinun on valvottava, mitä syötetään syötteenä. Käyttäjän tyypistä riippuen saatat saada sellaisen, joka haluaa rikkoa virtauksen ja pakottaa agentin sivuuttamaan alkuperäiset tavoitteensa, antamaan väärän tiedon, suorittamaan haitallisia toimia tai tuottamaan haitallista sisältöä.
• Arkaluonteisten tietojen vuotaminen. edellä mainituista syistä tai "päässä olevien äänien" johdolla agentti voi paljastaa tärkeitä tietoja, kuten käyttäjien henkilötietoja, yritys salaisuuksia jne.
• Myrkyllisen tai haitallisen sisällön tuottaminen.Jos tämä on suunnittelun mukaan, jätä tämä asia huomiotta.
• Asioiden luominen, kun tietoa ei ole.Iankaikkinen kipu.
• Menossa sallittujen rajojen ulkopuolelle. Koneiden nousu, muistakaa? Mutta vakavasti, sen päättelyn prosessissa, agentti voi saavuttaa hyvin ei-triviaalisia ratkaisuja, joista kaikki eivät ole normaalin käyttäytymisen rajoissa.

LLM-agentin turvallisuus ja maadoitus eivät ole yksi toimenpide, vaan monikerroksinen suojelujärjestelmä ("puolustus syvällä"), joka kattaa koko vuorovaikutuksen elinkaaren. Uhkat ovat moninaisia, eikä yksittäinen suojausmenetelmä ole parannuskeino. Tehokas suojaus edellyttää tekniikoiden yhdistelmää.

Solution:Meidän on sitouduttava monikerroksiseen puolustusjärjestelmään, harkittava ja käsiteltävä selkeästi kaikkia kulmakysymyksiä ja mahdollisia skenaarioita, ja oltava selkeä vastaus valmiina mihin tahansa.

Perusasetuksessa sinun pitäisi harkita:

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).

Lopullinen järjestelmä riippuu kuitenkin tehtävistäsi ja riskinarvioinnistasi.

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

Agentti, joka "kinda toimii" on vika, jolla on viivästynyt vaikutus.

Agentti, joka "kinda toimii" on vika, jolla on viivästynyt vaikutus.

Kaikkea ei tapahdu kerralla, ja et saa siitä heti selvää, joskus et edes tiedä.

Tämä artikkeli käsittelee insinöörien tapojaseeing what's happeningjachecking that everything is still workingPäiväkirjat, seuranta, testit - kaikki, mikä tekee agentin käyttäytymisestä läpinäkyvän ja luotettavan, jopa nukkuessasi tai kehittäessäsi seuraavaa agenttia.

13. Trace Everything

Problem:Yhdellä tai toisella tavalla kohtaat jatkuvasti tilanteita, joissa agentti ei toimi odotetulla tavalla. Kehityksen, testauksen, muutosten tekemisen tai normaalin toiminnan aikana. Tämä on väistämätöntä, ja tällä hetkellä se on normaalia jossain määrin. Tämä tarkoittaa, että olet tuomittu viettämään tunteja ja päiviä hävittämisessä, yrittää ymmärtää, mikä on väärin, toistaa ongelma ja korjata se. Haluaisin ajatella, että tähän pisteeseen mennessä olet jo toteuttanut periaatteen #1 (Keep State Outside) ja #8 (Compact Erors in Context). Useimmissa tapauksissa se riittää tekemään elämästäsi paljon helpompaa.

Jopa niin (ja varsinkin jos olet päättänyt olla häiritsemättä niitä nyt), on järkevää ajatella debugging etukäteen ja säästää aikaa ja hermoja tulevaisuudessa noudattamalla tätä periaatetta.

Solution:Kirjaa koko polku pyynnöstä toimeen. Vaikka sinulla olisi jo yksittäisten komponenttien lokit, koko ketjun jäljittäminen voi olla hankala. Vaikka olet suuri palapelin tai Lego-fan, jossain vaiheessa se lakkaa olemasta hauskaa.

Why it's needed:

• Debugging – Etsi nopeasti, missä asiat menivät pieleen.
• Analyysi – Katso, missä pullonkaulat ovat ja miten niitä voidaan parantaa.
• Laadun arviointi – Katso, miten muutokset vaikuttavat käyttäytymiseen.
• Toistettavuus – Voit rekonstruoida vaiheet tarkasti.
• Auditointi – kaikkien agenttien päätösten ja toimien loki.

Perus "herrasmiehen setti" näyttää tältä:

• Sisääntulo: Alkuperäinen käyttäjän pyyntö, edellisestä vaiheesta saadut parametrit.
• Agentin tila: Agentin keskeiset tilan muuttujat ennen vaiheen suorittamista.
• Prompt: LLM: lle lähetetyn pyynnön koko teksti, mukaan lukien järjestelmäohjeet, vuoropuheluhistoria, haettu RAG-konteksti, työkalujen kuvaukset jne.
• LLM Output: Täydellinen, raaka vastaus LLM: stä ennen analyysia tai käsittelyä.
• Työkalukutsu: Jos LLM päätti soittaa työkalulle – työkalun nimi ja tarkat parametrit, joilla se kutsuttiin (rakennetun tuotoksen mukaan).
• Työkalun tulos: Työkalun palauttama vastaus, mukaan lukien sekä onnistuneet tulokset että virheilmoitukset.
• Agentin päätös: Mitä päätöstä agentti teki LLM: n vastauksen tai työkalun tuloksen perusteella (esim. mitä seuraavaa vaihetta suorittaa, mitä vastausta antaa käyttäjälle).
• Metatiedot: Vaiheen suorittamisen aika, käytetty LLM-malli, puhelun kustannukset (jos saatavilla), koodi / prompt-versio.

Note:Tarkastele olemassa olevia seurantatyökaluja; tietyissä olosuhteissa ne tekevät elämästäsi paljon helpompaa. LangSmith esimerkiksi tarjoaa yksityiskohtaisen visualisoinnin soittoketjuista, kehotuksista, vastauksista ja työkalujen käytöstä. Voit myös mukauttaa työkaluja, kuten Arize, Painot ja ennakkoluulot, OpenTelemetry jne. tarpeisiisi.

Checklist:

• Kaikki agentin vaiheet on kirjattu (asiakkaan versio).
• Vaiheet on yhdistetty session_id ja step_id.
• On olemassa käyttöliittymä nähdä koko ketjun.
• LLM: lle lähetetty pyyntö voidaan toistaa missä tahansa vaiheessa.

14. Test Before You Ship

Problem:Tähän pisteeseen mennessä sinulla on todennäköisesti jonkinlainen käytännössä valmis ratkaisu. Se toimii, ehkä jopa vain haluamallasi tavalla.PidäToimiiko? Jopa seuraavan pienen päivityksen jälkeen? Kyllä, johdan meidät testauksen aiheeseen.

Ilmeisesti päivitykset LLM-järjestelmissä, aivan kuten kaikissa muissa - olipa kyseessä sitten muutokset sovelluskoodissa, päivitykset tietokokonaisuuksiin hienosäätöä tai RAG: tä varten, uusi versio perus LLM: stä tai jopa vähäiset kehotussäädökset - johtavat usein tahattomiin loukkauksiin olemassa olevassa logiikassa ja odottamattomaan, joskus heikentävään agenttien käyttäytymiseen. Perinteiset ohjelmistotestausmenetelmät osoittautuvat riittämättömiksi LLM-järjestelmien kattavaan laadunvalvontaan.

• Et ole tehnyt mitään, mutta suorituskyky on laskenut ajan myötä. Ehkä palveluntarjoaja on päivittänyt mallinsa, ehkä syöttötietojen luonne on muuttunut (tietojen siirtyminen) - se, mikä toimi eilen, saattaa lakata toimimasta tänään.
• Jopa pieni muutos kyselyyn voi rikkoa vakiintuneen logiikan ja vääristää tulosta.
• LLM: n ei-determinismi: Kuten tiedätte, monet LLM: t ovat ei-deterministisia (varsinkin lämpötilassa > 0), mikä tarkoittaa, että ne tuottavat eri vastauksia samaan syöttöön jokaisessa puhelussa.
• On helpompaa, jos olet ottanut käyttöön ensimmäisen periaatteen, mutta tietyn virheen toistaminen debuggausta varten voi olla vaikeaa jopa kiinteiden tietojen ja tilojen kanssa.
• Monimutkaisissa järjestelmissä yhden elementin (kuten mallin tai viestin) päivittäminen voi kaskadoida API-rajapintojen, tietokantojen, työkalujen jne. Ketjun läpi ja johtaa käyttäytymisen muutokseen muualla.
• ja hallusinaatioita.

Mutta ymmärrämme jo, että perinteiset testit, jotka keskittyvät nimenomaisen koodin logiikan todentamiseen, eivät täysin kykene kattamaan näitä kysymyksiä.

Solution:Meidän on kehitettävä monimutkainen, kattava lähestymistapa, joka kattaa monia asioita, yhdistämällä klassisia ja verkkotunnuskohtaisia ratkaisuja.

• Monitasoinen testaus: Erilaisten testaustyyppien yhdistelmä, joka kohdistuu järjestelmän eri osa-alueisiin: yksittäisten toimintojen ja kehotusten matalan tason yksikötesteistä monimutkaisiin skenaarioihin, jotka tarkistavat agentin loppupään työnkulun ja käyttäjän vuorovaikutuksen.
• Keskity LLM: n käyttäytymiseen ja laatuun: Testin tulisi arvioida paitsi toiminnallista oikeellisuutta myös LLM: n vastausten laadullisia ominaisuuksia, kuten merkitystä, tarkkuutta, johdonmukaisuutta, haitallisen tai puolueellisen sisällön puuttumista sekä ohjeiden ja tietyn tyylin noudattamista.
• Regressiota ja laatutestejä, jotka sisältävät "kultaisia tietokokonaisuuksia", jotka sisältävät erilaisia syöttöesimerkkejä ja viittauksia (tai hyväksyttäviä vaihteluvälejä).
• Automaatio ja integrointi CI/CD:hen
• Human-in-the-loop arviointi: Erityiset vaiheet LLM-eval pitäisi liittyä ihmisen kalibrointi mittareita ja tarkastella monimutkaisia tai kriittisiä tapauksia.
• Iteratiivinen lähestymistapa prompt-kehitykseen ja testaukseen: Prompt-tekniikkaa tulisi käsitellä iteratiivisena prosessina, jossa jokainen versio promptista testataan ja arvioidaan perusteellisesti ennen toteutusta.
• 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

Tämä on meta-periaate; se kulkee kaikkien edellä lueteltujen kautta.

Onneksi tänään meillä on kymmeniä työkaluja ja kehyksiä mihin tahansa tehtävään.Tämä on hienoa, se on kätevä, ja se on ansa.

Lähes aina valmiin ratkaisun valitseminen tarkoittaatrade-offSaat nopeuden ja helpon alun, mutta häviätflexibility, control, and, potentially, security.

Tämä on erityisen tärkeää agenttien kehittämisessä, jossa on tärkeää hallita:

• LLM: n ennakoimattomuus
• monimutkainen logiikka siirtymille ja itsekorjaukselle,
• järjestelmän sopeutumiseen ja kehitykseen, vaikka sen ydintehtävät pysyisivät ennallaan.

Puitteet tuovatinversion of controlTämä voi yksinkertaistaa prototyyppiä, mutta monimutkaistaa sen pitkän aikavälin kehitystä.

Monet edellä mainituista periaatteista voidaan toteuttaa off-the-shelf-ratkaisuilla – ja tämä on usein perusteltua.explicit implementation of the core logic takes a comparable amount of timeAntaa vertaansa vailla enemmäntransparency, manageability, and adaptability.

Myös vastakkainen ääripää on olemassa -over-engineering, halu kirjoittaa kaiken tyhjästä.Tämä on myös virhe.

This is why the key is balance.Insinööri valitsee itselleen: missä on kohtuullista luottaa kehykseen ja missä on tärkeää ylläpitää valvontaa.

Sinun on muistettava: teollisuus on yhä muotoilussa. Monet työkalut luotiin ennen nykyisten standardien syntymistä. Huomenna ne saattavat muuttua vanhentuneiksi – mutta arkkitehtuurissasi tänä päivänä paistetut rajoitukset säilyvät.

Conclusion

Okei, olemme käyneet yli 15 periaatetta, jotka kokemuksen mukaan auttavat kääntämään "se on elossa!" alkuperäisen jännityksen luottamukseen, että LLM-agentti toimii vakaalla, ennustettavalla ja hyödyllisellä tavalla todellisissa olosuhteissa.

Sinun pitäisi harkita jokaista niistä nähdäksesi, onko järkevää soveltaa sitä projektiin.Lopulta se on projekti, tehtäväsi ja luomuksesi.

Key takeaways to carry with you:

1. Tekninen lähestymistapa on avain: Älä luota LLM: n "maagiseen". rakenne, ennustettavuus, hallittavuus ja testaus ovat parhaita ystäviäsi.
2. LLM on tehokas osa, mutta silti vain osa: kohtele LLM erittäin älykäs, mutta silti, yksi osa järjestelmääsi.
3. Iteraatio ja palaute ovat avain menestykseen: On harvinaista luoda täydellinen agentti ensimmäisellä yrityksellä. Ole valmis kokeiluihin, mittauksiin, virheiden analysointiin ja jatkuvaan parantamiseen - sekä agentti itsessään että kehitysprosesseissasi.
4. Yhteisö ja avoimuus: LLM-agenttien kenttä kehittyy nopeasti. Pidä silmällä uutta tutkimusta, työkaluja ja parhaita käytäntöjä ja jaa omia kokemuksiasi.

Toivon, että olet löytänyt jotain uutta ja hyödyllistä täällä, ja ehkä haluat jopa palata tähän suunnitellessasi seuraavaa agenttia.