Vous avez suivi un cours sur les agents mais rien ne fonctionne ? Faites tourner les exemples avec une seule clé

Un post sur X ironisait : ceux qui ont payé 500 dollars un cours sur les AI Agents peuvent désormais le regarder gratuitement. Post original : https://x.com/deanwperkins/status/2116911546282733623 (auteur Dean W. Perkins, @deanwperkins). Le consensus dans les discussions en dessous : le cours lui-même n'est pas rare, ce qui est rare, c'est de faire tourner ce qu'il contient.

Cette remarque met le doigt sur le vrai problème. La plupart des gens ne bloquent pas parce qu'ils ne comprennent pas la boucle de l'agent, mais parce que la première étape ne démarre pas : pas de clé de modèle pour l'exemple de code, un autre modèle dont le protocole ne correspond pas, et sans exécution, impossible de vérifier quoi que ce soit.

Cet article traite de la configuration minimale fonctionnelle, pas de théorie des agents.

Un agent minimal, c'est seulement trois choses

Si l'on fait abstraction des frameworks et des abstractions, un agent qui fait le travail se résume à trois composants :

1. Un modèle capable d'appeler des outils
2. Un ensemble de définitions d'outils (nom, paramètres, description)
3. Une boucle : le modèle décide quel outil appeler, vous l'exécutez, vous renvoyez le résultat au modèle, jusqu'à ce qu'il ait terminé

Les multi-agents, la mémoire, la planification dont parlent les cours ne sont que des ajouts à ces trois choses. Commencez par faire fonctionner ces trois-là.

Étape 1 : préparer la clé

Le premier devoir de la plupart des cours est « allez demander une clé API pour un certain modèle ». Cette étape en décourage plus d'un : inscription, carte bancaire, attente de validation, parfois même demande de quota.

Utiliser un point d'entrée unifié permet de sauter cette étape. La clé HiAPI offre une authentification unique qui couvre les modèles textuels Claude, GPT, Kimi, Grok, DeepSeek, etc., via le protocole standard Chat Completions.

Une fois la clé obtenue, vérifiez d'abord que la connexion passe :

curl -s https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [{"role": "user", "content": "说一句你好"}]
  }'

Si une réponse est renvoyée, la clé est bonne.

Étape 2 : définir l'outil

La définition d'outil est le mode d'emploi destiné au modèle. Il doit savoir quels outils existent et quels paramètres chacun requiert.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询指定城市的当前天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名，如 北京"}
            },
            "required": ["city"]
        }
    }
}]

La description à rédiger ne tient qu'en une phrase : c'est sur la description que le modèle se base pour décider quand utiliser cet outil. Plus elle est claire, plus le risque d'erreur d'appel est faible.

Étape 3 : écrire la boucle

import json, requests

API = "https://api.hiapi.ai/v1/chat/completions"
KEY = "YOUR_HIAPI_API_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def run_weather(city):
    return {"city": city, "temp": 18, "condition": "晴"}  # 示例实现

messages = [{"role": "user", "content": "北京今天多少度？"}]

for _ in range(5):  # 防止死循环
    resp = requests.post(API, headers=HEADERS, json={
        "model": "gpt-6.1-sol",
        "messages": messages,
        "tools": tools,
    }).json()

    msg = resp["choices"][0]["message"]
    messages.append(msg)

    if not msg.get("tool_calls"):
        print(msg["content"])
        break

    for call in msg["tool_calls"]:
        args = json.loads(call["function"]["arguments"])
        result = run_weather(args["city"])
        messages.append({
            "role": "tool",
            "tool_call_id": call["id"],
            "content": json.dumps(result, ensure_ascii=False),
        })

Une fois ceci exécuté, vous verrez le modèle décider d'abord d'appeler get_weather, puis organiser le résultat en une phrase de réponse. C'est la boucle complète de l'agent.

Comment choisir le modèle

Avec la même boucle, il suffit de changer le champ model pour changer de modèle. Les écarts de coût sont considérables :

Modèle	Entrée	Sortie	Adapté à
GPT-6 Luna	$0.025	$0.125	Appels d'outils simples, classification, extraction
GPT-6.1 Terra	$0.25	$1.25	Agents du quotidien, tâches de code
GPT-6.1 Sol	$0.50	$2.50	Tâches complexes en plusieurs étapes
Claude Opus 5.5	$2.02	$10.08	Tâches longues, raisonnement approfondi

