Come creare un agente AI in Python: guida passo passo

👁 113 letture

Un agente AI in Python è essenzialmente un loop: il modello riceve un obiettivo e un elenco di strumenti, ne seleziona uno, il tuo codice lo esegue, il risultato ritorna al modello e quest’ultimo decide cosa fare dopo. Ho sviluppato un agente funzionante in sole 76 righe, senza alcun framework: cerca file, fa calcoli, scarica pagine web, gestisce un limite massimo di passaggi e salva un registro dettagliato delle decisioni. Poi ho riscritto la stessa logica utilizzando l’OpenAI Agents SDK e il Claude Agent SDK. Tutte le esecuzioni mostrate sotto sono state effettuate realmente il 4 ottobre 2026. Questa è la terza tappa del percorso Agenti AI da zero.

In cosa un agente differisce da un normale script con AI

Uno script convenzionale con intelligenza artificiale esegue passaggi rigidi e predeterminati: “scarica l’email, riassumi, salva”. Il modello si limita a completare un singolo passaggio logico. In un agente, invece, è il modello stesso a stabilire la sequenza delle azioni. Riceve un obiettivo (“calcola i totali delle fatture”) e un set di strumenti; decide autonomamente di esplorare prima i file, richiedere un tasso di cambio aggiornato e infine calcolare il totale. Approfondisco la natura degli agenti e i loro limiti nell’articolo Agente AI: che cos’è.

Sul piano tecnico, un agente è un pattern di function calling incapsulato in un ciclo di controllo. Se non conosci il meccanismo con cui un LLM richiede l’invocazione di funzioni esterne, ti consiglio di leggere prima quella guida.

Il ciclo dell’agente in quattro passaggi

1. Modello: analizza la richiesta e lo storico della conversazione.
2. Decisione: richiede l’esecuzione di un tool (con argomenti specifici) oppure genera la risposta finale se ritiene concluso il compito.
3. Strumento: il codice Python locale esegue la funzione richiesta.
4. Osservazione: l’output della funzione viene inserito nella cronologia e il ciclo riparte dal punto 1.

A questo schema aggiungo due misure di sicurezza indispensabili: un limite massimo di iterazioni (per evitare loop infiniti e sprechi di budget) e un registro delle decisioni (per monitorare esattamente cosa è accaduto e perché).

Passo 1: configurazione dell’ambiente

1. Installa Python (versione 3.11-3.13) da python.org (ricorda di selezionare “Add python.exe to PATH”).
2. Nella cartella di lavoro crea l’ambiente virtuale: python -m venv .venv, quindi attivalo con .venv\Scripts\activate.
3. Installa le librerie necessarie: pip install openai requests beautifulsoup4 python-dotenv.
4. Genera una chiave API su OpenRouter e inseriscila nel file .env come OPENROUTER_API_KEY=.... Imposta un massimale di credito, ad esempio circa 1,79 EUR (2 USD). Il funzionamento e i costi della piattaforma sono descritti nell’articolo su OpenRouter.
5. Crea la directory dane/faktury e inserisci alcuni file di testo di test. Nel pacchetto di prova abbiamo incluso tre documenti simulati, di cui uno con importo in EUR.

Passo 2: definire i tool come funzioni native

L’agente ha accesso a tre strumenti. Ognuno è una classica funzione Python che restituisce una stringa:

• szukaj_plikow: visualizza i file .txt all’interno della cartella dane/. L’agente non può accedere all’esterno di questo percorso;
• kalkulator: risolve operazioni matematiche tramite il modulo ast (evitando il rischioso eval). Poiché i modelli tendono a sbagliare nell’aritmetica diretta, è opportuno delegare i calcoli a un interprete;
• czytaj_strone: scarica una pagina web o una risposta API, limitando l’output a 4000 caratteri per controllare il consumo di token.

Passo 3: il codice completo dell’agente in 76 righe

