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.
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 providerDé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.
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
- ReAct : schéma raisonner puis agir
- Implémenter ReAct à partir de zéro
- Ensembles d’outils courants (Web, calculatrice, RAG)
- Détecter et gérer les erreurs des outils