Come creare agenti AI personalizzati: architettura, pattern e scalabilità

Fase 1: definisci l'architettura dell'agente AI e il sistema di controllo

L'architettura di un agente AI comprende due parti principali: il modello e il servizio che lo racchiude. Il servizio comprende il modello, i suoi strumenti, la memoria e tutti gli altri componenti. È un software deterministico, costruito attorno al modello, con una logica if/else definita nel codice.

La distinzione è semplice. Quando imparano a creare agenti AI personalizzati, i team spesso commettono l'errore di affidare tutto al modello, causando gravi problemi di affidabilità.

Questo approccio fallisce subito. Il modello genera testo, mentre il servizio esegue la logica. Devi quindi trattare il modello come un motore di ragionamento isolato, che non interviene mai nel codice di instradamento.

Il servizio gestisce stato, instradamento e recupero dagli errori. Il modello non prende decisioni. Dopo il deployment di questo sistema per un'azienda SaaS di medie dimensioni, i tempi di risoluzione delle richieste di supporto sono diminuiti del 40 percento, perché il servizio deterministico gestiva correttamente l'instradamento senza affidarsi alle supposizioni del modello.

Era il codice a farlo. Un flusso di sistema chiaro aiuta a visualizzare questa separazione: è il servizio a dettare il flusso, non il modello. Serve quindi un piano di implementazione rigoroso.

Non tralasciare le condizioni della logica deterministica. Anthropic ha pubblicato un documento sui possibili pattern di progettazione degli agenti AI, che descrive quattro tipi di sistema fondamentali: agenti singoli, workflow sequenziali, workflow paralleli e valutatore-ottimizzatore.

Vuoi sapere come creare agenti AI personalizzati capaci di scalare? Devi scegliere il pattern in base al problema: costringere un singolo agente a gestire un workflow parallelo in più passaggi farà aumentare enormemente la latenza del sistema. Gli agenti singoli svolgono bene un compito alla volta.

• [ ] Definisci la logica di instradamento deterministica
• [ ] Pianifica l'accesso agli strumenti tramite MCP
• [ ] Scegli il modello di base
• [ ] Progetta lo schema dello stato della memoria
• [ ] Configura le procedure di recupero dagli errori

Quale pattern di progettazione è adatto al tuo agente personalizzato?

Sono facili da debuggare, ma hanno un ambito d'azione limitato. Nei workflow sequenziali, l'output di un agente passa al successivo: una soluzione ideale per processi lineari, come le pipeline di ricerca che richiedono un'esecuzione rigorosa, passo dopo passo. L'architettura dei workflow paralleli prevede che un gruppo di agenti AI svolga attività contemporaneamente e in modo asincrono, come nel multithreading dei sistemi informatici tradizionali, per ridurre la latenza.

Questo pattern riduce drasticamente la latenza delle attività complesse. Nell'architettura valutatore-ottimizzatore, due sistemi di agenti lavorano in cicli iterativi: il gruppo A svolge il lavoro e il gruppo B lo valuta e lo migliora, in modo simile alla programmazione in coppia.

Questo produce risultati di qualità superiore nelle attività di programmazione o scrittura. Ecco uno snippet Python che configura un workflow parallelo in cui gli agenti operano in modo asincrono: così puoi eseguire più agenti senza aspettare che finiscano uno dopo l'altro. Esamina il codice qui sotto.

`async def run_agent(task: str):`

# Simulate asynchronous agent task await asyncio.sleep(1)

import asyncio


return f"Result for {task}" async def parallel_workflow(tasks: list[str]): # Agents act asynchronously like multithreading results = await asyncio.gather(*[run_agent(task) for task in tasks])


return results tasks = ["fetch_market_data", "analyze_sentiment", "check_compliance"] results = asyncio.run(parallel_workflow(tasks)) print(results)

Quando progetti il workflow, valuta questi compromessi. Per creare un agente AI con Claude, gli sviluppatori combinano Claude Agent SDK e Agent Skills: due elementi da considerare se stai cercando di capire come creare agenti AI personalizzati. Scegli gli strumenti con attenzione.

Puoi usare Claude Agent SDK per un'integrazione stretta oppure LangGraph per orchestrare macchine a stati complesse.

1. Latenza: i workflow paralleli riducono drasticamente il tempo complessivo.
2. Costo: i workflow paralleli consumano più token al secondo.
3. Accuratezza: i cicli valutatore-ottimizzatore migliorano l'accuratezza, ma raddoppiano le risorse di calcolo.
4. Complessità: i workflow sequenziali sono i più facili da debuggare.

Fase 2: scegli il modello di base e il framework di orchestrazione

Per creare agenti con Claude, il modello concettuale è semplice: l'SDK gestisce il ciclo di esecuzione, gli strumenti e MCP definiscono ciò che l'agente può fare, mentre le Skill definiscono come svolgere le attività. Le responsabilità restano così ben separate. Claude Agent SDK offre un ciclo dell'agente (raccogliere il contesto, chiamare il modello, eseguire uno strumento, restituire il risultato al modello e ripetere) programmabile in Python o TypeScript.

LangGraph offre più controllo: consente di definire nodi espliciti per la logica e di creare vincoli rigorosi che impediscono al modello di effettuare chiamate agli strumenti non previste.

Il livello di orchestrazione fornisce i vincoli essenziali per mantenere gli agenti concentrati sul compito. Puoi definirli nel codice con strumenti come LangGraph oppure gestirli tramite interfacce grafiche come Cursor Automations. Senza orchestrazione, un agente può rimanere bloccato in un ciclo infinito a causa di un singolo errore.

