Agentul AI cu 12 Factori: Construirea de Sisteme AI Eficiente care Scală

Ce face un Agent AI Eficient?

Înainte de a intra în factori, să clarificăm ce înțelegem prin „agenți AI”. În esență, aceștia sunt sisteme care pot interpreta cereri în limbaj natural, lua decizii bazate pe context și executa acțiuni specifice prin instrumente sau API-uri — totul menținând interacțiuni coerente și continue.

Cei mai puternici agenți combină capacitățile de raționament ale modelelor de limbaj cu fiabilitatea codului determinist. Dar găsirea acestui echilibru necesită alegeri de design atente, exact la asta se referă acești factori.

Cei 12 factori pentru construirea agenților AI robuști

1. Stăpânește Conversia din Limbaj Natural în Apeluri de Instrumente

Capacitatea de a transforma cererile în limbaj natural în apeluri de instrumente structurate stă la baza funcționalității agentului. Acesta este ceea ce permite unui agent să ia o comandă simplă precum „creează un link de plată de 750$ pentru Terri pentru întâlnirea AI Tinkerers din februarie” și să o convertească într-un apel API formatat corect.

URL Imagine

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

Cheia pentru ca acest lucru să funcționeze fiabil este să folosești cod determinist pentru a gestiona ieșirea structurată de la modelul tău de limbaj. Validează întotdeauna payload-urile API înainte de execuție pentru a preveni erorile și asigură-te că LLM-ul returnează formate JSON consistente care pot fi parcurse cu încredere.

2. Deține Complet Prompturile Tale

Prompturile tale sunt interfața dintre aplicația ta și modelul de limbaj — tratează-le ca pe un cod de primă clasă. Deși framework-urile care abstractizează prompturile pot părea convenabile, acestea adesea ascund modul în care instrucțiunile sunt transmise către LLM, făcând dificilă sau imposibilă ajustarea fină.

În schimb, menține controlul direct asupra prompturilor tale, scriindu-le explicit:

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?
  "#
}

Această abordare îți oferă mai multe avantaje:

• Control total pentru a scrie instrucțiuni precise adaptate cazului tău specific de utilizare
• Posibilitatea de a construi evaluări și teste pentru prompturi ca pentru orice alt cod
• Transparență pentru a înțelege exact ce primește LLM-ul
• Libertatea de a itera bazat pe metrici de performanță

3. Proiectează Strategic Fereastra de Context

Fereastra de context servește ca intrare pentru LLM, cuprinzând prompturi, istoric conversațional și date externe. Optimizarea acestei ferestre îmbunătățește performanța și eficiența utilizării tokenilor.

URL Imagine

Mergi dincolo de formatele standard bazate pe mesaje către structuri personalizate care maximizează densitatea informației:

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

Această abordare oferă mai multe beneficii:

• Utilizare redusă a tokenilor cu formate compacte
• Filtrare mai bună a datelor sensibile înainte de a fi transmise LLM-ului
• Flexibilitate pentru a experimenta cu formate care îmbunătățesc înțelegerea LLM-ului

4. Implementează Instrumentele ca Ieșiri Structurate

La bază, instrumentele sunt pur și simplu ieșiri JSON de la LLM care declanșează acțiuni deterministe în codul tău. Acest lucru creează o separare clară între procesul decizional AI și logica de execuție.

Definește clar schemele instrumentelor:

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

Apoi construiește un parsing fiabil pentru ieșirile JSON de la LLM, folosește cod determinist pentru a executa acțiunile și transmite rezultatele înapoi în context pentru fluxuri iterative.

5. Unifică Execuția și Starea de Business

Multe framework-uri pentru agenți separă starea de execuție (ex: pasul curent dintr-un proces) de starea de business (ex: istoricul apelurilor de instrumente și rezultatelor lor). Această separare adaugă complexitate inutilă.

În schimb, stochează toată starea direct în fereastra de context, deducând starea de execuție din secvența evenimentelor:

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

Această abordare unificată oferă:

• Simplitate cu o singură sursă de adevăr pentru stare
• Debugging mai bun cu istoricul complet într-un singur loc
• Recuperare ușoară prin reluarea din orice punct prin încărcarea thread-ului

Lansarea Agenților AI în Producție

6. Proiectează API-uri pentru Lansare, Pauză și Reluare

Agenții de nivel producție trebuie să se integreze perfect cu sistemele externe, să se poată pune în pauză pentru sarcini de lungă durată și să fie reluați când sunt declanșați de webhook-uri sau alte evenimente.

