Passa al contenuto principale

Costruire agenti AI locali

Avanzato

Un agente AI locale è un ciclo autonomo che gira interamente sul tuo hardware: un modello a pesi aperti (servito da Ollama o LM Studio) decide cosa fare, chiama gli strumenti che gli dai, legge i risultati, e continua finché il compito è fatto — con niente che lascia la tua macchina. Nessuna API cloud, nessun conto per-chiamata, nessun internet richiesto. La fregatura: un modello abbastanza piccolo da girare su un laptop è più debole nel ragionamento difficile e nella pianificazione a lungo orizzonte di un modello di frontiera, e tu possiedi la sua affidabilità e sicurezza. Questa pagina copre il caso onesto per gli agenti locali, l'architettura minima, cosa gira davvero localmente, e un percorso realistico verso il tuo primo agente.

What you'll learn
  • Sapere PERCHÉ costruiresti un agente che gira localmente — e i compromessi onesti rispetto a un agente su API cloud
  • Capire l'architettura minima: modello locale + ciclo di tool-calling + strumenti + un guardrail/condizione di stop
  • Scegliere un modello locale che possa davvero fare uso di strumenti / lavoro agentico
  • Sapere quali framework di agenti girano localmente puntando a un endpoint locale (LangGraph, CrewAI, OpenAI Agents SDK)
  • Seguire un percorso 'inizia semplice' da una singola chiamata a strumento a un ciclo protetto
  • Sandbox e cap di budget dell'agente così che un ciclo autonomo non possa fare danni reali

Perché costruire un agente locale (e quando no)​

Un ordinario agente a uso di strumenti chiama un modello cloud. Un agente locale scambia quella chiamata cloud per un modello che gira sulla tua macchina. Rinunci a qualche capacità ed erediti qualche onere operativo; in cambio ottieni quattro cose difficili da ottenere in altro modo:

  • Privacy — prompt, input degli strumenti e output degli strumenti non lasciano mai la macchina. È l'intera ragione per cui i team in contesti regolamentati, sensibili o air-gapped costruiscono agenti locali: i dati fisicamente non possono andare a terze parti.
  • Offline — nessun internet, nessuna dipendenza da API, nessun outage del provider. L'agente è file sul tuo disco; gira su un aereo o dietro un firewall.
  • Nessun costo per-chiamata — un ciclo di agente può lanciare decine di chiamate al modello per compito. Localmente quelle chiamate sono "gratis" (paghi in elettricità e hardware, non in token), quindi puoi lasciarlo iterare senza guardare il contatore.
  • Controllo totale — fissa una versione esatta del modello, personalizza il comportamento, e gira senza rate limit o sorprese dei termini di servizio.

I compromessi onesti — sii lucido su questi prima di impegnarti:

  • Divario di capacità. La parte più difficile di un agente è il ragionamento: pianificare lavoro multi-step, recuperare da una chiamata a strumento fallita, sapere quando fermarsi. Un modello che puoi eseguire su un laptop (grosso modo 1B–14B parametri) è marcatamente più debole qui di un modello di frontiera. Cicli semplici e ben delimitati funzionano bene localmente; i compiti a lungo orizzonte e aperti sono dove gli agenti locali più spesso deragliano.
  • Possiedi affidabilità e sicurezza. Nessun provider filtra, monitora o mette guardrail per te. Se l'agente cicla all'infinito, chiama lo strumento sbagliato, o compie un'azione distruttiva, è colpa del tuo design. (Vedi l'avviso sotto — è la parte che la gente sottovaluta.)
  • Limiti hardware. Modelli più grandi e più intelligenti hanno bisogno di più RAM/VRAM di quanta ne abbiano la maggior parte delle macchine. Di solito scegli il modello capace più grande che il tuo hardware può eseguire, non il modello migliore che esiste.

Una regola pratica duratura: inizia locale, escala quando il compito lo richiede. Usa un agente locale per lavoro privato/offline/economico-su-scala e cicli ben delimitati; ricorri a un agente su API di frontiera quando il compito ha genuinamente bisogno del ragionamento extra. L'architettura sotto è identica in entrambi i casi — cambia solo l'endpoint — quindi puoi prototipare localmente e scambiare i modelli dopo.

L'architettura minima​