"""02 - Agente AI minimale senza framework: ciclo modello -> tool -> osservazione -> decisione.
Esecuzione: python 02_agent_bez_frameworka.py "Somma gli importi lordi delle fatture nella cartella dane/faktury."
"""
import ast, json, operator, os, pathlib, sys, time
import requests
from bs4 import BeautifulSoup
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
MODEL, MAX_KROKOW = os.getenv("MODEL", "openai/gpt-5.6-luna"), int(os.getenv("MAX_KROKOW", 8))
client = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"])
KATALOG = pathlib.Path("dane").resolve()  # l'agente ha accesso solo a questa directory

def szukaj_plikow(fraza: str = "") -> str:
    """Elenco dei file in dane/ (con contenuto), filtrabili per parola chiave."""
    wynik = []
    for p in sorted(KATALOG.rglob("*.txt")):
        tekst = p.read_text(encoding="utf-8")
        if fraza.lower() in tekst.lower() or fraza.lower() in p.name.lower():
            wynik.append(f"== {p.relative_to(KATALOG)} ==\n{tekst[:1500]}")
    return "\n".join(wynik) or "nessun file trovato"

OPS = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.USub: operator.neg}
def kalkulator(wyrazenie: str) -> str:
    def licz(n):
        if isinstance(n, ast.Constant): return n.value
        if isinstance(n, ast.BinOp): return OPS[type(n.op)](licz(n.left), licz(n.right))
        if isinstance(n, ast.UnaryOp): return OPS[type(n.op)](licz(n.operand))
        raise ValueError("consentiti solo numeri e operatori + - * /")
    return str(round(licz(ast.parse(wyrazenie, mode="eval").body), 4))

def czytaj_strone(url: str) -> str:
    r = requests.get(url, timeout=20, headers={"User-Agent": "starter-agenti/1.0"})
    tekst = BeautifulSoup(r.text, "html.parser").get_text(" ", strip=True)
    return tekst[:4000]  # troncamento: contenuti lunghi consumano token rapidamente

NARZEDZIA = {"szukaj_plikow": szukaj_plikow, "kalkulator": kalkulator, "czytaj_strone": czytaj_strone}
def opis(nazwa, tekst, param, typ="string"):
    return {"type": "function", "function": {"name": nazwa, "description": tekst,
            "parameters": {"type": "object", "properties": {param: {"type": typ}}, "required": [param]}}}
TOOLS = [opis("szukaj_plikow", "Mostra i file .txt della cartella dane/ e il loro contenuto. Stringa vuota = tutti i file.", "fraza"),
         opis("kalkulator", "Risolve espressioni matematiche, es. 2214+1180.8. Usa sempre questo strumento per i calcoli.", "wyrazenie"),
         opis("czytaj_strone", "Recupera il contenuto testuale di una pagina web o una risposta API da un URL.", "url")]

def agent(zadanie: str) -> str:
    messages = [{"role": "system", "content": "Sei un agente AI. Risolvi il compito usando gli strumenti a disposizione. Prima di "
                 "chiamare un tool, spiega in una frase perche lo usi. Recupera i tassi di cambio dall'API NBP: "
                 "https://api.nbp.pl/api/exchangerates/rates/a/{kod}/?format=json."},
                {"role": "user", "content": zadanie}]
    log = open("agent_log.jsonl", "a", encoding="utf-8")
    koszt = 0.0
    for krok in range(1, MAX_KROKOW + 1):
        r = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS)
        koszt += getattr(r.usage, "cost", 0) or 0
        msg = r.choices[0].message
        messages.append(msg.model_dump(exclude_none=True))
        if not msg.tool_calls:
            print(f"--- completato in {krok} passaggi, costo {koszt:.5f} USD")
            return msg.content
        if msg.content: print(f"[step {krok}] PENSIERO: {msg.content.strip()[:300]}")
        for call in msg.tool_calls:
            args = json.loads(call.function.arguments or "{}")
            try:
                obs = NARZEDZIA[call.function.name](**args)
            except Exception as e:
                obs = f"ERRORE: {e}"
            print(f"[step {krok}] AZIONE: {call.function.name}({json.dumps(args, ensure_ascii=False)})")
            print(f"[step {krok}] OSSERVAZIONE: {obs[:160]!r}")
            log.write(json.dumps({"t": time.strftime("%H:%M:%S"), "step": krok, "tool": call.function.name,
                                  "args": args, "osservazione": obs[:500]}, ensure_ascii=False) + "\n")
            messages.append({"role": "tool", "tool_call_id": call.id, "content": obs})
    return f"Interrotto: raggiunto il limite di {MAX_KROKOW} passaggi (costo {koszt:.5f} USD)."

