12faktorový AI agent: Jak vytvářet efektivní a škálovatelné AI systémy

Co dělá AI agenta efektivním?

Než se pustíme do jednotlivých faktorů, upřesněme si, co myslíme pod pojmem „AI agenti“. V jádru jde o systémy, které dokážou interpretovat požadavky v přirozeném jazyce, rozhodovat na základě kontextu a provádět konkrétní akce pomocí nástrojů nebo API – a to vše při zachování souvislé, kontinuální interakce.

Nejmocnější agenti kombinují schopnost jazykových modelů uvažovat s spolehlivostí deterministického kódu. Najít tuto rovnováhu ale vyžaduje promyšlený design, což je právě cílem těchto faktorů.

12 faktorů pro tvorbu robustních AI agentů

1. Ovládněte převod přirozeného jazyka na volání nástroje

Schopnost převést požadavky v přirozeném jazyce na strukturované volání nástroje je středobodem funkčnosti agenta. Právě to umožňuje agentovi přijmout jednoduchý příkaz typu „vytvoř odkaz na platbu na 750 $ pro Terri na únorové setkání AI Tinkerers“ a převést jej na správně formátované API volání.

Image URL

{
  "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"
    }
  }
}

Klíčem ke spolehlivému fungování je použití deterministického kódu pro zpracování strukturovaného výstupu jazykového modelu. Vždy validujte API payloady před spuštěním, abyste předešli chybám, a zajistěte, že LLM vrací konzistentní JSON formáty, které lze spolehlivě parsovat.

2. Plně vlastněte své prompty

Prompty jsou rozhraním mezi vaší aplikací a jazykovým modelem – zacházejte s nimi jako s kódem první třídy. Frameworky, které prompty abstrahují, se mohou zdát pohodlné, často ale zamlžují způsob, jakým jsou instrukce předávány LLM, což ztěžuje nebo znemožňuje jejich ladění.

Raději si udržujte přímou kontrolu nad prompty tím, že je budete psát explicitně:

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 přístup vám přináší několik výhod:

• Plná kontrola nad přesností instrukcí šitých na míru vašemu případu použití
• Možnost stavět evaluace a testy pro prompty stejně jako pro jakýkoliv jiný kód
• Transparentnost – víte přesně, co LLM dostává
• Svoboda iterovat na základě výkonnostních metrik

3. Navrhujte své kontextové okno strategicky

Kontextové okno slouží jako vstup pro LLM – zahrnuje prompty, historii konverzace i externí data. Optimalizací tohoto okna zvýšíte výkon a efektivitu využití tokenů.

Image URL

Jděte nad rámec běžných formátů založených na zprávách a používejte vlastní struktury maximalizující hustotu informací:

<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 přístup přináší několik benefitů:

• Snížení spotřeby tokenů díky kompaktním formátům
• Lepší filtrování citlivých údajů před předáním do LLM
• Flexibilita při experimentování s formáty pro lepší porozumění LLM

4. Implementujte nástroje jako strukturované výstupy

V jádru jsou nástroje jednoduše JSON výstupy z LLM, které spouštějí deterministické akce ve vašem kódu. Vzniká tak čisté oddělení rozhodování AI a logiky provedení.

Definujte schémata nástrojů jasně:

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;
}

Poté vybudujte spolehlivý parser na JSON výstupy LLM, použijte deterministický kód k provedení akce a výsledky opět vložte do kontextu pro iterativní workflow.

5. Sjednoťte stav provádění a obchodní stav

Mnoho agentích frameworků odděluje stav provádění (např. aktuální krok procesu) od obchodního stavu (např. historie volání nástrojů a jejich výsledků). Toto rozdělení přináší zbytečnou složitost.

Místo toho ukládejte všechen stav přímo do kontextového okna a stav provádění odvozujte ze sekvence událostí:

<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 sjednocený přístup nabízí:

• Jednoduchost s jedním zdrojem pravdy pro stav
• Snadnější ladění díky úplné historii na jednom místě
• Snadné obnovení workflow načtením threadu z libovolného bodu

Nasazení AI agentů do produkce

6. Navrhujte API pro spuštění, pozastavení a obnovení

Produkčně připravení agenti se musí hladce integrovat s externími systémy, pozastavit se u dlouhotrvajících úloh a obnovit činnost po spuštění webhookem nebo jinou událostí.