Spoglia un agente fino al suo nucleo e ci sono quattro parti. Tutto il resto è comodità sopra queste.

        ┌─────────────────────────────────────────────┐
        │                                             │
        │   1. LOCAL MODEL  ──►  decides next action  │
        │      (Ollama / LM Studio, tool-capable)     │
        │                  │                          │
        │                  ▼                          │
        │   2. TOOL-CALLING LOOP                       │
        │      parse the model's tool request,         │
        │      run it, feed the result back            │
        │                  │                          │
        │                  ▼                          │
        │   3. TOOLS  ──►  search / read file /        │
        │      run code / call an API (your code)      │
        │                  │                          │
        │                  ▼                          │
        │   4. GUARDRAIL / STOP CONDITION              │
        │      max steps, budget, approval gate,       │
        │      "done" check ──► exit the loop          │
        │                                             │
        └─────────────────────────────────────────────┘
  1. Un modello locale che supporta il tool calling. Il modello deve poter emettere una richiesta strutturata per chiamare uno strumento (alias function calling), non solo chattare. Ollama lo espone tramite la sua API e tramite un endpoint OpenAI-compatibile su http://localhost:11434/v1, quindi qualsiasi framework che parla il formato OpenAI può guidare un modello locale.
  2. Il ciclo di tool-calling. Il cuore dell'agente: invia la conversazione al modello, verifica se ha chiesto di chiamare uno strumento, esegui quello strumento, appendi il risultato, e ripeti. Quando il modello risponde senza richiedere uno strumento, il ciclo finisce.
  3. Strumenti. Semplici funzioni che esponi al modello — cerca sul web, leggi un file, esegui un comando shell, interroga un database, chiama un'API. Ogni strumento ha un nome, una descrizione e uno schema di input tipizzato così il modello sa quando e come usarlo.
  4. Un guardrail / condizione di stop. Non negoziabile per l'autonomia. Al minimo un cap di passi massimi così il ciclo non può girare all'infinito, più — per qualsiasi cosa che scrive, cancella, spende o invia — un gate di approvazione o un sandbox. Senza questo non hai un agente, hai un ciclo infinito con accesso ai file.

Il ciclo nel passo 2 è genuinamente piccolo. Eccolo in pseudocodice Python contro un endpoint Ollama locale:

Un ciclo minimo di agente locale (pseudocodice Python, punta a Ollama locale)

from openai import OpenAI

# Point the OpenAI client at your LOCAL Ollama endpoint — nothing leaves the machine
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

tools = [{
  "type": "function",
  "function": {
      "name": "read_file",
      "description": "Read a UTF-8 text file and return its contents",
      "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"],
      },
  },
}]

def run_tool(name, args):
  if name == "read_file":
      # GUARDRAIL: only allow reads inside a sandboxed directory
      return safe_read(args["path"])
  raise ValueError(f"unknown tool: {name}")

messages = [{"role": "user", "content": "Summarize ./notes/today.md"}]

for step in range(8):                       # GUARDRAIL: hard step cap
  resp = client.chat.completions.create(
      model="llama3.1", messages=messages, tools=tools,
  )
  msg = resp.choices[0].message
  messages.append(msg)

  if not msg.tool_calls:                  # STOP: model answered, we're done
      print(msg.content)
      break

  for call in msg.tool_calls:
      result = run_tool(call.function.name, json.loads(call.function.arguments))
      messages.append({
          "role": "tool", "tool_call_id": call.id, "content": str(result),
      })
else:
  print("Stopped: hit the step cap without finishing.")

Questo è tutto il pattern. I framework aggiungono memoria, retry, orchestrazione multi-agente, tracing e stato strutturato sopra — ma ognuno di essi è una versione più robusta di questo ciclo.

Quali modelli locali sono adatti al lavoro agentico / uso di strumenti​

Non ogni modello a pesi aperti può guidare un agente. L'asticella è il tool calling affidabile: il modello deve emettere richieste di strumenti ben formate in modo coerente, scegliere lo strumento giusto, e non allucinare argomenti. Due filtri nella scelta:

  • Deve essere un modello capace di strumenti. Ollama li tagga — sfoglia la categoria Tools per la lista attuale invece di presumere. Modelli comunemente citati per un solido uso di strumenti locale includono le famiglie instruction-tuned Qwen e Llama; la migliore scelta esatta si sposta di trimestre in trimestre.
  • Deve stare nel tuo hardware con spazio per il contesto. I cicli di agente accumulano lunghe cronologie di messaggi (ogni risultato di strumento viene appeso), quindi ti servono sia i pesi sia una generosa finestra di contesto in memoria. Un modello più piccolo che sta comodo e gira veloce spesso batte uno più grande che va in swap su disco e si blocca a metà ciclo.