if __name__ == "__main__":
    print("\nRISULTATO:\n" + agent(" ".join(sys.argv[1:]) or "Somma gli importi lordi delle fatture nella cartella dane/faktury."))

Elementi strutturali fondamentali del codice:

• for krok in range(1, MAX_KROKOW + 1): è il ciclo principale con limite rigido di iterazioni (valore predefinito: 8);
• if not msg.tool_calls: se il modello non richiede chiamate a funzioni, significa che ha prodotto la risposta conclusiva;
• la gestione degli errori nei tool non causa l’arresto dello script: l’eccezione viene passata al modello come “ERRORE: …”, consentendogli di tentare una correzione autonoma;
• ogni azione viene tracciata in agent_log.jsonl (orario, passaggio, strumento invocato, argomenti e output restituito);
• il prompt di sistema obbliga il modello a verbalizzare il motivo dell’uso del tool in una frase. Questo “pensiero” finisce nei log e semplifica notevolmente il debug.

Test 1: gestione di fatture multivaluta

Abbiamo eseguito il test originario in lingua polacca con una richiesta volta a sommare importi di fatture e convertire una cifra espressa in euro:

> python 02_agent_bez_frameworka.py "[Traduzione del test polacco: Calcola il totale speso nelle fatture della cartella dane, convertendo la fattura in euro con il tasso NBP odierno]"
[step 1] PENSIERO: Leggero prima i file delle fatture dalla cartella `dane` e scarichero il tasso EUR aggiornato dall'API NBP per sommare gli importi.
[step 1] AZIONE: szukaj_plikow({"fraza": ""})
[step 1] OSSERVAZIONE: '== faktury\\FV_2026_09_014.txt ==\nFAKTURA VAT nr FV/2026/09/014 (dati di esempio)\nData emissione: 2026-09-12\nFornitore: Esempio S.r.l.\nAcquirente'
[step 1] AZIONE: czytaj_strone({"url": "https://api.nbp.pl/api/exchangerates/rates/a/eur/?format=json"})
[step 1] OSSERVAZIONE: '{"table":"A","currency":"euro","code":"EUR","rates":[{"no":"192/A/NBP/2026","effectiveDate":"2026-10-02","mid":4.3745}]}'
[step 2] PENSIERO: Ora converto la fattura da 120 EUR con il tasso di 4,3745 e sommo le altre due fatture da 2214,00 e 1180,80.
[step 2] AZIONE: kalkulator({"wyrazenie": "2214+1180.8+120*4.3745"})
[step 2] OSSERVAZIONE: '3919.74'
--- completato in 3 passaggi, costo 0.00104 USD (circa 0,00093 EUR; tasso BCE del 12/10/2026)

RISULTATO (tradotto dal log polacco):
In totale hai speso 3 919,74.

Dettaglio:
- Fattura 1: 2 214,00
- Fattura 2: 1 180,80
- Fattura in EUR: 120 * 4,3745 = 524,94

Totale: 2 214,00 + 1 180,80 + 524,94 = 3 919,74
Tasso EUR NBP applicato: 4,3745 (del 02/10/2026).

L’agente ha organizzato la sequenza in autonomia: al passaggio 1 ha ispezionato i file ed eseguito la query per il cambio valuta. Al passaggio 2 ha formulato l’espressione corretta delegandola al calcolatore. Al passaggio 3 ha generato il resoconto finale. Il calcolo manuale (2214 + 1180,80 + 120 * 4,3745 = 3919,74) coincide perfettamente. L’elaborazione ha richiesto tre chiamate API con un costo di circa 0,00093 EUR (0,00104 USD).

Test 2: combinare dati web e file locali

Il secondo scenario testato in polacco richiedeva di consultare Wikipedia per spiegare l’MCP e verificare una scadenza all’interno dei file locali:

