Corso sugli agent: lo guardi ma non funziona? Con una sola Key fai girare gli esempi

Su X c'è un post ironico: chi ha speso 500 dollari per un corso sugli AI Agent, ora può guardarlo gratis. Il post originale: https://x.com/deanwperkins/status/2116911546282733623 (autore Dean W. Perkins, @deanwperkins). Il consenso nella discussione sotto è che il corso in sé non è raro, raro è riuscire a far girare ciò che c'è dentro.

Questa frase coglie il punto. La maggior parte delle persone non si blocca perché non capisce il ciclo dell'agent, ma perché non riesce nemmeno a muovere il primo passo: manca la Key del modello usata nel codice di esempio, se cambi modello il protocollo non combacia, e se non parte non puoi verificare nulla.

Questo articolo parla della configurazione minima funzionante, non della teoria degli agent.

Un agent minimo ha solo tre cose

Lasciando da parte framework e astrazioni, un agent che fa il suo lavoro è fatto di tre componenti:

1. Un modello capace di chiamare strumenti
2. Un insieme di definizioni di strumenti (nome, parametri, descrizione)
3. Un ciclo: il modello decide quale strumento chiamare, tu lo esegui, restituisci il risultato al modello, finché non dice che ha finito

Multi-agent, memoria, pianificazione: tutto ciò che c'è nei corsi è un'aggiunta a queste tre cose. Prima fai funzionare queste tre.

Primo passo: preparare la Key

Il primo compito della maggior parte dei corsi è «vai a richiedere la API Key di un certo modello». Qui la percentuale di abbandono è alta: registrazione, carta di credito, attesa dell'approvazione, a volte anche richiesta di quota.

Con un unico punto di accesso salti questo passaggio. La Key di HiAPI con una sola autenticazione copre modelli testuali come Claude, GPT, Kimi, Grok, DeepSeek, e usa il protocollo standard Chat Completions.

Dopo aver ottenuto la Key, verifica prima che funzioni:

curl -s https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [{"role": "user", "content": "Di' un saluto"}]
  }'

Se restituisce contenuto, la Key va bene.

Secondo passo: definire gli strumenti

La definizione di uno strumento è il manuale d'uso che dai al modello. Deve sapere quali strumenti esistono e quali parametri richiede ciascuno.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询指定城市的当前天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名，如 北京"}
            },
            "required": ["city"]
        }
    }
}]

La descrizione da scrivere è solo una frase: il modello usa description per decidere quando usare quello strumento. Più è chiara, più bassa è la probabilità di chiamarlo male.

Terzo passo: scrivere il ciclo

import json, requests

API = "https://api.hiapi.ai/v1/chat/completions"
KEY = "YOUR_HIAPI_API_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def run_weather(city):
    return {"city": city, "temp": 18, "condition": "晴"}  # 示例实现

messages = [{"role": "user", "content": "北京今天多少度？"}]

for _ in range(5):  # 防止死循环
    resp = requests.post(API, headers=HEADERS, json={
        "model": "gpt-6.1-sol",
        "messages": messages,
        "tools": tools,
    }).json()

    msg = resp["choices"][0]["message"]
    messages.append(msg)

    if not msg.get("tool_calls"):
        print(msg["content"])
        break

    for call in msg["tool_calls"]:
        args = json.loads(call["function"]["arguments"])
        result = run_weather(args["city"])
        messages.append({
            "role": "tool",
            "tool_call_id": call["id"],
            "content": json.dumps(result, ensure_ascii=False),
        })

Eseguito questo, vedrai che il modello decide prima di chiamare get_weather, poi, ottenuto il risultato, lo organizza in una frase di risposta. Questo è il ciclo completo dell'agent.

Come scegliere il modello

Lo stesso ciclo, cambiando il campo model cambi modello. La differenza di costo è enorme:

Modello	Input	Output	Adatto a
GPT-6 Luna	$0.025	$0.125	Chiamate a strumenti semplici, classificazione, estrazione
GPT-6.1 Terra	$0.25	$1.25	Agent quotidiani, attività di coding
GPT-6.1 Sol	$0.50	$2.50	Attività complesse a più passaggi
Claude Opus 5.5	$2.02	$10.08	Attività lunghe, che richiedono ragionamento profondo