La gestione sicura delle credenziali è fondamentale. Non inserire mai le chiavi API nel prompt di sistema: per i sistemi in produzione, l'unico approccio sicuro è passarle durante l'esecuzione tramite variabili d'ambiente.

Preferiamo LangGraph per gli instradamenti complessi. Ti obbliga a ragionare sulle transizioni di stato, mentre Claude SDK è più adatto alla prototipazione rapida e alle attività che richiedono molti strumenti e iterazioni veloci.

{
 "orchestration": {
 "guardrails": {
 "max_iterations": 5,
 "timeout_seconds": 30
 },
 "secrets_manager": {
 "provider": "aws_secrets_manager",
 "keys": ["ANTHROPIC_API_KEY", "FIRECRAWL_API_KEY"]
 }
 }
}

Fase 3: implementa strumenti, accesso al web e gestione della memoria

Gli agenti AI usano MCP (Model Context Protocol), strumenti CLI e framework come LangChain per accedere agli strumenti. Sapere come creare agenti AI personalizzati significa anche sapere come collegarli alla realtà. Le conoscenze degli agenti AI devono basarsi su dati reali e aggiornati in tempo reale: senza questo accesso, si limitano a quanto contenuto negli archivi di memoria e nei dati di addestramento.

Gli strumenti di recupero delle pagine integrati nei servizi di aziende come OpenAI e Anthropic offrono un accesso al web limitato. Servono quindi strumenti dedicati come Firecrawl. Recuperare l'HTML grezzo spreca spazio nella finestra di contesto e confonde il modello.

Firecrawl offre tre endpoint principali per accedere al web: /search (ricerche sul web in tempo reale), /scrape (recupero di siti come dati strutturati o Markdown) e /interact (apertura di un vero browser per fare clic sui pulsanti e compilare moduli).

Su una pagina tipica, l'estrazione pulita con Firecrawl produce circa 2,788 token di Markdown anziché 38,381 token di HTML grezzo. Rispetto al recupero dell'HTML grezzo, Firecrawl usa il 94 percento di token di input in meno. Questo migliora direttamente le prestazioni dell'agente.

La struttura delle pagine web può cambiare e le pagine possono contenere elementi di navigazione o script irrilevanti. Quando è disponibile, preferisci un endpoint strutturato e documentato e verifica l'estrazione su pagine rappresentative e dopo modifiche al layout.

import requests


def search_web(query: str):
    response = requests.post("https://api.firecrawl.dev/v1/search", 
        json={"query": query, "limit": 5},
        headers={"Authorization": f"Bearer {API_KEY}"})
    return response.json()


def scrape_site(url: str):
    response = requests.post("https://api.firecrawl.dev/v1/scrape",
        json={"url": url, "formats": ["markdown"]},
        headers={"Authorization": f"Bearer {API_KEY}"})
    return response.json()

La memoria è essenziale per i sistemi AI che operano a lungo, perché tutti i modelli hanno una finestra di contesto limitata, che si azzera quando raggiunge il limite. Un modello AI può avere, per esempio, una finestra di contesto di 200,000 token: una volta raggiunto il limite, il contesto va ricostruito tramite la memoria.

Devi archiviare la cronologia delle conversazioni e lo stato in un database esterno. Quando la finestra di contesto si riempie, recuperi un riepilogo e i fatti pertinenti, poi ricostruisci il prompt. Non dare mai per scontato che il modello ricordi qualcosa che non sia presente nell'input corrente.

Come gestire i costi, le chiavi API e i test?

Se esegui cinque agenti contemporaneamente, paghi cinque chiamate al modello nello stesso momento. Un agente singolo costa meno per esecuzione, ma impiega molto più tempo a concludere il lavoro. Devi trovare il giusto equilibrio tra velocità e budget.

Facciamo un esempio concreto con un agente di supporto che gestisce 10,000 richieste al mese. Se ogni ticket gestito manualmente costa $5, la spesa totale è $50,000. Con l’automazione, i costi si distribuiscono diversamente.

L’hosting costa $100. Il punto di pareggio si raggiunge quasi subito. Testare il wrapper dell’agente è imprescindibile: prima di mettere qualsiasi cosa in produzione, devi simulare i malfunzionamenti degli strumenti e verificare a fondo la gestione dei timeout.

Per il wrapper usiamo casi di test deterministici, mentre per il modello usiamo suite di valutazione probabilistiche. Non distribuiamo mai un agente senza averne testato i percorsi di recupero dagli errori. Smetti di appesantire i prompt di sistema.

Le Agent Skills sono cartelle che contengono un file SKILL.md e insegnano all’agente a svolgere attività specializzate. Vengono caricate solo quando servono, così la finestra di contesto resta snella. Se vuoi imparare a creare agenti AI personalizzati, devi separare le diverse responsabilità.

Un aspetto meno ovvio: perché le conoscenze procedurali vanno nelle Skills

Il modello mentale per creare agenti con Claude è semplice: l’SDK gestisce il ciclo di esecuzione, gli strumenti e MCP definiscono cosa può fare l’agente, mentre le Skills gli insegnano come farlo. Gli strumenti sono i verbi, le Skills sono i manuali. Se metti tutte le istruzioni nel prompt di sistema, sprechi spazio nella finestra di contesto: il modello legge anche indicazioni che non servono per l’attività in corso.

Il caricamento progressivo risolve il problema. L’agente carica il file SKILL.md solo quando deve svolgere quella specifica attività. Così la finestra di contesto resta snella e diminuisce il rischio di allucinazioni.

Inoltre, gli agenti diventano modulari: puoi aggiornare una Skill senza toccare la logica centrale di orchestrazione.