> python 02_agent_bez_frameworka.py "[Traduzione del prompt polacco: Leggi la voce Wikipedia su Model Context Protocol e riassumi in 3 punti a cosa serve. Poi cerca nei file locali una scadenza e calcola i giorni mancanti rispetto al 4 ottobre 2026]"
[step 1] PENSIERO: Leggo la pagina Wikipedia per riassumere le funzionalita principali di MCP in 3 punti.
[step 1] AZIONE: czytaj_strone({"url": "https://pl.wikipedia.org/wiki/Model_Context_Protocol"})
[step 1] OSSERVAZIONE: 'Model Context Protocol - Wikipedia... Salta al contenuto Menu principale...'
[step 2] PENSIERO: Esploro la cartella dane per rintracciare un appunto con una data di scadenza.
[step 2] AZIONE: szukaj_plikow({"fraza": ""})
[step 2] OSSERVAZIONE: '== faktury\\FV_2026_09_014.txt == ...'
[step 3] PENSIERO: Calcolo la differenza tra il 4 e il 7 ottobre 2026 per indicare i giorni esatti.
[step 3] AZIONE: kalkulator({"wyrazenie": "7-4"})
[step 3] OSSERVAZIONE: '3'
--- completato in 4 passaggi, costo 0.00130 USD (circa 0,00116 EUR; tasso BCE del 12/10/2026)

