12-Faktorový AI Agent: Budovanie efektívnych AI systémov, ktoré škálujú

Čo tvorí efektívneho AI agenta?

Predtým, než sa pustíme do jednotlivých faktorov, objasnime si, čo myslíme pod pojmom „AI agenti“. V jadre sú to systémy, ktoré dokážu interpretovať požiadavky v prirodzenom jazyku, robiť rozhodnutia na základe kontextu a vykonávať konkrétne akcie prostredníctvom nástrojov alebo API – a to všetko pri zachovaní koherentnej, prebiehajúcej interakcie.

Najsilnejší agenti spájajú schopnosti uvažovania jazykových modelov so spoľahlivosťou deterministického kódu. Dosiahnuť túto rovnováhu však vyžaduje premyslené dizajnové rozhodnutia, práve ktorým sa tieto faktory venujú.

12 faktorov pre budovanie robustných AI agentov

1. Majstrovsky zvládnite prevod prirodzeného jazyka na volanie nástroja

Schopnosť premeniť požiadavky v prirodzenom jazyku na štruktúrované volania nástrojov je jadrom funkčnosti agenta. Práve to umožňuje agentovi vziať jednoduchý príkaz ako „vytvor platobný odkaz na 750 $ pre Terri na februárové stretnutie AI Tinkerers“ a konvertovať ho na správne naformátované API volanie.

URL obrázku

{
  "function": {
    "name": "create_payment_link",
    "parameters": {
      "amount": 750,
      "customer": "cust_128934ddasf9",
      "product": "prod_8675309",
      "price": "prc_09874329fds",
      "quantity": 1,
      "memo": "Hey Jeff - see below for the payment link for the February AI Tinkerers meetup"
    }
  }
}

Kľúčom k spoľahlivej funkčnosti je použitie deterministického kódu na spracovanie štruktúrovaného výstupu z jazykového modelu. Vždy validujte API payload pred vykonaním, aby ste predišli chybám, a zabezpečte, že váš LLM vracia konzistentné JSON formáty, ktoré možno spoľahlivo parsovať.

2. Vlastnite svoje prompti naplno

Vaše prompti sú rozhraním medzi vašou aplikáciou a jazykovým modelom – zaobchádzajte s nimi ako s prvotriednym kódom. Hoci frameworky, ktoré prompti abstrahujú, môžu pôsobiť pohodlne, často zakrývajú spôsob, akým sa inštrukcie odovzdávajú LLM, čo sťažuje alebo znemožňuje jemné doladenie.

Namiesto toho majte nad promptami priamu kontrolu písaním ich explicitne:

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
  prompt #"
    {{ _.role("system") }}
    You are a helpful assistant that manages deployments for frontend and backend systems.
    ...
    {{ _.role("user") }}
    {{ thread }}
    What should the next step be?
  "#
}

Tento prístup prináša viacero výhod:

• Plná kontrola nad presnými inštrukciami šitými na mieru vašej aplikácii
• Možnosť vytvárať hodnotenia a testy promptov ako akýkoľvek iný kód
• Transparentnosť, aby ste presne vedeli, čo LLM dostáva
• Sloboda iterovať na základe výkonnostných metrík

3. Navrhnite kontextové okno strategicky

Kontextové okno slúži ako vstup pre LLM, zahŕňa prompti, históriu konverzácie a externé dáta. Optimalizácia tohto okna zlepšuje výkon aj efektívnosť tokenov.

URL obrázku

Prekročte štandardné formáty založené na správach k vlastným štruktúram maximalizujúcim hustotu informácií:

<slack_message>
    From: @alex
    Channel: #deployments
    Text: Can you deploy the backend?
</slack_message>
<list_git_tags>
    intent: "list_git_tags"
</list_git_tags>
<list_git_tags_result>
    tags:
      - name: "v1.2.3"
        commit: "abc123"
        date: "2024-03-15T10:00:00Z"
</list_git_tags_result>

Tento prístup prináša viacero benefitov:

