AI Agents · Leçon

Détecter et gérer les erreurs des outils

Lorsqu’un outil renvoie une erreur 500, renvoyez l’erreur au modèle afin qu’il essaie une autre approche au lieu de s’arrêter.

Leçon 4 sur 415 étapes

Détecter et gérer les erreurs des outils est une leçon AI Agents gratuite sur CoddyKit. Ceci est la leçon 4 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage AI Agents, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours AI Agents comprend 4 leçons au total.

Les outils échouent. Prévoyez-le.

Tout outil réel échoue parfois :

  • Délais d’expiration du réseau
  • Limites de débit
  • Arguments incorrects fournis par le modèle
  • Indisponibilité d’un service externe
  • Authentification invalide

Les agents de production doivent se rétablir correctement.

Retournez toujours un résultat, ne levez jamais d’exception

Dans la boucle de l’agent, interceptez toutes les erreurs des outils et retournez-les comme contenu. Ne laissez jamais une exception interrompre la boucle :

def safe_dispatch(tool_call):
    try:
        args = json.loads(tool_call.function.arguments)
        return TOOLS[tool_call.function.name](**args)
    except json.JSONDecodeError:
        return {'error': 'Arguments are not valid JSON.'}
    except KeyError:
        return {'error': f'Unknown tool: {tool_call.function.name}'}
    except Exception as e:
        return {'error': f'{type(e).__name__}: {e}'}

Format d’erreur structuré

Utilisez une structure cohérente afin que le modèle reconnaisse les erreurs :

error = {'ok': False, 'error_type': 'TimeoutError', 'error_message': 'Tavily timed out after 10s', 'retryable': True}
print(error)

Distinguer les erreurs réessayables des erreurs définitives

Certaines erreurs justifient une nouvelle tentative (délai d’expiration), d’autres non (404). Indiquez-le au modèle :

if isinstance(e, requests.Timeout):
    return {'ok': False, 'retryable': True, 'error': str(e)}
if isinstance(e, ValueError):
    return {'ok': False, 'retryable': False, 'error': str(e)}

Relancer automatiquement les erreurs temporaires

Pour les appels réseau, effectuez de nouvelles tentatives avec une temporisation exponentielle :

from tenacity import retry, wait_exponential, stop_after_attempt, retry_if_exception_type

@retry(
    wait=wait_exponential(multiplier=1, max=10),
    stop=stop_after_attempt(3),
    retry=retry_if_exception_type((requests.Timeout, requests.ConnectionError))
)
def web_search(query):
    return requests.get('https://api.tavily.com/search', ...).json()

Validation des arguments

Avant d’appeler l’outil, validez les arguments avec un modèle Pydantic :

from pydantic import BaseModel, ValidationError

class SearchArgs(BaseModel):
    query: str
    k: int = 5

try:
    args = SearchArgs.model_validate_json(tool_call.function.arguments)
except ValidationError as e:
    return {'error': f'Bad arguments: {e}'}

Afficher l’erreur au modèle

Ajoutez l’erreur comme résultat de l’outil et appelez de nouveau le modèle. Le modèle se corrige souvent lui-même :

messages.append({
    'role': 'tool',
    'tool_call_id': tc.id,
    'content': json.dumps({'error': 'Argument k must be an integer'})
})
# Next model call: 'Sorry, let me retry with k=5...'

Éviter les boucles d’erreurs infinies

Lorsqu’ils voient une erreur, certains modèles réessaient le même appel défectueux. Limitez la boucle et détectez les répétitions :

recent_calls = []
for tc in msg.tool_calls:
    key = (tc.function.name, tc.function.arguments)
    if recent_calls.count(key) >= 3:
        return 'Agent stuck in retry loop, aborting.'
    recent_calls.append(key)

Récupération propre à chaque outil

Pour les outils connus pour être instables, construisez la logique de nouvelle tentative INSIDE l’outil, et non dans la boucle :

def search_with_fallback(query):
    try:
        return tavily_search(query)
    except Exception:
        return bing_search(query)   # secondary provider

Délai d’attente pour chaque appel

Chaque appel externe nécessite un délai d’attente. Sinon, un service lent bloque tout votre agent :

import requests
response = requests.get(url, timeout=10)  # 10s

# For LLM calls:
from openai import OpenAI
client = OpenAI(timeout=30.0)

Coupe-circuits

Lorsqu’un outil échoue à plusieurs reprises, « ouvrez » le circuit et ignorez-le pendant un certain temps :

import time

class CircuitOpen(Exception):
    pass

def circuit(failure_threshold=5, recovery_timeout=60):
    def decorator(func):
        state = {'failures': 0, 'open_until': 0}
        def wrapper(*args, **kwargs):
            if time.time() < state['open_until']:
                raise CircuitOpen('circuit is open')
            try:
                result = func(*args, **kwargs)
                state['failures'] = 0
                return result
            except Exception:
                state['failures'] += 1
                if state['failures'] >= failure_threshold:
                    state['open_until'] = time.time() + recovery_timeout
                raise
        return wrapper
    return decorator

@circuit(failure_threshold=3, recovery_timeout=1)
def fragile_tool(x):
    if x < 0:
        raise ValueError('bad input')
    return x * 2

for x in [1, -1, -1, -1, -1]:
    try:
        print('ok', fragile_tool(x))
    except CircuitOpen as e:
        print('blocked:', e)
    except ValueError as e:
        print('failed:', e)

Journaliser les erreurs avec leur contexte

Journalisez suffisamment d’informations pour pouvoir déboguer après coup : nom de l’outil, arguments, type d’erreur, trace de la pile, identifiant de requête, identifiant utilisateur, identifiant de trace. Envoyez-les à votre outil d’observabilité.

Dégradation maîtrisée

Lorsqu’un outil critique est indisponible, informez-en honnêtement l’utilisateur au lieu de prétendre que l’agent a réussi :

if all_search_tools_failed:
    return 'I was unable to search the web right now. Please try again in a few minutes.'

Modèle des erreurs de Tool

Quelle est la manière la plus sûre de gérer les exceptions des outils dans la boucle de l’agent ?

Récapitulatif

Les outils échouent. Interceptez les erreurs, classez-les, structurez-les comme du contenu et laissez l’agent récupérer. Ajoutez des délais d’attente, des nouvelles tentatives et des coupe-circuits pour assurer la fiabilité en production.

Gratuit pour commencer

Apprends AI Agents avec un tuteur IA — gratuit

Écris et exécute du vrai code dans ton navigateur, obtiens de l'aide instantanée d'un tuteur IA disponible 24h/24, et reprends là où tu t'es arrêté sur le web ou dans l'app.

Cours
60
Leçons
239

Questions Fréquemment Posées

La leçon « Détecter et gérer les erreurs des outils » est-elle gratuite ?

Oui — le texte complet de « Détecter et gérer les erreurs des outils » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours AI Agents, passe à CoddyKit PRO. Le cours AI Agents comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Détecter et gérer les erreurs des outils » ?

Lorsqu’un outil renvoie une erreur 500, renvoyez l’erreur au modèle afin qu’il essaie une autre approche au lieu de s’arrêter. Tu pratiques AI Agents avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer AI Agents ?

Aucune expérience préalable n'est requise. AI Agents sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 4 sur 4.

Combien de temps prend la leçon « Détecter et gérer les erreurs des outils » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon AI Agents ?

Oui. Chaque leçon AI Agents inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. ReAct : schéma raisonner puis agir
  2. Implémenter ReAct à partir de zéro
  3. Ensembles d’outils courants (Web, calculatrice, RAG)
  4. Détecter et gérer les erreurs des outils
← Retour à AI Agents