PydanticAI + Gonka — Agenti AI tipizzati a basso costo

Per prima cosa ottieni una chiave: registrati su gate.joingonka.ai/register — alla registrazione offriamo 10M di token gratuiti — e crea una chiave jg-xxx nella Dashboard → API Keys.

Installazione:

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

Un esempio minimo — un agente tramite Gonka. PydanticAI configura 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-tua-chiave",
    ),
)

agent = Agent(model)

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

Tutto qui — il tuo PydanticAI-agente funziona tramite la rete decentralizzata Gonka a costi irrisori. Il metodo run_sync è comodo per gli script; per il codice async esiste await agent.run(...).

Parametri del modello: la finestra di contesto dei modelli della rete è di 200K token (200000), la lunghezza massima della 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 e MiniMaxAI/MiniMax-M2.7 (fino a 8192 token di output ciascuno) — basta cambiare il nome del modello nel primo argomento di OpenAIChatModel.

Il motivo principale per scegliere PydanticAI è lo structured output. Invece di analizzare (parsing) il testo della risposta con espressioni regolari, descrivi il risultato come un Pydantic-model e lo passi come parametro output_type. Il framework utilizza il tool calling del modello per costringerlo a restituire dati strettamente conformi allo schema, li valida e restituisce un oggetto pronto all'uso 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-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 backend-developer, conosce Python, Go e Postgres"
)
print(result.output)
# name='Anna' role='backend-developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — è già una list[str], non testo

Funziona perché entrambi i modelli Gonka (Kimi K2.6 e MiniMax M2.7) supportano il native tool calling — PydanticAI si basa su questo per restituire una struttura JSON valida. In output ottieni un oggetto Python tipizzato, non una stringa da dover analizzare 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 lavorano continuamente: estraggono dati, richiamano strumenti ed elaborano flussi di richieste. Qui, il costo dei token decide se il progetto rimane un prototipo o entra in produzione. Confrontiamo i carichi tipici:

La differenza è di centinaia o migliaia di volte. Per un prototipo, i 10M di token gratuiti bastano per centinaia di cicli dell'agente. Per la produzione, che gestisce centinaia di migliaia di richieste al giorno, il risparmio ammonta a decine di migliaia di dollari al mese, mantenendo lo stesso codice PydanticAI e cambiando semplicemente il base_url.

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

La seconda funzionalità chiave di PydanticAI sono gli strumenti (tools). La 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-tua-chiave-api",
    ),
)

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 su Gonka è nativo, gli strumenti vengono chiamati in modo affidabile, senza il fragile parsing di risposte testuali. L'intero ciclo (richiesta → chiamata tool → risposta finale) costa circa $0.00007 tramite Gonka rispetto ai $0.04–0.22 di OpenAI/Anthropic.

Quale modello scegliere: moonshotai/Kimi-K2.6 — eccellente nel coding e nei ragionamenti complessi, output fino a 8192. MiniMaxAI/MiniMax-M2.7 — per dialoghi lunghi e compiti bilanciati, output fino a 8192. Entrambi disponibili istantaneamente con un'unica chiave: cambia solo la stringa del modello. Strumenti simili per spirito: LangChain per catene e RAG, LlamaIndex per l'indicizzazione dei dati.