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

Obtenez d'abord une clé : inscrivez-vous sur gate.joingonka.ai/register — lors de votre inscription, nous vous offrons 3M jetons gratuits — puis créez une clé jg-xxx dans Dashboard → API Keys.

Installation :

pip install pydantic-ai
# ou la version légère avec seulement les dépendances OpenAI :
# pip install "pydantic-ai-slim[openai]"

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

agent = Agent(model)

result = agent.run_sync("Explique en deux phrases ce qu'est le PoUW")
print(result.output)

C'est tout — votre agent PydanticAI fonctionne via le réseau décentralisé Gonka pour quelques centimes. La méthode run_sync est pratique pour les scripts ; pour le code async, il y a await agent.run(...).

Paramètres du modèle : fenêtre de contexte MiniMax M2.7 — 200K jetons (200000), DeepSeek V4 Flash — 380K, GLM-5.3 Flash — 390K ; longueur maximale de réponse via Gateway — jusqu'à 8192 jetons 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)). Les modèles 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 raison principale de choisir PydanticAI est le structured output. Au lieu d'analyser le texte de la réponse avec des expressions régulières, vous décrivez le résultat comme un modèle Pydantic et le transmettez au paramètre output_type. Le framework utilise l'appel d'outil (tool calling) du modèle pour le forcer à renvoyer les données strictement selon le schéma, les valide et fournit un objet déjà prêt 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-votre-clé",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Extrais les données : Anna est une développeuse backend, elle connaît Python, Go et Postgres"
)
print(result.output)
# name='Anna' role='développeuse backend' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — déjà list[str], pas du texte

Cela fonctionne parce que les trois modèles Gonka (MiniMax M2.7, DeepSeek V4 Flash et GLM-5.3 Flash) prennent en charge nativement le tool calling — PydanticAI s'appuie dessus pour renvoyer une structure JSON valide. En sortie, vous obtenez un objet Python typé, et non une chaîne à analyser manuellement. Idéal pour l'extraction de données, la classification, le remplissage de formulaires et les pipelines RAG, où le résultat doit être utilisé plus loin dans le code avec 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 fonctionnalité clé de PydanticAI réside dans ses outils. Une fonction peut être enregistrée via le décorateur @agent.tool_plain (sans contexte) ou @agent.tool (avec accès au RunContext et dependency injection). 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-votre-clé",
    ),
)

agent = Agent(
    model,
    instructions="Tu es un assistant. Utilise les outils quand c'est nécessaire.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Lance un dé à six faces et renvoie le résultat."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Calcule une expression mathématique."""
    return str(eval(expression))


result = agent.run_sync("Lance un dé et multiplie le résultat par 7")
print(result.output)

Comme l'appel d'outils est natif chez Gonka, les outils sont appelés de manière fiable, sans analyse 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 longs dialogues 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 invites volumineuses bon marché, sortie jusqu'à 32768. zai-org/GLM-5.3-Flash — modèle de raisonnement pour les réflexions complexes et le plus long contexte du réseau (390K), sortie jusqu'à 8192 ; le raisonnement consomme une partie de max_tokens, définissez-le avec une marge (à partir de 600). Tous 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 de données.