Framework per agenti AI: LangGraph, CrewAI, OpenAI e Claude SDK

Aggiornamento (9 novembre 2026): sono usciti Claude Fable 5.2 e Mythos 5.2 - prezzi, accesso e benchmark nella mia guida a Claude Fable 5.2.

👁 113 letture

Ho scritto lo stesso agente AI cinque volte: senza framework, con OpenAI Agents SDK, LangGraph, CrewAI e Claude Agent SDK. Ciascuna versione ha ricevuto gli stessi tre strumenti e lo stesso identico compito: ho misurato righe di codice, tempo di esecuzione, numero di richieste al modello e costi. La risposta sintetica: per imparare e per agenti semplici la soluzione migliore è un ciclo personalizzato o l’OpenAI Agents SDK; LangGraph vince sui flussi complessi; CrewAI è ideale per team di agenti con ruoli definiti; Claude Agent SDK eccelle quando l’agente deve operare direttamente sui file come Claude Code. Questa guida fa parte del percorso Agenti AI da zero.

Il task di test

L’agente deve calcolare l’importo totale speso per le fatture presenti nella cartella dane/ (due fatture in valuta polacca e una da 120 EUR), convertendo l’euro in base al tasso corrente ufficiale della banca centrale polacca NBP. Il risultato corretto è 3919,74 unità di valuta originale polacca. Abbiamo testato il prompt e i documenti in polacco. Gli strumenti sono identici per tutte le versioni e sono isolati in un file separato:

• szukaj_plikow: cerca e legge il contenuto dei file .txt nella cartella;
• kalkulator: esegue in modo sicuro le operazioni aritmetiche;
• czytaj_strone: scarica una pagina web o la risposta di un’API.

"""Strumenti condivisi da tutte le versioni dell'agente (funzioni Python pure, senza framework)."""
import ast, operator, pathlib
import requests
from bs4 import BeautifulSoup

KATALOG = (pathlib.Path(__file__).parent.parent / "dane").resolve()
# Traduzione dell'istruzione originale testata in polacco:
# "Calcola quanto ho speso in totale in zloty per le fatture nella cartella dane.
# Converti la fattura in euro usando il tasso di cambio odierno di NBP."
ZADANIE = ("[Traduzione del testo di prova polacco originale: Calcola quanto ho speso in totale in zloty per le fatture nella cartella dane. "
           "Converti la fattura in euro usando il tasso di cambio odierno di NBP.]")
# Traduzione del prompt di sistema testato:
# "Risolvi il compito usando gli strumenti. Tassi di cambio: https://api.nbp.pl/api/exchangerates/rates/a/{kod}/?format=json.
# Esegui i calcoli sempre con il calcolatore. Rispondi in polacco, brevemente."
INSTRUKCJA = ("[Traduzione del testo di prova polacco originale: Risolvi il compito usando gli strumenti. Tassi di cambio: https://api.nbp.pl/api/exchangerates/rates/a/{kod}/?format=json. "
              "Esegui i calcoli sempre con il calcolatore. Rispondi in polacco, brevemente.]")

def szukaj_plikow(fraza: str = "") -> str:
    """Mostra i file .txt nella cartella dane/ e il loro contenuto. Stringa vuota = tutti i file."""
    out = [f"== {p.relative_to(KATALOG)} ==\n{p.read_text(encoding='utf-8')[:1500]}"
           for p in sorted(KATALOG.rglob("*.txt")) if fraza.lower() in p.read_text(encoding="utf-8").lower()]
    return "\n".join(out) 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:
    """Calcola un'espressione aritmetica, ad es. 2214+1180.8."""
    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:
    """Recupera il testo di una pagina web o la risposta API da un URL."""
    r = requests.get(url, timeout=20, headers={"User-Agent": "agenti-starter/1.0"})
    return BeautifulSoup(r.text, "html.parser").get_text(" ", strip=True)[:4000]

Questo approccio consente di valutare esclusivamente l’overhead introdotto dal framework e non quello degli strumenti stessi. I dettagli sul funzionamento interno del ciclo di un agente sono descritti nell’articolo su come creare un agente AI in Python.

Risultati dei test

Parametri di misurazione (stime monetarie al tasso BCE del 12/10/2026, 1 EUR = 1,1181 USD):

• Righe di codice: righe non vuote e prive di commenti, escludendo il file comune degli strumenti.
• Tempo: dall’avvio del processo Python fino all’output finale, includendo l’import delle librerie. Media su 3 esecuzioni.
• Dipendenze: pacchetti installati da pip per risolvere l’ambiente su Python 3.13.
• Costo: valore complessivo del campo cost restituito da OpenRouter a ogni richiesta.

Cosa emerge dall’analisi:

• Su un task semplice, il framework influisce minimamente sul costo. I test con il modello Luna si attestano tra 0,00055 EUR (0,00062 USD) e 0,00074 EUR (0,00083 USD). OpenAI Agents SDK e CrewAI hanno talvolta richiesto un quarto passaggio (suddividendo i calcoli anziché risolverli in un’unica chiamata), aumentando leggermente la media.
• Claude Agent SDK risulta notevolmente più costoso e lento, a causa sia del modello sia del framework. La prova di controllo mostra chiaramente la suddivisione: lo stesso Haiku eseguito in un ciclo essenziale senza framework è costato circa 0,0063 EUR (0,0071 USD), mentre su Claude Agent SDK ha raggiunto circa 0,0133 EUR (0,0149 USD). Circa la metà della spesa aggiuntiva deriva dalla logica interna di Claude Code (prompt di sistema più prolissi e fasi di reasoning prima di ogni azione).
• CrewAI comporta il maggior numero di dipendenze (137 pacchetti, pari a circa 790 MB di ambiente virtuale) e tempi di import più lunghi. È consigliabile eseguirlo in un ambiente isolato per prevenire conflitti tra versioni.

1. Senza framework: 16 righe

import json, os
from openai import OpenAI
from narzedzia import ZADANIE, INSTRUKCJA, szukaj_plikow, kalkulator, czytaj_strone

client = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"])
FUNKCJE = {f.__name__: f for f in (szukaj_plikow, kalkulator, czytaj_strone)}
TOOLS = [{"type": "function", "function": {"name": n, "description": f.__doc__, "parameters": {"type": "object",
          "properties": {p: {"type": "string"} for p in f.__annotations__ if p != "return"}}}} for n, f in FUNKCJE.items()]

messages = [{"role": "system", "content": INSTRUKCJA}, {"role": "user", "content": ZADANIE}]
for krok in range(8):
    msg = client.chat.completions.create(model=os.environ["MODEL"], messages=messages, tools=TOOLS).choices[0].message
    messages.append(msg.model_dump(exclude_none=True))
    if not msg.tool_calls:
        print(msg.content); break
    for c in msg.tool_calls:
        wynik = FUNKCJE[c.function.name](**json.loads(c.function.arguments or "{}"))
        messages.append({"role": "tool", "tool_call_id": c.id, "content": wynik})

La logica è completamente esposta: gestione dello storico messaggi, ciclo di controllo ed esecuzione delle funzioni. Gli schemi dei tool derivano direttamente dai docstring. Mancano sistemi di logging, retry automatici in caso di errore di rete e validazione avanzata dei parametri: elementi che in un progetto di produzione richiedono circa 30-50 righe extra, come illustrato nella versione completa dell’agente.

2. OpenAI Agents SDK: 10 righe

import os
from openai import AsyncOpenAI
from agents import Agent, OpenAIChatCompletionsModel, Runner, function_tool, set_tracing_disabled
from narzedzia import ZADANIE, INSTRUKCJA, szukaj_plikow, kalkulator, czytaj_strone