Un singolo ciclo di chiamata a strumenti consuma circa qualche migliaio di token; con il più economico Luna, una volta costa meno di un centesimo di yuan. Per gli esperimenti del corso, il costo è trascurabile.

Se il corso specifica un modello, usa quello; se non lo specifica o non puoi usarlo, un sostituto di pari livello non compromette l'apprendimento, perché la logica del ciclo è la stessa.

I tre punti in cui ci si blocca più facilmente nei corsi

Il formato di ritorno delle chiamate agli strumenti non è corretto. Produttori diversi organizzano i campi di tool_calls in modo diverso. Con modelli compatibili con il protocollo Chat Completions il formato è uniforme e cambiare modello non richiede modificare il codice di parsing.

Il contesto si allunga sempre di più. Se porti tutta la cronologia a ogni turno, al trentesimo giro arrivi al limite. Nei corsi avanzati si parla di strategie di trimming; per ora sappi che questa trappola esiste.

Il modello non chiama gli strumenti e risponde solo a parole. Di solito è perché la descrizione dello strumento è troppo vaga, o il prompt non dice chiaramente «hai strumenti a disposizione». Rendi la descrizione più specifica, o indicalo nel system prompt.

Cosa fare dopo aver fatto girare il tutto

Non affrettarti a usare un framework.

Dopo che il ciclo minimo funziona, aggiungi in ordine queste cose:

1. Aggiungi la gestione degli errori: quando l'esecuzione di uno strumento fallisce, restituisci il messaggio di errore al modello, così che riprovi o cambi strada
2. Aggiungi il conteggio dell'uso: registra i token di ogni chiamata, solo così sai dove spendi
3. Aggiungi timeout e retry: le fluttuazioni di rete sono la norma
4. Poi considera un framework: se il compito è così complesso da richiedere multi-agent o macchine a stati complesse, allora è il momento del framework

L'architettura insegnata nei corsi è di solito pensata per la produzione; copiarla direttamente rischia di bloccarti al primo passo. Fai prima girare i tre componenti, aggiungi il resto secondo necessità.

Domande frequenti

Devo per forza usare un modello specifico?

No. Basta che supporti le chiamate a strumenti (function calling), la logica del ciclo è universale. Se il modello indicato dal corso non è utilizzabile, un sostituto di pari prezzo non compromette la comprensione.

Qual è la differenza tra corsi gratuiti e a pagamento?

Secondo la discussione su X, la differenza sta più nella struttura e nel supporto alle domande che nella conoscenza in sé. Far girare gli esempi è comunque qualcosa che devi fare da solo in entrambi i casi.

Gli strumenti possono chiamare API reali?

Sì. Basta sostituire run_weather con una vera richiesta HTTP. Attenzione a catturare tutte le eccezioni nella funzione dello strumento, altrimenti un singolo fallimento interrompe l'intero ciclo.

Quanto costa un'esecuzione?

L'esempio minimo consuma qualche migliaio di token, con il modello più economico una volta costa meno di un centesimo di yuan, con quello caro qualche centesimo. Per fare esperimenti non devi preoccuparti del costo.

Conclusione chiave

Il punto critico dei corsi sugli agent non è mai la teoria, ma il primo esempio che non parte. Tre cose bastano per far girare un ciclo completo: una Key funzionante, una definizione di strumento, un ciclo che restituisce i risultati. Aggiungere i dettagli ingegneristici dopo aver fatto girare il tutto è dieci volte più facile del contrario.

Visualizza i modelli testuali disponibili e i prezzi

---

Fonti

• Origine dell'argomento: Dean W. Perkins (@deanwperkins), https://x.com/deanwperkins/status/2116911546282733623
• Il post non allega link a corsi specifici; questo articolo non punta a nessun corso particolare, illustra solo la configurazione generica per far girare gli esempi
• Gli esempi di codice e i dati sui prezzi sono raccolti da questo sito; i prezzi provengono dall'ambiente di produzione HiAPI (2026-11-02)