Implementează API-uri care permit lansarea, pauzarea și reluarea agenților, cu stocare robustă a stării între operațiuni. Acest lucru permite:

• Suport flexibil pentru fluxuri de lucru asincrone
• Integrare curată cu webhook-uri și alte sisteme
• Reluare fiabilă după întreruperi fără restartare

7. Permite Colaborarea Umană prin Apeluri de Instrumente

Agenții AI au adesea nevoie de input uman pentru decizii cu miză mare sau situații ambigue. Folosirea apelurilor de instrumente structurate face această interacțiune fără cusur:

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 Imagine

Această abordare oferă specificare clară a tipului de interacțiune și a urgenței, suportă input de la mai mulți utilizatori și se combină bine cu API-uri pentru fluxuri de lucru durabile.

8. Controlează Fluxul Agentului Tău

Fluxul de control personalizat îți permite să pui pauză pentru aprobare umană, să faci caching la rezultate sau să implementezi limitarea ratei — adaptând comportamentul agentului la nevoile tale specifice:

URL Imagine

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

Cu această abordare, obții:

• Posibilitatea de întrerupere pentru revizuire umană înainte de acțiuni critice
• Opțiuni de personalizare pentru logare, caching sau sumarizare
• Gestionare fiabilă a sarcinilor de lungă durată

9. Compactează Erorile în Context pentru Autocorectare

Incluzând erorile direct în fereastra de context, agenții AI pot învăța din eșecuri și își pot ajusta abordarea:

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

Pentru ca acest lucru să funcționeze eficient:

• Limitează retry-urile pentru a preveni bucle infinite
• Escaladează la oameni după eșecuri repetate
• Formatează clar erorile pentru ca LLM-ul să poată înțelege ce a mers prost

Cele mai bune practici arhitecturale

10. Construiește Agenți Mici și Focalizați

Agenții mici care gestionează 3–20 pași mențin ferestre de context ușor de gestionat, îmbunătățind performanța și fiabilitatea LLM. Această abordare oferă:

• Claritate cu un scop bine definit pentru fiecare agent
• Risc redus ca agentul să-și piardă focusul
• Testare și validare mai ușoară a funcțiilor specifice

URL Imagine

Pe măsură ce LLM-urile continuă să se îmbunătățească, acești agenți mici își pot extinde scopul păstrând calitatea, asigurând scalabilitatea pe termen lung.

11. Permite Declanșatori din Surse Multiple

Fă agenții tăi accesibili permițând declanșarea din Slack, email sau sisteme de evenimente — ajungând la utilizatori acolo unde deja lucrează.

Implementează API-uri care lansează agenți din diverse canale și răspund prin același mediu. Acest lucru permite:

• Accesibilitate mai bună prin integrare cu platformele preferate de utilizatori
• Suport pentru fluxuri de lucru automatizate bazate pe evenimente
• Fluxuri de aprobare umană pentru operațiuni cu miză ridicată

12. Proiectează Agenții ca Reduceri Fără Stare

Tratează agenții ca funcții fără stare care transformă contextul de intrare în acțiuni de ieșire, simplificând gestionarea stării și făcându-i predictibili și mai ușor de depanat.

URL Imagine

Această abordare conceptuală privește agenții ca funcții pure care nu mențin stare internă, oferind:

• Comportament predictibil pentru aceleași inputuri
• Urmărire mai ușoară a problemelor prin istoricul contextului
• Testare și validare mai simplă

Construiește pentru viitor

Domeniul agenților AI evoluează rapid, dar aceste principii de bază vor rămâne relevante chiar și pe măsură ce modelele de bază se îmbunătățesc. Începând cu agenți mici, focalizați, care urmează aceste practici, poți crea sisteme care oferă valoare astăzi și se adaptează avansului viitor.

Amintește-ți că cei mai eficienți agenți AI combină capacitățile de raționament ale modelelor de limbaj cu fiabilitatea codului determinist — iar acești 12 factori te ajută să găsești acel echilibru.

Cum a aplicat FlowHunt metodologia cu 12 factori

La FlowHunt, am pus aceste principii în practică dezvoltând propriul nostru agent AI care creează automat automatizări de fluxuri de lucru pentru clienții noștri. Iată cum am aplicat metodologia cu 12 factori pentru a construi un sistem fiabil, gata de producție