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 vous donnons 10 millions de jetons gratuits lors de l'inscription — et créez une clé jg-xxx dans le tableau de bord → Clés API.

Installation :

pip install pydantic-ai
# ou la version allégée avec uniquement les dépendances OpenAI :
# pip install "pydantic-ai-slim[openai]"

Exemple minimal — un agent via Gonka. PydanticAI définit un point de terminaison personnalisé via OpenAIProvider(base_url=..., api_key=...), qui est passé à OpenAIChatModel :

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-votre-clé",
    ),
)

agent = Agent(model)

result = agent.run_sync("Expliquez 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 une bouchée de pain. La méthode run_sync est pratique pour les scripts ; pour le code asynchrone, il y a await agent.run(...).

Paramètres du modèle : la fenêtre contextuelle de Qwen3-235B est de 128K jetons (131072), la longueur de réponse maximale via la passerelle est de 8192 jetons. Vous pouvez limiter la sortie via les paramètres du modèle (OpenAIChatModelSettings(max_tokens=8192)). moonshotai/Kimi-K2.6 (jusqu'à 3072 jetons de sortie) et MiniMaxAI/MiniMax-M2.7 (jusqu'à 4096) 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 sa sortie structurée. Au lieu d'analyser le texte de la réponse avec des regex, 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'outils du modèle pour le forcer à renvoyer des données strictement conformes au schéma, les valide et renvoie un objet 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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(
    "Extraire les données : Anna est une développeuse backend, 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 Qwen3-235B (et les deux autres modèles Gonka) prennent en charge l'appel d'outils natif — PydanticAI s'appuie sur cela pour renvoyer une structure JSON valide. En sortie, vous obtenez un objet Python typé, pas une chaîne que vous devez 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 transmis dans le code dans 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 l'ordre de centaines à des milliers de fois. Pour un prototype, cela signifie que 10 millions de jetons gratuits suffisent pour des centaines d'exécutions d'agents. 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, juste un base_url différent.

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

La deuxième fonctionnalité clé de PydanticAI est les outils. Une fonction peut être enregistrée avec le décorateur @agent.tool_plain (sans contexte) ou @agent.tool (avec accès à RunContext et injection de dépendances). Le modèle décide seul quand appeler l'outil, obtient le résultat et continue 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-votre-clé",
    ),
)

agent = Agent(
    model,
    instructions="Vous êtes un assistant. Utilisez 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:
    """Évalue 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)

Étant donné que l'appel d'outils de Gonka est natif, 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,00001 $ via Gonka contre 0,04 $ à 0,22 $ chez OpenAI/Anthropic.

Quel modèle choisir : Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — par défaut, le meilleur équilibre qualité et la plus grande limite de sortie (8192). moonshotai/Kimi-K2.6 est fort en codage et en raisonnement complexe (sortie jusqu'à 3072). MiniMaxAI/MiniMax-M2.7 — pour les longs dialogues (sortie jusqu'à 4096). Les trois sont disponibles dès maintenant avec une seule clé — seule la chaîne du modèle change. Outils similaires : LangChain pour les chaînes et le RAG, LlamaIndex pour l'indexation des données.