La mossa decisiva non è leggere i benchmark — è eseguire una piccola valutazione (eval) del tuo compito contro due o tre modelli candidati. Un modello che è in cima a una classifica può comunque essere inaffidabile sugli strumenti specifici di cui il tuo agente ha bisogno. Misura sul tuo ciclo.

Framework che girano localmente​

Puoi scrivere a mano il ciclo sopra, e per un primo agente è un ottimo modo per imparare. Per qualsiasi cosa reale, un framework ti dà retry, memoria, coordinamento multi-agente e tracing. Il fatto chiave: i framework di agenti popolari sono agnostici rispetto al modello — non gli importa se il modello è nel cloud o su localhost, purché li punti all'endpoint giusto.

  • LangGraph — un framework di orchestrazione a basso livello per agenti stateful (esecuzione durevole, persistenza, human-in-the-loop). Agnostico rispetto al modello; collegalo a un modello locale tramite l'integrazione LangChain Ollama senza workaround. Buono quando ti serve controllo esplicito sul grafo di stato dell'agente.
  • CrewAI — un framework di più alto livello per orchestrare uno o più agenti basati su ruoli ("crew"). Agnostico rispetto al modello tramite LiteLLM; punta un agente a un modello locale con LLM(model="ollama/llama3.1", base_url="http://localhost:11434"). Buono quando vuoi comporre rapidamente più agenti cooperanti.
  • OpenAI Agents SDK — un framework multi-agente leggero. Nonostante il nome è agnostico rispetto al provider: tramite la sua integrazione LiteLLM puoi puntarlo a un modello Ollama locale invece che a uno OpenAI. Buono quando vuoi l'ergonomia degli agenti di OpenAI su un backend locale.

Scegli un framework e imparalo bene invece di campionarli tutti e tre. I concetti (agenti, strumenti, cicli, stato) si trasferiscono; le API sono dettagli.

Costruisci il tuo primo agente locale​

Un percorso realistico va da "nessun ciclo affatto" a "ciclo autonomo protetto" in passi deliberati. Non saltare al passo 4 — la maggior parte dei fallimenti che la gente incontra con gli agenti locali viene dal dare troppa corda a un modello debole troppo presto.

Guided walkthrough1 of 5
  1. Installa Ollama (vedi Eseguire modelli localmente), poi scarica un modello taggato per gli strumenti, es. ollama pull llama3.1. Conferma che serva su http://localhost:11434 e che ollama list lo mostri. Ancora nessun agente — solo un modello che puoi chiamare.
Watch out
  • Un agente locale con strumenti può comunque compiere azioni reali — mettilo in sandbox, richiedi approvazione per i passi distruttivi, e metti un cap ai suoi cicli/budget.

Mettiti alla prova​

Mettiti alla prova

0/4
  1. Qual è la singola ragione più importante per cui i team costruiscono agenti che girano localmente invece che contro un'API cloud?
  2. Quali quattro parti compongono l'architettura minima di agente locale?
  3. Cosa significa che LangGraph, CrewAI e l'OpenAI Agents SDK sono 'agnostici rispetto al modello' per l'uso locale?
  4. Stai costruendo il tuo primo agente locale. Cosa dovresti fare PRIMA di aggiungere qualsiasi strumento che scrive file o esegue comandi?
Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 6
Key takeaways
  • Un agente locale è lo standard ciclo di uso di strumenti con il modello cloud scambiato per un modello a pesi aperti sulla tua macchina — privato, offline, e gratuito da iterare.
  • Architettura minima = modello locale capace di strumenti + ciclo di tool-calling + strumenti + un guardrail/condizione di stop. Il ciclo stesso è minuscolo.
  • L'endpoint OpenAI-compatibile di Ollama (/v1) supporta il tool calling, quindi qualsiasi framework in formato OpenAI può guidare un modello locale.
  • LangGraph, CrewAI e l'OpenAI Agents SDK sono agnostici rispetto al modello — puntali a un endpoint locale invece che al cloud.
  • Scegli un modello capace di strumenti che stia nel tuo hardware, poi decidi con una piccola eval del tuo compito — non una classifica.
  • Sii onesto sul divario di capacità e possiedi la sicurezza: metti cap a cicli e budget, sandbox degli strumenti, e richiedi approvazione per qualsiasi cosa distruttiva.
  • Inizia semplice: una chiamata a strumento pulita → ciclo di sola lettura delimitato → strumenti distruttivi protetti → (opzionalmente) un framework.

Fonti e approfondimenti​