L'agente AI a 12 fattori: Costruire sistemi AI efficaci e scalabili

Cosa rende efficace un agente AI?

Prima di entrare nei fattori, chiariamo cosa intendiamo per “agenti AI”. Fondamentalmente, sono sistemi che sanno interpretare richieste in linguaggio naturale, prendere decisioni in base al contesto ed eseguire azioni specifiche tramite strumenti o API—il tutto mantenendo interazioni coerenti e continue.

Gli agenti più potenti combinano le capacità di ragionamento dei modelli linguistici con l’affidabilità del codice deterministico. Ma trovare questo equilibrio richiede scelte progettuali attente, ed è proprio ciò che questi fattori aiutano a ottenere.

I 12 fattori per costruire agenti AI robusti

1. Padroneggia la conversione dal linguaggio naturale alla chiamata dello strumento

La capacità di trasformare richieste in linguaggio naturale in chiamate strutturate agli strumenti è il cuore della funzionalità dell’agente. È ciò che permette a un agente di prendere un comando semplice come “crea un link di pagamento da 750$ per Terri per il meetup di febbraio degli AI Tinkerers” e convertirlo in una chiamata API formattata correttamente.

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

La chiave per far funzionare tutto in modo affidabile è utilizzare codice deterministico per gestire l’output strutturato del tuo modello linguistico. Valida sempre i payload delle API prima dell’esecuzione per prevenire errori e assicurati che il tuo LLM restituisca formati JSON coerenti, sempre interpretabili.

2. Possiedi i tuoi prompt completamente

I tuoi prompt sono l’interfaccia tra la tua applicazione e il modello linguistico—trattali come codice di prima classe. Anche se i framework che astraggono i prompt sembrano comodi, spesso nascondono come le istruzioni vengono passate all’LLM, rendendo difficile o impossibile l’ottimizzazione fine.

Invece, mantieni il controllo diretto dei tuoi prompt scrivendoli esplicitamente:

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
  prompt #"
    {{ _.role("system") }}
    Sei un assistente utile che gestisce le distribuzioni per sistemi frontend e backend.
    ...
    {{ _.role("user") }}
    {{ thread }}
    Qual è il prossimo passo da eseguire?
  "#
}

Questo approccio ti offre diversi vantaggi:

• Controllo totale per scrivere istruzioni precise su misura per il tuo caso d’uso
• Possibilità di creare valutazioni e test per i prompt come per qualsiasi altro codice
• Trasparenza per capire esattamente cosa riceve l’LLM
• Libertà di iterare in base alle metriche di performance

3. Progetta strategicamente la tua finestra di contesto

La finestra di contesto è l’input dell’LLM e comprende prompt, cronologia delle conversazioni e dati esterni. Ottimizzare questa finestra migliora prestazioni ed efficienza nell’uso dei token.

Image URL

Vai oltre i formati standard basati su messaggi con strutture personalizzate che massimizzano la densità informativa:

<slack_message>
    Da: @alex
    Canale: #deployments
    Testo: Puoi distribuire il 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>

Questo metodo offre diversi vantaggi:

• Ridotto uso di token grazie a formati compatti
• Migliore filtraggio di dati sensibili prima di passarli all’LLM
• Flessibilità per sperimentare formati che aumentino la comprensione dell’LLM

4. Implementa gli strumenti come output strutturati

Alla base, gli strumenti sono semplicemente output JSON dell’LLM che attivano azioni deterministiche nel tuo codice. Questo crea una chiara separazione tra il decision making dell’AI e la logica di esecuzione.

Definisci chiaramente gli schemi degli strumenti:

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

Costruisci quindi parsing affidabili per gli output JSON dell’LLM, usa codice deterministico per eseguire le azioni e reinserisci i risultati nel contesto per workflow iterativi.

5. Unifica esecuzione e stato di business

Molti framework per agenti separano lo stato di esecuzione (es. passo corrente di un processo) dallo stato di business (es. cronologia delle chiamate agli strumenti e risultati). Questa separazione aggiunge complessità non necessaria.

Al contrario, memorizza tutto lo stato direttamente nella finestra di contesto, deducendo lo stato di esecuzione dalla sequenza degli eventi:

<deploy_backend>
    intent: "deploy_backend"
    tag: "v1.2.3"
    environment: "production"
</deploy_backend>
<error>
    errore durante l'esecuzione di deploy_backend: impossibile connettersi al servizio di distribuzione
</error>

Questo approccio unificato offre:

