PydanticAI + Gonka — Agents IA typés pour une bouchée de pain

Commencez par obtenir une clé : inscrivez-vous sur gate.joingonka.ai/register — à l'inscription, nous offrons 3M tokens gratuits — puis créez une clé jg-xxx dans Dashboard → API Keys.

Installation :

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

Exemple minimal — un agent via Gonka. PydanticAI définit un endpoint personnalisé via OpenAIProvider(base_url=..., api_key=...), transmis à 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)

Et voilà — votre agent PydanticAI tourne sur le réseau décentralisé Gonka pour une bouchée de pain. La méthode run_sync est pratique pour les scripts ; pour du code async, utilisez await agent.run(...).

Paramètres des modèles : la fenêtre de contexte de MiniMax M2.7 est de 180K tokens (180000), celle de DeepSeek V4 Flash de 380K, celle de GLM-5.3 Flash de 390K ; la longueur maximale de réponse via Gateway va jusqu'à 8192 tokens pour MiniMax et GLM-5.3 Flash, jusqu'à 32768 pour DeepSeek. Vous pouvez limiter la sortie via les paramètres du modèle (OpenAIChatModelSettings(max_tokens=8192)). MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 et zai-org/GLM-5.3-Flash sont disponibles — il suffit de changer le nom du modèle dans le premier argument de OpenAIChatModel.

La principale raison de choisir PydanticAI, c'est le structured output. Au lieu de parser le texte de la réponse avec des regex, vous décrivez le résultat sous forme de modèle Pydantic et le passez au paramètre output_type. Le framework utilise le tool calling du modèle pour le forcer à renvoyer des données strictement conformes au schéma, les valide, puis vous livre un objet prêt à l'emploi via 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

Cela fonctionne parce que les trois modèles Gonka (MiniMax M2.7, DeepSeek V4 Flash et GLM-5.3 Flash) prennent en charge le tool calling natif — PydanticAI s'appuie dessus pour renvoyer une structure JSON valide. Vous obtenez en sortie un objet Python typé, et non une chaîne à décortiquer à la main. Idéal pour l'extraction de données, la classification, le remplissage de formulaires et les pipelines RAG, où le résultat doit circuler dans le code sous un format strict.

PydanticAI est un framework pour les agents et les pipelines qui fonctionnent en continu : ils extraient des données, appellent des outils, traitent des flux de requêtes. Ici, le coût des jetons détermine si le projet restera un prototype ou passera en production. Comparons les charges typiques :

La différence est de plusieurs centaines, voire milliers de fois. Pour un prototype, cela signifie que 3M de jetons gratuits suffisent pour les premiers tests de l'agent. Pour la production traitant des centaines de milliers de requêtes par jour, l'économie se chiffre en dizaines de milliers de dollars par mois — avec le même code PydanticAI, simplement avec une base_url différente.

Une seule clé jg-xxx et un seul solde fonctionnent à la fois pour le format OpenAI (/v1) et le format Anthropic (/v1/messages) — mais pour PydanticAI, l'endpoint compatible OpenAI montré ci-dessus suffit.

La deuxième capacité clé de PydanticAI, ce sont les outils. Une fonction s'enregistre avec le décorateur @agent.tool_plain (sans contexte) ou @agent.tool (avec accès au RunContext et injection de dépendances). Le modèle décide lui-même quand appeler l'outil, reçoit le résultat et poursuit son raisonnement :

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)

Comme le tool calling de Gonka est natif, les outils s'appellent de manière fiable — fini le parsing fragile des réponses textuelles. Le cycle complet (requête → appel d'outil → réponse finale) coûte environ $0.00007 via Gonka, contre $0.04–0.22 chez OpenAI/Anthropic.

Quel modèle choisir : MiniMaxAI/MiniMax-M2.7 — pour les longues conversations et les tâches équilibrées, sortie jusqu'à 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — l'un des contextes les plus longs du réseau (380K) et des gros prompts bon marché, sortie jusqu'à 32768. zai-org/GLM-5.3-Flash — un modèle de reasoning pour les raisonnements complexes et le contexte le plus long du réseau (390K), sortie jusqu'à 8192 ; le raisonnement consomme une partie des max_tokens, prévoyez donc une marge (à partir de 600). Les trois sont disponibles dès maintenant avec une seule clé — seule la ligne du modèle change. Outils similaires : LangChain pour les chaînes et le RAG, LlamaIndex pour l'indexation des données.