Une boucle d'appel d'outil unique représente quelques milliers de tokens ; avec le moins cher, Luna, cela coûte moins d'un centime chinois par exécution. Pour expérimenter en suivant un cours, le coût est négligeable.

Si le cours impose un modèle précis, suivez le cours ; si aucun n'est imposé ou que vous n'y avez pas accès, un substitut de gamme équivalente ne nuit pas à l'apprentissage, car la logique de boucle reste la même.

Les trois points de blocage les plus fréquents dans les cours

Format de retour des appels d'outils incorrect. L'organisation des champs tool_calls varie selon les fournisseurs. Avec des modèles compatibles avec le protocole Chat Completions, le format est unifié : changer de modèle ne nécessite pas de modifier le code d'analyse.

Le contexte s'allonge sans cesse. Si l'on traîne tout l'historique à chaque tour, on atteint la limite dès le trentième tour. Les cours abordent les stratégies de troncature en fin de parcours ; sachez dès le début que ce piège existe.

Le modèle ne appelle pas d'outil et répond seulement en texte. C'est généralement que la description de l'outil est trop vague, ou que le prompt ne précise pas « tu as des outils à disposition ». Rendez la description concrète, ou mentionnez-le explicitement dans le prompt système.

Que faire après avoir fait fonctionner l'ensemble

Ne vous précipitez pas sur un framework.

Une fois la boucle minimale fonctionnelle, ajoutez ces éléments dans l'ordre :

1. Ajouter la gestion des erreurs : en cas d'échec d'exécution d'un outil, renvoyer le message d'erreur au modèle pour qu'il réessaie ou change de piste
2. Ajouter le suivi de consommation : enregistrer le nombre de tokens de chaque appel, pour savoir où part le coût
3. Ajouter timeouts et tentatives : les instabilités réseau sont monnaie courante
4. Envisager ensuite un framework : si la tâche devient assez complexe pour nécessiter du multi-agents ou une machine à états élaborée, il sera toujours temps d'adopter un framework

L'architecture enseignée dans les cours vise généralement la production ; la reproduire directement risque de bloquer dès la première étape. Faites d'abord tourner les trois composants, ajoutez le reste selon les besoins.

Questions fréquentes

Faut-il obligatoirement un modèle précis ?

Non. Tant que le modèle prend en charge l'appel d'outils (function calling), la logique de boucle est universelle. Si le modèle imposé par le cours n'est pas disponible, un substitut au même prix ne gêne pas la compréhension.

Quelle différence entre cours gratuits et payants ?

Selon la discussion sur X, la différence tient davantage à la structure et à l'accompagnement qu'aux connaissances elles-mêmes. Faire tourner les exemples, dans les deux cas, c'est à vous de le faire.

Les outils peuvent-ils appeler une vraie API ?

Oui. Remplacez run_weather par une véritable requête HTTP. Veillez à intercepter toutes les exceptions dans la fonction d'outil, sinon un seul échec interrompt toute la boucle.

Combien coûte une exécution ?

Quelques milliers de tokens pour l'exemple minimal, moins d'un centime chinois avec le modèle le moins cher, quelques centimes avec les plus chers. Pour expérimenter, pas d'inquiétude sur le coût.

Conclusion clé

Le point de blocage des cours sur les agents n'a jamais été la théorie, mais le premier exemple qui ne démarre pas. Trois choses suffisent à faire tourner une boucle complète : une clé utilisable, une définition d'outil, et une boucle qui renvoie les résultats. Une fois que ça tourne, ajouter les détails d'ingénierie est dix fois plus facile que l'inverse.

Consulter les modèles textuels disponibles et leurs tarifs

---

Sources

• Origine du sujet : Dean W. Perkins (@deanwperkins), https://x.com/deanwperkins/status/2116911546282733623
• Le post ne fournit pas de lien vers un cours précis ; cet article ne renvoie à aucun cours particulier et ne traite que de la configuration générique pour faire tourner les exemples
• Les exemples de code et les données tarifaires sont compilés par nos soins, les prix provenant de l'environnement de production HiAPI (2026-11-02)