• Semplicità con una sola fonte di verità per lo stato
• Migliore debug grazie alla cronologia completa in un unico posto
• Recupero facile riprendendo da qualsiasi punto caricando il thread

Portare gli agenti AI in produzione

6. Progetta API per avvio, pausa e ripresa

Agenti pronti per la produzione devono integrarsi perfettamente con sistemi esterni, mettersi in pausa per task di lunga durata e riprendere quando attivati da webhook o altri eventi.

Implementa API che permettano di avviare, mettere in pausa e riprendere agenti, con una solida memorizzazione dello stato tra le operazioni. Questo consente:

• Supporto flessibile per workflow asincroni
• Integrazione pulita con webhook e altri sistemi
• Ripresa affidabile dopo interruzioni senza riavvii

7. Abilita la collaborazione umana tramite chiamate agli strumenti

Gli agenti AI hanno spesso bisogno di input umano per decisioni critiche o situazioni ambigue. Usare chiamate strutturate agli strumenti rende questa interazione fluida:

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

Questo approccio offre una specifica chiara del tipo di interazione e urgenza, supporta input da più utenti e si combina bene con API per workflow durevoli.

8. Controlla il flusso del tuo agente

Un flusso di controllo personalizzato ti permette di mettere in pausa per approvazione umana, memorizzare risultati nella cache o implementare limitazioni di frequenza—adattando il comportamento dell’agente alle tue esigenze specifiche:

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

Con questo approccio ottieni:

• Interrompibilità per mettere in pausa e chiedere una revisione umana prima di azioni critiche
• Opzioni di personalizzazione per log, cache o sintesi
• Gestione affidabile di task a lunga esecuzione

9. Comprimi gli errori nel contesto per l’auto-riparazione

Includere gli errori direttamente nella finestra di contesto consente agli agenti AI di imparare dai fallimenti e adattare il loro approccio:

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

Affinché questo funzioni efficacemente:

• Limita i tentativi per evitare loop infiniti
• Escalare agli umani dopo fallimenti ripetuti
• Format errori chiaramente così che l’LLM capisca cosa è andato storto

Best practice architetturali

10. Costruisci agenti piccoli e focalizzati

Agenti piccoli che gestiscono 3–20 passaggi mantengono finestre di contesto gestibili, migliorando le prestazioni e l’affidabilità dell’LLM. Questo approccio offre:

• Chiarezza con ambito ben definito per ciascun agente
• Rischio ridotto che l’agente perda il filo
• Test e validazione più semplici delle funzioni specifiche

Image URL

Con il continuo miglioramento degli LLM, questi piccoli agenti potranno espandere il loro ambito mantenendo la qualità, assicurando scalabilità nel lungo termine.

11. Abilita trigger da più fonti

Rendi i tuoi agenti accessibili permettendo trigger da Slack, email o sistemi di eventi—raggiungendo gli utenti dove già lavorano.

Implementa API che avviano agenti da diversi canali e rispondono tramite lo stesso mezzo. Questo consente:

• Maggiore accessibilità integrandosi con le piattaforme preferite dagli utenti
• Supporto per workflow di automazione guidati dagli eventi
• Workflow di approvazione umana per operazioni critiche

12. Progetta agenti come reducer stateless

Trattare gli agenti come funzioni stateless che trasformano il contesto di input in azioni di output semplifica la gestione dello stato, rendendoli prevedibili e più facili da fare debug.

Image URL

Questo approccio concettuale vede gli agenti come funzioni pure senza stato interno, offrendo:

• Comportamento prevedibile per input dati
• Tracciamento più semplice dei problemi grazie alla cronologia del contesto
• Test e validazione più semplici

Costruire per il futuro

Il campo degli agenti AI sta evolvendo rapidamente, ma questi principi fondamentali rimarranno rilevanti anche con il miglioramento dei modelli sottostanti. Partendo da agenti piccoli e focalizzati che seguono queste pratiche, puoi creare sistemi che offrono valore già oggi e si adattano ai progressi futuri.

Ricorda che gli agenti AI più efficaci combinano le capacità di ragionamento dei modelli linguistici con l’affidabilità del codice deterministico—e questi 12 fattori ti aiutano a trovare il giusto equilibrio.

Come FlowHunt ha applicato la metodologia dei 12 fattori

In FlowHunt, abbiamo messo in pratica questi principi sviluppando il nostro agente AI che crea automaticamente automazioni di workflow per i nostri clienti. Ecco come abbiamo applicato la metodologia dei 12 fattori per costruire un sistema affidabile e pronto per la produzione