Toolfouten detecteren en herstellen
Wanneer een tool een 500-fout geeft, stuurt u de fout terug naar het model, zodat het een andere aanpak kan proberen in plaats van vast te lopen.
Toolfouten detecteren en herstellen is een gratis AI-agenten-les op CoddyKit. Dit is les 4 van 4. Je kunt de volledige les hieronder gratis lezen en daarna in de browser praktisch oefenen met een ingebouwde code-editor en een AI-begeleider die 24/7 beschikbaar is. Deze les maakt deel uit van het leertraject AI-agenten. Je voortgang wordt gesynchroniseerd op het web en in de CoddyKit-app. De cursus AI-agenten bevat in totaal 4 lessen.
Tools mislukken. Bereid je daarop voor.
Elke echte tool mislukt soms:
- Netwerktime-outs
- Rate limits
- Ongeldige argumenten van het model
- Uitval van externe diensten
- Ongeldige authenticatie
Agents in productie moeten zich soepel kunnen herstellen.
Altijd retourneren, nooit een uitzondering gooien
Vang binnen de agentlus alle toolfouten op en retourneer ze als inhoud. Laat een uitzondering nooit de lus beëindigen:
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}'}Gestructureerde foutindeling
Gebruik een consistente structuur, zodat het model fouten herkent:
error = {'ok': False, 'error_type': 'TimeoutError', 'error_message': 'Tavily timed out after 10s', 'retryable': True}
print(error)
Opnieuw te proberen versus permanent onderscheiden
Bij sommige fouten is opnieuw proberen zinvol (time-out); bij andere niet (404). Vertel het model:
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)}Tijdelijke fouten automatisch opnieuw proberen
Probeer netwerkoproepen opnieuw met een exponentieel oplopende wachttijd:
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()Argumenten valideren
Valideer argumenten voordat je de tool aanroept met een Pydantic-model:
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}'}Toon het model de fout
Voeg de fout toe als toolresultaat en roep het model opnieuw aan. Het model corrigeert zichzelf vaak:
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...'Oneindige foutlussen voorkomen
Sommige modellen proberen, wanneer ze een fout zien, dezelfde mislukte aanroep opnieuw. Beperk de lus en detecteer herhalingen:
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)Herstel per tool
Bouw voor tools waarvan bekend is dat ze soms falen de logica voor opnieuw proberen IN de tool, niet in de lus:
def search_with_fallback(query):
try:
return tavily_search(query)
except Exception:
return bing_search(query) # secondary providerTime-out bij elke aanroep
Elke externe aanroep heeft een time-out nodig. Anders bevriest één trage service je hele agent:
import requests
response = requests.get(url, timeout=10) # 10s
# For LLM calls:
from openai import OpenAI
client = OpenAI(timeout=30.0)Circuitbreakers
Wanneer een tool herhaaldelijk faalt, zet je het circuit op "open" en sla je de tool enige tijd over:
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)
Fouten loggen met context
Log genoeg om achteraf te kunnen debuggen: toolnaam, argumenten, fouttype, stacktrace, aanvraag-id, gebruikers-id, trace-id. Stuur dit naar je tool voor observeerbaarheid.
Geleidelijke verslechtering
Wanneer een kritieke tool niet beschikbaar is, vertel je dat eerlijk aan de gebruiker in plaats van te doen alsof de agent is geslaagd:
if all_search_tools_failed:
return 'I was unable to search the web right now. Please try again in a few minutes.'Patroon voor tolfouten
Wat is de veiligste manier om uitzonderingen van tools in de agentlus af te handelen?
Samenvatting
Tools falen. Vang fouten op, classificeer ze, structureer ze als inhoud en laat de agent herstellen. Voeg time-outs, pogingen en circuitbreakers toe voor betrouwbaarheid in productie.
Leer AI-agenten met een AI-tutor — gratis
Schrijf echte code en voer die uit in je browser, krijg direct hulp van een AI-tutor die 24/7 beschikbaar is en ga verder waar je gebleven bent op het web of in de app.
- Cursussen
- 60
- Lessen
- 239
Veelgestelde vragen
Is de les “Toolfouten detecteren en herstellen” gratis?
Ja — de volledige tekst van “Toolfouten detecteren en herstellen” kun je hier gratis op het web lezen. Als je interactief wilt oefenen met een ingebouwde code-editor en een AI-begeleider die 24/7 beschikbaar is, en de rest van de cursus AI-agenten wilt ontgrendelen, kun je upgraden naar CoddyKit PRO. De cursus AI-agenten bevat in totaal 4 lessen.
Wat leer ik in “Toolfouten detecteren en herstellen”?
Wanneer een tool een 500-fout geeft, stuurt u de fout terug naar het model, zodat het een andere aanpak kan proberen in plaats van vast te lopen. Je oefent met AI-agenten door code rechtstreeks in de browser uit te voeren. Een AI-begeleider die 24/7 beschikbaar is beantwoordt je vragen terwijl je de les doorwerkt.
Heb ik ervaring nodig om met AI-agenten te beginnen?
Ervaring vooraf is niet nodig. AI-agenten op CoddyKit is opgebouwd voor beginners tot gevorderden, zodat je hier of bij het begin kunt starten en in je eigen tempo kunt leren. Dit is les 4 van 4.
Hoe lang duurt de les “Toolfouten detecteren en herstellen”?
De meeste lessen van CoddyKit duren ongeveer 5–10 minuten. Elke les is kort en interactief, zodat je gestaag vooruitgaat en op het web en in de app precies verdergaat waar je was gebleven.
Kan ik code schrijven en uitvoeren in deze les over AI-agenten?
Ja. Elke les over AI-agenten bevat een ingebouwde code-editor, zodat je rechtstreeks in je browser echte code kunt schrijven en uitvoeren en direct feedback van AI krijgt — lokale installatie is niet nodig.
Alle lessen in deze cursus
- ReAct: het patroon Reason + Act
- ReAct vanaf nul implementeren
- Veelgebruikte toolsets (web, calculator, RAG)
- Toolfouten detecteren en herstellen