• Nižšia spotreba tokenov vďaka kompaktným formátom
• Lepšie filtrovanie citlivých údajov pred odovzdaním LLM
• Flexibilita experimentovať s formátmi, ktoré zlepšujú porozumenie LLM

4. Implementujte nástroje ako štruktúrované výstupy

V jadre sú nástroje jednoducho JSON výstupy z LLM, ktoré spúšťajú deterministické akcie vo vašom kóde. Tým sa vytvára čisté oddelenie medzi rozhodovaním AI a vykonávacou logikou.

Jasne definujte schémy nástrojov:

class CreateIssue {
  intent: "create_issue";
  issue: {
    title: string;
    description: string;
    team_id: string;
    assignee_id: string;
  };
}

class SearchIssues {
  intent: "search_issues";
  query: string;
  what_youre_looking_for: string;
}

Potom vybudujte spoľahlivé parsovanie JSON výstupov z LLM, použite deterministický kód na vykonanie akcií a výsledky vracajte späť do kontextu pre iteratívne workflowy.

5. Zjednoťte vykonávací a biznisový stav

Mnohé frameworky pre agentov oddeľujú vykonávací stav (napr. aktuálny krok v procese) od biznisového stavu (napr. história volaní nástrojov a ich výsledkov). Toto oddelenie pridáva zbytočnú zložitosť.

Namiesto toho ukladajte všetok stav priamo do kontextového okna a vyvodzujte vykonávací stav zo sekvencie udalostí:

<deploy_backend>
    intent: "deploy_backend"
    tag: "v1.2.3"
    environment: "production"
</deploy_backend>
<error>
    error running deploy_backend: Failed to connect to deployment service
</error>

Tento zjednotený prístup poskytuje:

• Jednoduchosť s jedným zdrojom pravdy pre stav
• Lepšie ladenie vďaka úplnej histórii na jednom mieste
• Jednoduché obnovenie pokračovaním z ľubovoľného bodu načítaním vlákna

Nasadenie AI agentov do produkcie

6. Navrhnite API pre spustenie, pozastavenie a obnovenie

Produkčne pripravení agenti musia bezproblémovo integrovať s externými systémami, pozastaviť sa pri dlhobežných úlohách a znovu sa spustiť pri triggeri z webhooku alebo inej udalosti.

Implementujte API, ktoré umožnia spustenie, pozastavenie a obnovenie agentov, s robustným uložením stavu medzi operáciami. To umožňuje:

• Flexibilnú podporu asynchrónnych workflowov
• Čistú integráciu s webhookmi a inými systémami
• Spoľahlivé obnovenie po prerušení bez reštartu

7. Umožnite spoluprácu s ľuďmi cez volania nástrojov

AI agenti často potrebujú vstup od človeka pri dôležitých rozhodnutiach alebo nejasných situáciách. Použitie štruktúrovaných volaní nástrojov robí túto interakciu bezproblémovou:

class RequestHumanInput {  
  intent: "request_human_input";  
  question: string;  
  context: string;  
  options: {  
    urgency: "low" | "medium" | "high";  
    format: "free_text" | "yes_no" | "multiple_choice";  
    choices: string[];  
  };  
}

URL obrázku

Tento prístup poskytuje jasnú špecifikáciu typu interakcie a naliehavosti, podporuje vstupy od viacerých používateľov a dobre sa kombinuje s API pre odolné workflowy.

8. Majte pod kontrolou tok agenta

Vlastný riadiaci tok vám umožní pozastaviť sa na ľudské schválenie, cacheovať výsledky alebo zaviesť rate limiting – teda prispôsobiť správanie agenta vašim špecifickým potrebám:

URL obrázku

async function handleNextStep(thread: Thread) {
  while (true) {
    const nextStep = await determineNextStep(threadToPrompt(thread));
    if (nextStep.intent === 'request_clarification') {
      await sendMessageToHuman(nextStep);
      await db.saveThread(thread);
      break;
    } else if (nextStep.intent === 'fetch_open_issues') {
      const issues = await linearClient.issues();
      thread.events.push({ type: 'fetch_open_issues_result', data: issues });
      continue;
    }
  }
}

