PydanticAI + Gonka — Agenti AI tipizzati a basso costo

Inizia ottenendo la chiave: registrati su gate.joingonka.ai/register — alla registrazione ti regaliamo 3M token gratuiti — e crea una chiave jg-xxx in Dashboard → API Keys.

Installazione:

pip install pydantic-ai
# or the slim variant with only the OpenAI dependencies:
# pip install "pydantic-ai-slim[openai]"

Esempio minimale — un agente tramite Gonka. PydanticAI imposta un endpoint personalizzato con 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-your-key",
    ),
)

agent = Agent(model)

result = agent.run_sync("Explain in two sentences what PoUW is")
print(result.output)

Fatto: il tuo agente PydanticAI funziona tramite la rete decentralizzata Gonka a pochi centesimi. Il metodo run_sync è comodo per gli script; per il codice async c'è await agent.run(...).

Parametri dei modelli: la finestra di contesto di MiniMax M2.7 è di 180K token (180000), DeepSeek V4 Flash arriva a 380K, GLM-5.3 Flash a 390K; la lunghezza massima della risposta tramite Gateway è fino a 8192 token per MiniMax e GLM-5.3 Flash, fino a 32768 per DeepSeek. Puoi 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 fare il parsing del testo della risposta con le regex, descrivi il risultato come modello Pydantic e lo passi al parametro output_type. Il framework usa il tool calling del modello per costringerlo a restituire i dati rigorosamente secondo lo schema, li valida e ti 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Extract the data: Anna is a backend developer who knows Python, Go and Postgres"
)
print(result.output)
# name='Anna' role='backend developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — already a list[str], not text

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 di esso per restituire una struttura JSON valida. In output ottieni un oggetto Python tipizzato, non una stringa da analizzare a mano. Ideale per l'estrazione di dati, la classificazione, la compilazione di form 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, 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. Puoi registrare una funzione con il decoratore @agent.tool_plain (senza contesto) o @agent.tool (con accesso a RunContext e dependency injection). Il modello decide da solo quando chiamare lo strumento, ne riceve il risultato e prosegue 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-your-key",
    ),
)

agent = Agent(
    model,
    instructions="You are an assistant. Use the tools when needed.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Rolls a six-sided die and returns the result."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Evaluates a math expression."""
    return str(eval(expression))


result = agent.run_sync("Roll the die and multiply the result by 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 del tool → 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 attività bilanciate, output fino a 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — uno dei contesti più lunghi della rete (380K) e prompt grandi a basso costo, output fino a 32768. zai-org/GLM-5.3-Flash — 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 impostalo con un margine (da 600 in su). Tutti e tre sono disponibili subito con un'unica chiave — cambia solo la stringa del modello. Strumenti di spirito affine: LangChain per catene e RAG, LlamaIndex per l'indicizzazione dei dati.