RISULTATO (tradotto dall'output originale):
MCP serve a:
1. Standardizzare la connessione tra modelli linguistici e strumenti esterni, database o risorse informative.
2. Fornire un'interfaccia universale per la lettura dei file, l'esecuzione di tool e l'uso del contesto.
3. Facilitare l'integrazione dell'AI con ambienti operativi come CRM, file aziendali e IDE.

Nel file `dane/faktury/notatka.txt` e presente la nota: inviare i documenti entro il 7 ottobre 2026.
Dal 4 ottobre 2026 mancano esattamente 3 giorni.

L’agente ha integrato due canali informativi indipendenti. Un dettaglio emerso dal tracciamento: la porzione iniziale della pagina web conteneva elementi di navigazione (“Salta al contenuto…”). Il limite di 4000 caratteri ha comunque permesso di catturare il corpo della voce, ma su pagine complesse è consigliabile filtrare i tag semantici come <main> o <article>. Anche se l’operazione 7 - 4 può sembrare banale, l’uso del tool aritmetico garantisce l’assenza di allucinazioni di calcolo.

Test 3: arresto forzato per limite passaggi

Impostando il tetto a soli 2 cicli operativi e richiedendo anche una conversione supplementare in USD, l’esecuzione si interrompe in sicurezza:

> MAX_KROKOW=2 python 02_agent_bez_frameworka.py "[Traduzione del prompt polacco: Calcola le spese e converti gli importi anche in USD]"
[step 1] PENSIERO: Recupero il contenuto dei file e i tassi EUR e USD per preparare le conversioni.
[step 1] AZIONE: szukaj_plikow({"fraza": ""})
[step 1] OSSERVAZIONE: '== faktury\\FV_2026_09_014.txt == ...'
[step 1] AZIONE: czytaj_strone({"url": "https://api.nbp.pl/api/exchangerates/rates/a/eur/?format=json"})
[step 1] OSSERVAZIONE: '{"table":"A","currency":"euro",...}'
[step 1] AZIONE: czytaj_strone({"url": "https://api.nbp.pl/api/exchangerates/rates/a/usd/?format=json"})
[step 1] OSSERVAZIONE: '{"table":"A","currency":"dollaro USA",...}'
[step 2] PENSIERO: Calcolo il controvalore complessivo intermedio.
[step 2] AZIONE: kalkulator({"wyrazenie": "2214+1180.80+120*4.3745"})
[step 2] OSSERVAZIONE: '3919.74'

RISULTATO:
Interrotto: raggiunto il limite di 2 passaggi (costo 0.00079 USD, pari a circa 0,00071 EUR; fonte BCE 12/10/2026).

Non avendo tempo per completare la conversione in USD, l’agente è stato bloccato dal vincolo di sicurezza, fornendo un messaggio esplicito. Negli scenari di produzione è preferibile impostare un margine più ampio (8-15 passaggi) e salvare l’intero contesto su log per poter ripristinare il flusso. Ecco la traccia salvata nel file JSON:

> type agent_log.jsonl   (ultimi 3 record)
{"t": "13:50:52", "step": 1, "tool": "czytaj_strone", "args": {"url": "https://api.nbp.pl/api/exchangerates/rates/a/eur/?format=json"}, "osservazione": "{\"table\":\"A\",\"currency\":\"euro\",\"code\":\"EUR\",\"rates\":[{\"no\":\"192/A/NBP/2026\",\"effectiveDate\":\"2026-10-02\",\"mid\":4.3745}]}"}
{"t": "13:50:52", "step": 1, "tool": "czytaj_strone", "args": {"url": "https://api.nbp.pl/api/exchangerates/rates/a/usd/?format=json"}, "osservazione": "{\"table\":\"A\",\"currency\":\"(traduzione dal test polacco originale: dollaro statunitense)\",\"code\":\"USD\",\"rates\":[{\"no\":\"192/A/NBP/2026\",\"effectiveDate\":\"2026-10-02\",\"mid\":3.8881}]}"}
{"t": "13:50:56", "step": 2, "tool": "kalkulator", "args": {"wyrazenie": "2214+1180.80+120*4.3745"}, "osservazione": "3919.74"}

Problemi tipici degli agenti (e come risolverli)

Lo stesso agente implementato con OpenAI Agents SDK

Dopo aver compreso la logica del ciclo di controllo, le librerie dedicate appaiono molto più lineari. L’OpenAI Agents SDK ricalca esattamente la logica delle 76 righe precedenti: interroga l’LLM, esegue le funzioni, controlla la soglia di turni (max_turns) e raccoglie la telemetria. Inoltre, genera automaticamente lo schema JSON delle funzioni esaminando parametri e docstring (tramite il decoratore @function_tool). Il sistema può essere utilizzato anche con provider terzi specificando un client compatibile puntato su OpenRouter:

"""03 - Lo stesso agente dello script 02, ma implementato con OpenAI Agents SDK (openai-agents).
Il ciclo, le chiamate ai tool e il controllo dei passaggi sono gestiti da Runner.
Esecuzione: python 03_agent_openai_sdk.py "Calcola il totale delle fatture nella cartella dane."
"""
import asyncio, os, sys
from dotenv import load_dotenv
from openai import AsyncOpenAI
from agents import Agent, OpenAIChatCompletionsModel, Runner, function_tool, set_tracing_disabled

import importlib
narz = importlib.import_module("02_agent_bez_frameworka")  # riutilizzo dei medesimi tool

load_dotenv()
set_tracing_disabled(True)  # la telemetria invia log a OpenAI: la disattiviamo usando OpenRouter
model = OpenAIChatCompletionsModel(
    model=os.getenv("MODEL", "openai/gpt-5.6-luna"),
    openai_client=AsyncOpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"]))

@function_tool
def szukaj_plikow(fraza: str = "") -> str:
    """Mostra i file .txt della cartella dane/ e il loro contenuto. Stringa vuota = tutti i file."""
    return narz.szukaj_plikow(fraza)

@function_tool
def kalkulator(wyrazenie: str) -> str:
    """Risolve espressioni matematiche, es. 2214+1180.8. Usa sempre questo strumento."""
    return narz.kalkulator(wyrazenie)

@function_tool
def czytaj_strone(url: str) -> str:
    """Recupera il contenuto testuale di una pagina web o una risposta API da un URL."""
    return narz.czytaj_strone(url)

agent = Agent(
    name="Assistente fatture",
    instructions="Risolvi il compito usando i tool. API tassi di cambio: https://api.nbp.pl/api/exchangerates/rates/a/{kod}/?format=json.",
    model=model, tools=[szukaj_plikow, kalkulator, czytaj_strone])

async def main():
    zadanie = " ".join(sys.argv[1:]) or "Calcola il totale delle fatture nella cartella dane."
    wynik = await Runner.run(agent, zadanie, max_turns=8)
    for item in wynik.new_items:  # monitoraggio degli eventi intermedi
        if item.type == "tool_call_item":
            print("AZIONE:", item.raw_item.name, item.raw_item.arguments)
        elif item.type == "tool_call_output_item":
            print("OSSERVAZIONE:", str(item.output)[:120].replace("\n", " "))
    u = wynik.context_wrapper.usage
    print(f"\nRISULTATO:\n{wynik.final_output}\n\nchiamate al modello: {u.requests}, token: {u.input_tokens} in / {u.output_tokens} out")

asyncio.run(main())

> python 03_agent_openai_sdk.py "[Traduzione del prompt polacco: Calcola la spesa totale delle fatture convertendo l'importo in euro]"
AZIONE: szukaj_plikow {"fraza":""}
AZIONE: czytaj_strone {"url":"https://api.nbp.pl/api/exchangerates/rates/a/EUR/?format=json"}
OSSERVAZIONE: == faktury\FV_2026_09_014.txt == FAKTURA VAT nr FV/2026/09/014 ...
OSSERVAZIONE: {"table":"A","currency":"euro","code":"EUR","rates":[{"no":"192/A/NBP/2026","effectiveDate":"2026-10-02","mid":4.3745}]}
AZIONE: kalkulator {"wyrazenie":"2214+1180.8"}
AZIONE: kalkulator {"wyrazenie":"120*4.3745"}
AZIONE: kalkulator {"wyrazenie":"2214+1180.8+120*4.3745"}
OSSERVAZIONE: 3394.8
OSSERVAZIONE: 524.94
OSSERVAZIONE: 3919.74

RISULTATO (tradotto dal log polacco):
Totale speso: 3 919,74.

Dettaglio:
- Somma fatture: 2 214,00 + 1 180,80 = 3 394,80
- Fattura in EUR: 120 EUR * tasso NBP 4,3745 = 524,94
- Totale complessivo: 3 394,80 + 524,94 = 3 919,74

chiamate al modello: 3, token: 1970 in / 323 out

L’esito è identico: 3 chiamate al modello, 1970 token di ingresso e 323 di output. Due dettagli architetturali importanti:

• set_tracing_disabled(True): per default l’SDK inoltra i dati di telemetria all’infrastruttura OpenAI. In ambienti che sfruttano endpoint proxy o necessitano di riservatezza sui dati aziendali, è preferibile disattivare questo tracciamento;
• OpenAIChatCompletionsModel: la libreria tenta normalmente di comunicare con le Responses API proprietarie. Router esterni (come OpenRouter) implementano invece l’interfaccia Chat Completions; questo wrapper garantisce la compatibilità.

L’implementazione con Claude Agent SDK

Il Claude Agent SDK espone il motore alla base di Claude Code sotto forma di libreria richiamabile. Include di serie il supporto per filesystem e terminale, mentre i tool personalizzati vengono agganciati tramite un server MCP in-memory. Il codice corrispondente è reperibile in frameworki/e_claude_agent_sdk.py, mentre per una disamina comparativa dettagliata puoi consultare l’articolo sui framework per agenti AI. Durante i test su Windows abbiamo rilevato due criticità:

• L’SDK istanzia il processo claude come sottoprocesso e rifiuta per criteri di sicurezza il file claude.cmd generato da npm. Occorre indicare il percorso assoluto di claude.exe tramite cli_path o installare il CLI in modalità binaria nativa;
• Vengono caricate automaticamente le preferenze da ~/.claude/settings.json. In presenza di un ANTHROPIC_BASE_URL custom, il traffico verrà reindirizzato a quell’endpoint. Il parametro setting_sources=[] evita sovrascritture impreviste.

Utilizzando Claude Haiku 4.5 via OpenRouter, l’elaborazione delle fatture ha impiegato tra i 15 e i 18 secondi, registrando un costo di circa 0,012-0,016 EUR (0,013-0,018 USD) su 3 sessioni. Il nostro ciclo manuale di 76 righe con lo stesso Haiku ha richiesto 7,1 secondi e circa 0,006 EUR (0,007 USD). Lo scarto deriva dai prompt operativi aggiuntivi e dai passaggi di riflessione interni eseguiti dall’architettura Claude Code, che in cambio offre strumenti preconfigurati per la gestione di permessi, file system complessi e sub-agenti.

Sviluppo personalizzato o SDK: quale approccio scegliere

• Codice custom: essenziale per comprendere a fondo le dinamiche interne, ottimale per agenti mirati con 2-5 tool e quando serve il pieno controllo sui token;
• OpenAI Agents SDK: la scelta ideale quando occorre gestire passaggi di consegne (handoff) tra agenti multipli, applicare guardrail e tracciare esecuzioni strutturate;
• Claude Agent SDK: indicato per agenti che devono interagire direttamente con file locali, comandi di shell e architetture simili a Claude Code;
• LangGraph: consigliato per flussi a grafo con ramificazioni condizionali, checkpoint persistenti e approvazioni umane (human-in-the-loop);
• Piattaforme no-code: n8n, Make oppure Gumloop se preferisci orchestrare flussi tramite interfacce visuali.

Domande frequenti

Bisogna essere programmatori esperti per creare un agente AI?

Per capire i principi di base basta saper interpretare script Python lineari. Il codice fornito in questa guida si compone di sole 76 righe ed è immediatamente eseguibile. Se non desideri scrivere codice, puoi orientarti su strumenti visivi come n8n o Gumloop.

Quanto costa l’esecuzione di un agente AI?

La spesa è determinata dal costo unitario del modello e dal numero di turni necessari. L’agente di test con un modello economico ha richiesto circa 0,0009 EUR (0,001 USD) a esecuzione. Con Claude Haiku la spesa si è attestata tra 0,006 e 0,016 EUR (0,007-0,018 USD; stime basate su tassi BCE del 12/10/2026: 1 EUR = 1,1181 USD). Con modelli di fascia alta da 5 USD per milione di token, il costo scala sensibilmente poiché a ogni passaggio viene ripresentata l’intera cronologia pregressa.

Quale modello linguistico è più adatto per un agente?

Qualsiasi LLM dotato di un supporto solido per il function calling. Per i primi esperimenti è sufficiente il modello più economico disponibile con filtro “tools” su OpenRouter. Su compiti articolati che richiedono molti passaggi logici, modelli più avanzati garantiscono una tenuta migliore dell’obiettivo iniziale.

Un agente può appoggiarsi a un modello locale?

Certamente. Ollama espone un’interfaccia compatibile con lo standard OpenAI (http://localhost:11434/v1): ti basterà modificare l’attributo base_url e il nome del modello nel codice. Va ricordato che modelli open-source di dimensioni ridotte possono commettere più errori nella formattazione degli argomenti.

Come evitare comportamenti indesiderati o distruttivi dell’agente?

Configura esclusivamente gli strumenti strettamente indispensabili e mantienili in sola lettura ove possibile. Limita i permessi di accesso al filesystem a cartelle specifiche (come nel nostro esempio limitato a dane/). Per operazioni critiche o irreversibili, inserisci sempre un passaggio di conferma manuale da parte dell’utente e traccia ogni iterazione nei file di log.

Gli agenti AI funzionano con prompt in italiano?

Sì. Il ciclo di reasoning e tool calling opera regolarmente anche se istruzioni di sistema, descrizioni delle funzioni e dati di input sono forniti in lingua italiana. È buona norma mantenere i nomi tecnici delle funzioni in caratteri ASCII standard, usando liberamente le lettere accentate nelle descrizioni e nei messaggi.

Fonti e riferimenti

• Anthropic: Building effective agents (consultato il 04/10/2026).
• Documentazione ufficiale di OpenAI Agents SDK (consultata il 04/10/2026).
• Documentazione ufficiale di Claude Agent SDK (consultata il 04/10/2026).
• Tassi di cambio e quotazioni di riferimento: API NBP (Tabella A) e dati valute BCE del 12/10/2026 (ECB reference rates).
• Sessioni di benchmark: esecuzione locale, 4 ottobre 2026, intervallo 13:50-13:55.

// continua a leggerePrima chiamata alle API AI in Python: guida passo passoGuideCome creare video con FLUX 3 Video via API: guida e scriptGuideCome creare video da immagini con Vidu Q4: guida e promptGuide

Kinetyra