PydanticAI + Gonka — Agenti AI tipizzati a basso costo

Prima ottieni una chiave: registrati su gate.joingonka.ai/register — ti diamo 3M di token gratuiti alla registrazione — e crea una chiave jg-xxx in 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-ваш-ключ",
    ),
)

agent = Agent(model)

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

Questo è tutto: il tuo agente PydanticAI funziona tramite la rete decentralizzata Gonka a costi minimi. Il metodo run_sync è comodo per gli script; per il codice async esiste await agent.run(...).

Parametri del modello: la finestra di contesto di MiniMax M2.7 è di 200K token (200000), DeepSeek V4 Flash di 380K, GLM-5.3 Flash di 390K; la lunghezza massima della risposta tramite Gateway è fino a 8192 token per MiniMax e GLM-5.3 Flash, fino a 32768 per DeepSeek. È possibile limitare l'output tramite le impostazioni del modello (OpenAIChatModelSettings(max_tokens=8192)). Sono disponibili MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 e zai-org/GLM-5.3-Flash — basta cambiare il nome del modello nel primo argomento di OpenAIChatModel.

Il motivo principale per scegliere PydanticAI è lo structured output. Invece di analizzare il testo della risposta con espressioni regolari, descrivi il risultato come un modello Pydantic e lo passi 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 fornisce l'oggetto 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-ваш-ключ",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Estrai 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

Questo funziona perché tutti e tre i modelli Gonka (MiniMax M2.7, DeepSeek V4 Flash e GLM-5.3 Flash) supportano il tool calling nativo — PydanticAI si basa su questo per restituire una struttura JSON valida. In output ottieni un oggetto Python tipizzato, non una stringa da analizzare manualmente. Ideale per estrazione dati, classificazione, compilazione di moduli e 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, elaborano flussi di richieste. Qui il costo dei token decide se il progetto rimarrà un prototipo o andrà in produzione. Confrontiamo i carichi tipici:

La differenza è di centinaia e migliaia di volte. Per un prototipo, significa che 3M di token gratuiti bastano per i primi test dell'agente. Per la produzione, che gestisce centinaia di migliaia di richieste al giorno, il risparmio è di decine di migliaia di dollari al mese — mantenendo lo stesso codice su PydanticAI, semplicemente con un base_url diverso.

Una sola chiave jg-xxx e un solo 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 (tools). 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 da solo quando richiamare lo strumento, ottiene 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-ваш-ключ",
    ),
)

agent = Agent(
    model,
    instructions="Ты помощник. Используй инструменты, когда нужно.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Бросает шестигранный кубик и возвращает результат."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Вычисляет математическое выражение."""
    return str(eval(expression))


result = agent.run_sync("Брось кубик и умножь результат на 7")
print(result.output)

Poiché il tool calling di Gonka è nativo, gli strumenti vengono richiamati in modo affidabile, senza il fragile parsing delle risposte testuali. L'intero ciclo (richiesta → chiamata dello strumento → risposta finale) costa circa $0.00007 tramite Gonka contro $0.04–0.22 di OpenAI/Anthropic.

Quale modello scegliere: MiniMaxAI/MiniMax-M2.7 — per dialoghi lunghi e compiti bilanciati, output fino a 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — uno dei contesti più lunghi della rete (380K) e prompt grandi ed economici, output fino a 32768. zai-org/GLM-5.3-Flash — un modello di reasoning per ragionamenti complessi e il contesto più lungo della rete (390K), output fino a 8192; il ragionamento consuma parte dei max_tokens, quindi impostali con un margine (da 600 in su). Tutti e tre sono disponibili subito con un'unica chiave: cambia solo la stringa del modello. Strumenti simili per filosofia: LangChain per chain e RAG, LlamaIndex per l'indicizzazione dei dati.