set_tracing_disabled(True)
model = OpenAIChatCompletionsModel(model=os.environ["MODEL"], openai_client=AsyncOpenAI(
    base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"]))
agent = Agent(name="Fatture", instructions=INSTRUKCJA, model=model,
              tools=[function_tool(f) for f in (szukaj_plikow, kalkulator, czytaj_strone)])
print(Runner.run_sync(agent, ZADANIE, max_turns=8).final_output)

È la sintassi più compatta ed efficace. function_tool costruisce lo schema dalla firma della funzione, mentre Runner.run_sync gestisce il ciclo con una soglia massima max_turns. Include nativamente funzionalità per handover multi-agente, guardrail, sessioni e tracciamento. Con OpenRouter è necessario disattivare il tracing e incapsulare il client in OpenAIChatCompletionsModel, poiché l’SDK punta per impostazione predefinita alle API Responses proprietarie di OpenAI.

3. LangGraph: 19 righe

import os
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState, START
from langgraph.prebuilt import ToolNode, tools_condition
from narzedzia import ZADANIE, INSTRUKCJA, szukaj_plikow, kalkulator, czytaj_strone

narzedzia = [szukaj_plikow, kalkulator, czytaj_strone]
llm = ChatOpenAI(model=os.environ["MODEL"], base_url="https://openrouter.ai/api/v1",
                 api_key=os.environ["OPENROUTER_API_KEY"]).bind_tools(narzedzia)

def model(stan: MessagesState):
    return {"messages": [llm.invoke(stan["messages"])]}

graf = StateGraph(MessagesState)
graf.add_node("model", model)
graf.add_node("tools", ToolNode(narzedzia))
graf.add_edge(START, "model")
graf.add_conditional_edges("model", tools_condition)  # se ci sono tool_calls -> "tools", altrimenti -> fine
graf.add_edge("tools", "model")
agent = graf.compile()

wynik = agent.invoke({"messages": [("system", INSTRUKCJA), ("user", ZADANIE)]}, {"recursion_limit": 16})
print(wynik["messages"][-1].content)

Richiede più codice, ma il grafo è stato volutamente costruito in modo esplicito anziché ricorrere a helper predefiniti. Questa struttura chiarisce i fondamenti di LangGraph: stato (lista dei messaggi), nodi (modello e strumenti) e archi (la condizione per verificare se il modello ha richiesto un tool). Per un agente singolo può apparire ridondante; diventa invece determinante nei flussi articolati che richiedono rami condizionali, approvazione umana (human-in-the-loop), persistenza e ripresa automatica dopo un crash. Il limite di iterazioni è controllato da recursion_limit.

4. CrewAI: 10 righe

import os
from crewai import Agent, Task, Crew, LLM
from crewai.tools import tool
from narzedzia import ZADANIE, INSTRUKCJA, szukaj_plikow, kalkulator, czytaj_strone

llm = LLM(model="openrouter/" + os.environ["MODEL"], base_url="https://openrouter.ai/api/v1",
          api_key=os.environ["OPENROUTER_API_KEY"])
ksiegowy = Agent(role="Contabile", goal="Calcolare le spese dalle fatture", backstory=INSTRUKCJA, llm=llm,
                 tools=[tool(f) for f in (szukaj_plikow, kalkulator, czytaj_strone)], max_iter=8, verbose=False)
zadanie = Task(description=ZADANIE, expected_output="Somma totale con breve calcolo", agent=ksiegowy)
print(Crew(agents=[ksiegowy], tasks=[zadanie]).kickoff().raw)

CrewAI modella il workflow su concetti organizzativi: ogni agente possiede un ruolo, un obiettivo e un backstory, mentre ogni task definisce istruzioni e output atteso. Per un unico agente la struttura è cerimoniosa, ma in scenari multi-agente (ad esempio un ricercatore che aggrega dati, un redattore che scrive e un revisore che valida) l’architettura risulta intuitiva anche per profili non tecnici. Il modello richiede il prefisso del provider (in questo caso openrouter/). CrewAI richiede Python tra 3.10 e 3.13.

5. Claude Agent SDK: 24 righe

import asyncio, os
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, create_sdk_mcp_server, query, tool
from narzedzia import ZADANIE, INSTRUKCJA, szukaj_plikow, kalkulator, czytaj_strone

def owin(f, param):  # converte una funzione Python in un tool SDK (restituisce blocchi di testo)
    @tool(f.__name__, f.__doc__, {param: str})
    async def t(args):
        return {"content": [{"type": "text", "text": f(args.get(param, ""))}]}
    return t

serwer = create_sdk_mcp_server("faktury", tools=[owin(szukaj_plikow, "fraza"), owin(kalkulator, "wyrazenie"),
                                                 owin(czytaj_strone, "url")])
opcje = ClaudeAgentOptions(system_prompt=INSTRUKCJA, model=os.environ.get("CLAUDE_MODEL", "anthropic/claude-haiku-4.5"),
                           mcp_servers={"faktury": serwer}, strict_mcp_config=True,
                           tools=[],  # disattiva i tool integrati di Claude Code (Bash, Edit, ecc.)
                           allowed_tools=["mcp__faktury__szukaj_plikow", "mcp__faktury__kalkulator",
                                          "mcp__faktury__czytaj_strone"], max_turns=8,
                           cli_path=os.getenv("CLAUDE_CLI"),  # Windows: percorso verso claude.exe (evitare claude.cmd)
                           setting_sources=[],  # ignora ~/.claude/settings.json per evitare sovrascritture di ANTHROPIC_BASE_URL
                           env={"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",  # Claude tramite OpenRouter
                                "ANTHROPIC_AUTH_TOKEN": os.environ["OPENROUTER_API_KEY"], "ANTHROPIC_API_KEY": ""})

async def main():
    async for m in query(prompt=ZADANIE, options=opcje):
        if isinstance(m, ResultMessage):
            print(m.result)
asyncio.run(main())

È la variante che necessita di più configurazione iniziale, poiché il Claude Agent SDK include l’intero motore di Claude Code impacchettato come libreria. I tool personalizzati vengono integrati come server MCP in-memory (tramite create_sdk_mcp_server), mentre le utility native (Bash, modifica file) sono state disattivate impostando tools=[]. Tre aspetti tecnici da considerare durante l’integrazione:

• su Windows l’SDK fallisce se punta a claude.cmd generato da npm: occorre indicare il path assoluto dell’eseguibile claude.exe tramite cli_path;
• senza setting_sources=[], la libreria carica le preferenze da ~/.claude/settings.json, sovrascrivendo l’endpoint specificato e causando errori HTTP 403;
• su OpenRouter, Claude Code deve puntare all’endpoint compatibile con l’API Anthropic (ANTHROPIC_BASE_URL=https://openrouter.ai/api), inoltrando la chiave in ANTHROPIC_AUTH_TOKEN.

Confronto: quale framework scegliere

Il panorama comprende altri strumenti: Google propone ADK (Agent Development Kit, versione 2.11.0 su PyPI), Hugging Face sviluppa smolagents (1.26.0) e Microsoft mantiene il proprio Agent Framework. Nessuno di questi è stato incluso in questa tornata di test. Per contesti no-code, le alternative più diffuse sono n8n (con il nodo AI Agent) e Gumloop.

Consigli pratici

1. Inizia implementando un agente senza framework: comprendere i passaggi sottostanti evita di procedere per tentativi quando si adottano librerie astratte.
2. Per il primo progetto applicativo, OpenAI Agents SDK offre il compromesso più pulito tra funzionalità e complessità, funzionando con OpenRouter e modelli in locale.
3. Adotta LangGraph quando il flusso di lavoro richiede diagrammi a blocchi con diramazioni condizionali complesse e gestione dello stato persistente.
4. Riserva CrewAI e Claude Agent SDK a casi d’uso mirati: coordinamento di ruoli verticali nel primo caso, interazione profonda con file e terminale nel secondo.

Domande frequenti

Meglio LangChain o LangGraph?

LangChain raccoglie componenti modulari (connettori per modelli, tool, parser), mentre LangGraph gestisce l’orchestrazione del flusso mediante grafi di stato. Nelle release 1.x, LangChain adotta internamente LangGraph per l’esecuzione degli agenti. Per chi comincia oggi è preferibile partire da LangGraph, importando da LangChain solo le librerie di integrazione strettamente necessarie come langchain-openai.

I framework per agenti AI sono gratuiti?

Tutti e cinque i framework analizzati sono open source e liberamente utilizzabili; il costo effettivo riguarda il consumo dei token dei modelli. Eventuali costi aggiuntivi riguardano servizi enterprise opzionali come LangSmith per LangGraph o i piani cloud dedicati di CrewAI.

Quali framework supportano modelli locali?

L’approccio senza framework, l’OpenAI Agents SDK, LangGraph e CrewAI possono collegarsi a modelli locali tramite Ollama o qualsiasi interfaccia compatibile con l’API di OpenAI. Claude Agent SDK supporta unicamente i modelli della famiglia Claude.

Un framework migliora la qualità dell’agente?

Nei test effettuati non è emersa alcuna differenza qualitativa: tutte le implementazioni hanno restituito il medesimo risultato. La precisione finale dipende dal modello, dalla qualità dei docstring associati ai tool e dai dati in ingresso. Il framework fornisce esclusivamente ordine architetturale, logging e robustezza attorno al ciclo di esecuzione.

Quanto è costata la sessione complessiva di benchmark?

Le 16 esecuzioni (15 di test e 1 di controllo) hanno totalizzato un costo di circa 0,054 EUR (0,060 USD), di cui circa 0,046 EUR (0,052 USD) imputabili ai soli test con Claude Haiku (stime al tasso BCE del 12/10/2026: 1 EUR = 1,1181 USD; ecb.europa.eu).

Dove approfondire lo studio di ciascun framework?

Tra le risorse formative gratuite spiccano la LangChain Academy (con il percorso Intro to LangGraph), i corsi DeepLearning.AI dedicati ad agenti e sistemi multi-agente, nonché le guide ufficiali di OpenAI Agents SDK e Claude Agent SDK. Una rassegna completa è consultabile nella sezione dedicata del nostro hub informativo.

Fonti e dettagli dei test

• Documentazione ufficiale: OpenAI Agents SDK, LangChain Academy: Intro to LangGraph, CrewAI docs, Claude Agent SDK (verificate il 4/10/2026).
• Versioni pacchetti: PyPI, verificate il 4/10/2026.
• Ambiente di benchmark: test eseguiti in locale (Windows 11, Python 3.13) il 4 ottobre 2026 tra le 13:53 e le 13:57. Il codice di tutte le varianti è accessibile nel pacchetto di partenza archivio starter agenti all’interno della cartella frameworki/.

// continua a leggereClaude Code rilancia Projects: più agenti AI coordinati in cloudNotizieAgenti OpenAI hanno vandalizzato un sito tedesco prima dell’hackathon di Hugging FaceNotizieTassa token 2026: testo polacco costa 56% in più con Claude vs OpenAIBenchmark

Kinetyra