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

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

Installation :

pip install pydantic-ai
# ou la version légère avec uniquement 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 dans 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-clef",
    ),
)

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 asynchrone, utilisez await agent.run(...).

Paramètres du modèle : la fenêtre contextuelle des modèles du réseau est de 200K tokens (200000), la longueur maximale de réponse via Gateway est jusqu'à 8192 tokens. Vous pouvez limiter la sortie via les paramètres du modèle (OpenAIChatModelSettings(max_tokens=8192)). Les modèles moonshotai/Kimi-K2.6 et MiniMaxAI/MiniMax-M2.7 (jusqu'à 8192 tokens de sortie chacun) sont également disponibles — il suffit de changer le nom du modèle dans le premier argument de OpenAIChatModel.

La principale raison de choisir PydanticAI est la structured output (sortie structurée). 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 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 et fournit 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-votre-clef",
    ),
)


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 développrice backend, elle connaît Python, Go et Postgres"
)
print(result.output)
# name='Anna' role='développrice backend' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — déjà list[str], pas du texte

Cela fonctionne parce que les deux modèles Gonka (Kimi K2.6 et MiniMax M2.7) prennent en charge le tool calling natif — PydanticAI s'appuie sur cela pour renvoyer une structure JSON valide. En sortie, vous obtenez un objet Python typé, pas une chaîne de caractères qu'il faut 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 réutilisé dans le code dans un format strict.

PydanticAI est un framework destiné aux agents et pipelines travaillant en continu : extraction de données, appel d'outils, traitement de flux de requêtes. Ici, le coût des tokens détermine si le projet restera un prototype ou passera en production. Comparons les charges typiques :

La différence se compte en centaines ou milliers de fois. Pour un prototype, cela signifie que 10M de tokens gratuits permettent des centaines d'exécutions. Pour la production traitant des centaines de milliers de requêtes par jour, l'économie atteint des dizaines de milliers de dollars par mois — avec le même code PydanticAI, simplement en utilisant une base_url différente.

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

La deuxième fonctionnalité clé de PydanticAI est celle des outils. Une fonction peut être enregistrée via le décorateur @agent.tool_plain (sans contexte) ou @agent.tool (avec accès à RunContext et à l'injection de dépendances). Le modèle décide lui-même quand appeler l'outil, reçoit le résultat et poursuit le 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 si 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 (tool calling) est natif chez Gonka, les outils sont appelés de manière fiable, sans parsing fragile de 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 : moonshotai/Kimi-K2.6 — performant en codage et en raisonnements complexes, sortie jusqu'à 8192. MiniMaxAI/MiniMax-M2.7 — pour de longs dialogues et des tâches équilibrées, sortie jusqu'à 8192. Les deux sont disponibles immédiatement avec une seule clé, il suffit de changer la chaîne de caractères du modèle. Outils proches dans l'esprit : LangChain pour les chaînes et le RAG, LlamaIndex pour l'indexation de données.