Compatibilité avec l'OpenAI SDK — Multi-Agent Research

Utiliser le multi-agent via l’OpenAI SDK

Beaucoup d’équipes ont déjà bâti leur couche d’appel autour de l’OpenAI SDK, avec ses wrappers, ses tests et ses conventions de journalisation. Bonne nouvelle : accéder au multi-agent de Grok ne vous oblige pas à tout réécrire. xAI expose une API compatible avec le format Responses d’OpenAI, ce qui permet de conserver le client OpenAI en le faisant simplement pointer vers l’API xAI.

Configuration du client

Deux paramètres suffisent — l’URL de base de xAI et votre clé API xAI :

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

À partir de là, vous utilisez la Responses API normalement, en indiquant grok-4.20-multi-agent-0309 comme modèle. Le reste de votre code d’appel reste inchangé.

Contrôle du nombre d’agents via reasoning.effort

C’est ici que la traduction entre les deux mondes se joue. Là où le xAI SDK expose un agent_count explicite, l’OpenAI SDK n’offre que reasoning.effort — vous ne demandez donc pas un nombre d’agents, vous demandez un niveau d’effort que xAI convertit en nombre d’agents.

# 4 agents (effort low)
response = client.responses.create(
    model="grok-4.20-multi-agent-0309",
    reasoning={"effort": "low"},
    input=[{"role": "user", "content": "Quels sont les derniers modeles open source de 2026 ?"}],
)
print(response.output_text)

# 16 agents (effort high)
response = client.responses.create(
    model="grok-4.20-multi-agent-0309",
    reasoning={"effort": "high"},
    input=[{"role": "user", "content": "Compare les strategies IA de l'UE et des USA en 2026"}],
)
print(response.output_text)

Le mapping effort → agents

Le champ accepte quatre valeurs, mais elles ne débouchent que sur deux équipes : "low" et "medium" mobilisent 4 agents, "high" et "xhigh" en mobilisent 16.

Ce détail mérite une lecture attentive. Passer de low à medium, ou de high à xhigh, ne change pas le nombre d’agents : ces niveaux intermédiaires peuvent influencer d’autres aspects du comportement du modèle, mais au sein de chaque paire l’équipe reste identique. Imaginez une interface où vous proposeriez à l’utilisateur quatre niveaux de profondeur de recherche — il en percevrait deux, et vos deux boutons supplémentaires ne feraient que brouiller son choix.

Chat Completions NON supporté

Voici la contrainte qui fait échouer la première tentative de la plupart des développeurs : l’API Chat Completions n’est pas supportée pour le multi-agent. Vous devez impérativement passer par la Responses API, donc client.responses.create et non client.chat.completions.create.

# NE FONCTIONNE PAS
response = client.chat.completions.create(
    model="grok-4.20-multi-agent-0309",
    messages=[{"role": "user", "content": "..."}],
)

Tenter cet appel renvoie une erreur. Si votre code existant repose entièrement sur Chat Completions — ce qui est le cas de beaucoup de bases installées —, l’adaptation n’est pas un simple changement de nom de modèle : il faut migrer l’appel vers un autre format d’entrée et de sortie. Mesurez cet effort avant de promettre l’intégration.

Streaming avec l’OpenAI SDK

Le streaming reste disponible, toujours via la Responses API :

stream = client.responses.create(
    model="grok-4.20-multi-agent-0309",
    reasoning={"effort": "low"},
    input=[{"role": "user", "content": "Resume les annonces tech de cette semaine"}],
    stream=True,
)

for event in stream:
    if hasattr(event, 'delta') and event.delta:
        print(event.delta, end="", flush=True)

Le test hasattr(event, 'delta') mérite d’être conservé tel quel : le flux d’événements de la Responses API ne contient pas que du texte, et lire aveuglément event.delta sur chaque événement produirait une exception.

Avantages et limites de cette approche

Le principal intérêt de cette voie est économique en temps : vous n’installez aucun SDK supplémentaire, vos développeurs retrouvent une syntaxe familière, et basculer entre modèles xAI et OpenAI dans une même base de code devient trivial. Pour une équipe qui veut évaluer le multi-agent sans engager de chantier, c’est le chemin le plus court.

Les limites tiennent toutes à la même cause : vous passez par une couche de compatibilité, donc vous perdez ce qui est propre à xAI. Ni agent_count, remplacé par un contrôle indirect via reasoning.effort, ni verbose_streaming, ni use_encrypted_content ne vous sont accessibles. Ajoutez que le mapping effort → agents relève d’une API en beta et pourrait évoluer : si votre produit dépend précisément du nombre d’agents mobilisés, le SDK natif reste le choix prudent.

Points clés à retenir

L’OpenAI SDK fonctionne avec le multi-agent via base_url="https://api.x.ai/v1"
Le nombre d’agents se contrôle via reasoning.effort (low/medium = 4, high/xhigh = 16)
Chat Completions n’est PAS supporté — utilisez la Responses API uniquement
Certains paramètres exclusifs du xAI SDK (agent_count, verbose_streaming) ne sont pas accessibles