S týmto prístupom získate:

• Prerušiteľnosť pre pozastavenie na ľudskú kontrolu pred kritickými akciami
• Možnosti prispôsobenia pre logovanie, cacheovanie alebo sumarizáciu
• Spoľahlivé spracovanie dlhobežných úloh

9. Zahrňte chyby do kontextu pre samoliečenie

Zahrnutie chýb priamo do kontextového okna umožňuje AI agentom učiť sa z neúspechov a upraviť svoj prístup:

try {
  const result = await handleNextStep(thread, nextStep);
  thread.events.push({ type: `${nextStep.intent}_result`, data: result });
} catch (e) {
  thread.events.push({ type: 'error', data: formatError(e) });
}

Aby to fungovalo efektívne:

• Obmedzte počet opakovaní, aby ste predišli nekonečným slučkám
• Po opakovaných zlyhaniach eskalujte na človeka
• Jasne formátujte chyby, aby LLM pochopilo, čo sa pokazilo

Architektonické najlepšie praktiky

10. Budujte malých, zameraných agentov

Malí agenti, ktorí zvládnu 3–20 krokov, si udržiavajú spravovateľné kontextové okná, čo zlepšuje výkon i spoľahlivosť LLM. Tento prístup poskytuje:

• Jasnosť s dobre definovaným rozsahom každého agenta
• Znížené riziko, že agent stratí fokus
• Jednoduchšie testovanie a validáciu konkrétnych funkcií

URL obrázku

Ako sa LLM budú ďalej zlepšovať, títo malí agenti môžu rozširovať svoj rozsah pri zachovaní kvality, čo zabezpečí dlhodobú škálovateľnosť.

11. Umožnite spúšťanie z viacerých zdrojov

Sprístupnite svojich agentov tým, že umožníte spúšťanie zo Slacku, e-mailu alebo event systémov – teda tam, kde už používatelia pracujú.

Implementujte API, ktoré spustí agentov z rôznych kanálov a odpovedá rovnakým spôsobom. To umožňuje:

• Lepšiu dostupnosť integráciou s preferovanými platformami používateľov
• Podporu event-driven automatizačných workflowov
• Schvaľovanie ľuďmi pri dôležitých operáciách

12. Navrhujte agentov ako bezstavové reduktory

Zaobchádzajte s agentmi ako s bezstavovými funkciami, ktoré premieňajú vstupný kontext na výstupné akcie, čím zjednodušujete správu stavu a robíte ich predvídateľnými a ľahko laditeľnými.

URL obrázku

Tento konceptuálny prístup vníma agentov ako čisté funkcie bez vnútorného stavu, čo poskytuje:

• Predvídateľné správanie pre dané vstupy
• Jednoduchšie sledovanie problémov cez históriu kontextu
• Jednoduchšie testovanie a validáciu

Budovanie pre budúcnosť

Oblasť AI agentov sa rýchlo vyvíja, no tieto základné princípy zostanú relevantné aj s vylepšovaním modelov. Ak začnete s malými, zameranými agentmi, ktorí sa riadia týmito praktikami, vytvoríte systémy, ktoré prinášajú hodnotu už dnes a zároveň sa dokážu prispôsobiť budúcim pokrokom.

Pamätajte, že najefektívnejší AI agenti spájajú schopnosti uvažovania jazykových modelov so spoľahlivosťou deterministického kódu – a týchto 12 faktorov vám pomôže túto rovnováhu dosiahnuť.

Ako FlowHunt aplikoval 12-faktorovú metodológiu

Vo FlowHunt sme tieto princípy uviedli do praxe vývojom vlastného AI agenta, ktorý automaticky vytvára workflow automatizácie pre našich zákazníkov. Tu je, ako sme aplikovali 12-faktorovú metodológiu na vytvorenie spoľahlivého, produkčne pripraveného systému