PydanticAI + Gonka — Agenti AI tipizzati a basso costo

Innanzitutto, ottieni una chiave: registrati su gate.joingonka.ai/register e al momento della registrazione ti daremo 10 milioni di token gratuiti. Quindi, crea una chiave jg-xxx nella Dashboard → API Keys.

Installazione:

pip install pydantic-ai
# o la versione leggera solo con le dipendenze OpenAI:
# pip install "pydantic-ai-slim[openai]"

Un esempio minimo — un agente tramite Gonka. PydanticAI imposta un endpoint personalizzato tramite OpenAIProvider(base_url=..., api_key=...), che viene passato a OpenAIChatModel:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-la-tua-chiave",
    ),
)

agent = Agent(model)

result = agent.run_sync("Spiega in due frasi cos'è PoUW")
print(result.output)

Questo è tutto — il tuo agente PydanticAI funziona tramite la rete decentralizzata Gonka a costi irrisori. Il metodo run_sync è comodo per gli script; per il codice async, c'è await agent.run(...).

Parametri del modello: la finestra di contesto di Qwen3-235B è di 128K token (131072), la lunghezza massima di risposta tramite Gateway è fino a 8192 token. È possibile limitare l'output tramite le impostazioni del modello (OpenAIChatModelSettings(max_tokens=8192)). Sono disponibili anche moonshotai/Kimi-K2.6 (fino a 3072 token di output) e MiniMaxAI/MiniMax-M2.7 (fino a 4096) — basta cambiare il nome del modello nel primo argomento di OpenAIChatModel.

Il motivo principale per scegliere PydanticAI è l'output strutturato. Invece di analizzare il testo della risposta con espressioni regolari, si descrive il risultato come un modello Pydantic e lo si passa al parametro output_type. Il framework utilizza il tool calling del modello per costringerlo a restituire i dati rigorosamente secondo lo schema, li convalida e restituisce un oggetto già pronto tramite result.output.

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-la-tua-chiave",
    ),
)


class Profile(BaseModel):
    name: str
    role: str
    skills: list[str]


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Estrai i dati: Anna è una sviluppatrice backend, conosce Python, Go e Postgres"
)
print(result.output)
# name='Anna' role='sviluppatrice backend' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — è già list[str], non testo

Questo funziona perché Qwen3-235B (e gli altri due modelli Gonka) supportano il tool calling nativo — PydanticAI si basa su di esso per restituire una struttura JSON valida. In uscita si ottiene un oggetto Python tipizzato, non una stringa che deve essere analizzata manualmente. Ideale per l'estrazione di dati, la classificazione, la compilazione di moduli e le pipeline RAG, dove il risultato deve proseguire nel codice in un formato rigoroso.

PydanticAI è un framework per agenti e pipeline che operano continuamente: estraggono dati, richiamano strumenti, elaborano flussi di richieste. Qui, il costo dei token determina se un progetto rimarrà un prototipo o andrà in produzione. Confrontiamo i carichi tipici:

La differenza è di centinaia e migliaia di volte. Per un prototipo, ciò significa che 10 milioni di token gratuiti sono sufficienti per centinaia di esecuzioni dell'agente. Per la produzione, che gestisce centinaia di migliaia di richieste al giorno, il risparmio si traduce in decine di migliaia di dollari al mese, con lo stesso codice su PydanticAI, solo con un diverso base_url.

Una singola chiave jg-xxx e un singolo saldo funzionano sia per il formato OpenAI (/v1) che per il formato Anthropic (/v1/messages) — ma per PydanticAI è sufficiente l'endpoint compatibile con OpenAI, mostrato sopra.

La seconda funzionalità chiave di PydanticAI sono gli strumenti. Una funzione può essere registrata con il decoratore @agent.tool_plain (senza contesto) o @agent.tool (con accesso a RunContext e dependency injection). Il modello decide autonomamente quando chiamare lo strumento, riceve il risultato e continua il ragionamento:

import random
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-la-tua-chiave",
    ),
)

agent = Agent(
    model,
    instructions="Sei un assistente. Usa gli strumenti quando necessario.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Lancia un dado a sei facce e restituisce il risultato."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Calcola un'espressione matematica."""
    return str(eval(expression))


result = agent.run_sync("Lancia il dado e moltiplica il risultato per 7")
print(result.output)

Poiché il tool calling di Gonka è nativo, gli strumenti vengono chiamati in modo affidabile, senza l'instabile parsing delle risposte testuali. L'intero ciclo (richiesta → chiamata a strumento → risposta finale) costa circa $0.00001 tramite Gonka contro $0.04-0.22 con OpenAI/Anthropic.

Quale modello scegliere: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — predefinito, miglior equilibrio qualità-prezzo e il limite di output più grande (8192). moonshotai/Kimi-K2.6 è forte nella codifica e nel ragionamento complesso (output fino a 3072). MiniMaxAI/MiniMax-M2.7 — per dialoghi lunghi (output fino a 4096). Tutti e tre sono disponibili subito con una sola chiave — cambia solo la stringa del modello. Strumenti simili: LangChain per catene e RAG, LlamaIndex per l'indicizzazione dei dati.