Implementujte API umožňující spouštět, pozastavovat a obnovovat agenty s robustním uložením stavu mezi operacemi. Tím získáte:

• Flexibilní podporu asynchronních workflow
• Snadnou integraci s webhooky a dalšími systémy
• Spolehlivé obnovení po přerušení bez nutnosti restartu

7. Umožněte spolupráci s lidmi pomocí volání nástrojů

AI agenti často potřebují lidský vstup pro klíčová rozhodnutí nebo nejednoznačné situace. Použití strukturovaných volání nástrojů tuto interakci zjednodušuje:

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

Image URL

Tento přístup jasně specifikuje typ interakce a naléhavost, podporuje vstupy od více uživatelů a dobře se kombinuje s API pro trvalé workflow.

8. Řiďte tok vašeho agenta

Vlastní řízení toku vám umožní pozastavit akci pro lidské schválení, cachovat výsledky či implementovat rate limiting – a tak přizpůsobit chování agenta svým potřebám:

Image URL

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;
    }
  }
}

Tím získáte:

• Možnost přerušit workflow pro lidský dohled před kritickými akcemi
• Volnost pro logování, cachování či sumarizaci
• Spolehlivé zpracování dlouhotrvajících úloh

9. Vkládejte chyby do kontextu pro samoléčení

Zařazení chyb přímo do kontextového okna umožňuje AI agentům učit se z neúspěchů a upravit další postup:

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 efektivně:

• Omezte počet opakování, abyste zabránili nekonečným smyčkám
• Po opakovaných neúspěších eskalujte k člověku
• Formátujte chyby jasně, aby LLM pochopil, co se pokazilo

Osvědčené architektonické principy

10. Stavte malé, úzce zaměřené agenty

Malí agenti, kteří řeší 3–20 kroků, udrží spravovatelné kontextové okno, což zlepšuje výkon i spolehlivost LLM. Tento přístup přináší:

• Přehlednost díky jasně vymezenému záběru každého agenta
• Menší riziko, že agent ztratí zaměření
• Snadnější testování a ověřování konkrétních funkcí

Image URL

Jak se LLM budou zlepšovat, mohou i tito malí agenti rozšiřovat svůj záběr, aniž by ztratili kvalitu, což zajistí dlouhodobou škálovatelnost.

11. Umožněte spouštění z více zdrojů

Zpřístupněte své agenty tím, že umožníte spouštění ze Slacku, e-mailu nebo eventových systémů – tedy tam, kde uživatelé skutečně pracují.

Implementujte API, která agenty spustí z různých kanálů a umožní odpovídat stejným médiem. Získáte tak:

• Větší dostupnost díky integraci do uživatelsky preferovaných platforem
• Podporu automatizace založené na událostech
• Workflow pro lidské schvalování u klíčových operací

12. Navrhujte agenty jako bezstavové reduktory

Zacházejte s agenty jako s bezstavovými funkcemi, které proměňují vstupní kontext na výstupní akce – tím zjednodušíte správu stavu, usnadníte ladění a zvýšíte předvídatelnost.

Image URL

Tento koncepční přístup vnímá agenty jako čisté funkce bez interního stavu, takže nabízí:

• Předvídatelné chování pro dané vstupy
• Snadné dohledání problémů díky historii kontextu
• Jednodušší testování a validaci

Budování pro budoucnost

Oblast AI agentů se rychle vyvíjí, ale tyto základní principy zůstanou relevantní i s tím, jak se budou modely dále zlepšovat. Začněte s malými, úzce zaměřenými agenty, kteří se řídí těmito zásadami, abyste vytvářeli systémy, které mají hodnotu už dnes a zároveň se umí přizpůsobit budoucím inovacím.

Pamatujte, že nejefektivnější AI agenti kombinují uvažování jazykových modelů se spolehlivostí deterministického kódu – a právě těchto 12 faktorů vám pomůže tuto rovnováhu najít.

Jak FlowHunt uplatnil metodiku 12 faktorů

Ve FlowHunt jsme tyto principy uvedli do praxe vývojem vlastního AI agenta, který automaticky vytváří workflow automatizace pro naše zákazníky. Zde je, jak jsme metodiku 12 faktorů využili při budování spolehlivého, produkčně připraveného systému