Classificazione delle modalità di errore degli agenti
Costruisca una tassonomia degli errori degli agenti: errori degli strumenti, output malformati, cicli di ragionamento, esaurimento del contesto e indisponibilità dei servizi esterni, quindi progetti strategie di recupero per ciascun caso.
Classificazione delle modalità di errore degli agenti è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Engineering Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Engineering Academy include 4 lezioni in totale.
Perché gli agenti falliscono in modi distintivi
Gli agenti falliscono in modo diverso rispetto alle semplici chiamate LLM. Una chiamata a turno singolo restituisce una risposta oppure genera un errore. Un agente che esegue un'attività in più passaggi può fallire in qualsiasi momento, e il fallimento potrebbe non essere evidente dall'output finale. Comprendere la tassonomia delle modalità di errore degli agenti è il primo passo per costruire agenti in grado di rilevare, diagnosticare e recuperare autonomamente dai propri errori.
Modalità di errore 1: errori degli strumenti
Gli errori degli strumenti si verificano quando l'agente chiama uno strumento con argomenti non validi, lo strumento genera un'eccezione oppure restituisce un risultato vuoto o malformato. Alcuni esempi sono: chiamare un'API di ricerca con una query malformata, interrogare un database con SQL non valido oppure invocare un code executor che va in timeout. Gli errori degli strumenti sono i più facili da rilevare perché producono segnali espliciti di eccezione che possono essere intercettati e gestiti.
class ToolError(Exception):
def __init__(self, tool_name: str, args: dict, error: Exception):
self.tool_name = tool_name
self.args = args
self.original_error = error
super().__init__(f'Tool {tool_name} failed: {error}')
def safe_tool_call(tool_func, args: dict) -> str:
try:
result = tool_func(**args)
if not result:
return 'Tool returned empty result. Try a different approach.'
return str(result)
except Exception as e:
raise ToolError(tool_func.__name__, args, e)Modalità di errore 2: output malformati
Gli output malformati si verificano quando l'agente genera testo che non corrisponde al formato previsto, ad esempio restituisce linguaggio naturale quando il passaggio successivo richiede JSON oppure chiama uno strumento con argomenti strutturati in modo errato. Questo accade spesso quando l'agente confonde il passaggio corrente con uno precedente. Convalidi il formato di ogni output dell'agente prima di utilizzarlo e invii nuovamente il prompt quando il formato non è corretto.
import json
def validate_agent_output(raw_output: str, expected_format: str) -> dict:
if expected_format == 'json':
try:
return json.loads(raw_output)
except json.JSONDecodeError as e:
return {
'valid': False,
'error': f'Expected JSON but got invalid JSON: {e}',
'raw': raw_output[:200]
}
return {'valid': True, 'data': raw_output}Modalità di errore 3: cicli di ragionamento
I cicli di ragionamento si verificano quando un agente ripete indefinitamente la stessa azione o lo stesso pensiero senza fare progressi. L'agente potrebbe eseguire la stessa query di ricerca 10 volte di seguito, ottenendo sempre lo stesso risultato vuoto e senza sapere cosa provare dopo. Rilevi i cicli tenendo traccia delle azioni recenti e verificando la presenza di ripetizioni. Quando viene rilevato un ciclo, inserisca un meta-prompt che chieda all'agente di provare un approccio diverso.
from collections import Counter
class LoopDetector:
def __init__(self, window: int = 5, threshold: int = 3):
self.recent_actions = []
self.window = window
self.threshold = threshold
def record(self, action: str) -> bool:
self.recent_actions.append(action)
if len(self.recent_actions) > self.window:
self.recent_actions.pop(0)
counts = Counter(self.recent_actions)
most_common_count = counts.most_common(1)[0][1] if counts else 0
return most_common_count >= self.threshold # True = loop detectedModalità di errore 4: esaurimento del contesto
L'esaurimento del contesto si verifica quando la cronologia accumulata dall'agente (chiamate agli strumenti, osservazioni e pensieri) supera la finestra di contesto del modello. Il modello tronca la cronologia senza segnalarlo, perdendo informazioni essenziali, oppure genera un errore di limite dei token. Prevenga questo problema monitorando l'uso dei token tra i vari passaggi e comprimendo la cronologia (riassumendo i passaggi meno recenti) prima che raggiunga il limite.
import tiktoken
CONTEXT_LIMIT = 100_000 # tokens
COMPRESS_AT = 80_000 # trigger compression with headroom
enc = tiktoken.encoding_for_model('gpt-4o')
def total_tokens(messages: list) -> int:
return sum(len(enc.encode(str(m))) for m in messages)
def check_context(messages: list) -> str:
tokens = total_tokens(messages)
if tokens > COMPRESS_AT:
return 'compress'
if tokens > CONTEXT_LIMIT:
return 'critical'
return 'ok'Modalità di errore 5: indisponibilità dei servizi esterni
Gli errori dei servizi esterni si verificano quando il servizio sottostante a uno strumento è inattivo, soggetto a limitazione della frequenza o restituisce errori imprevisti. Un agente che non riesce a raggiungere il database che deve interrogare rimane bloccato. A differenza dei cicli di ragionamento, che dipendono dall'agente, gli errori esterni dipendono dall'ambiente. Li gestisca con nuovi tentativi e backoff esponenziale e preveda strumenti di fallback in grado di approssimare il risultato usando fonti di dati diverse.
import asyncio
async def resilient_tool_call(tool_func, args: dict, max_retries: int = 3) -> str:
for attempt in range(max_retries):
try:
return await tool_func(**args)
except (ConnectionError, TimeoutError) as e:
if attempt == max_retries - 1:
return f'Service unavailable after {max_retries} attempts. Error: {e}'
wait = 2 ** attempt # 1s, 2s, 4s
await asyncio.sleep(wait)
return 'Unexpected error in resilient_tool_call'Modalità di errore 6: incomprensione dell'obiettivo
L'incomprensione dell'obiettivo si verifica quando l'agente interpreta erroneamente l'attività e persegue un obiettivo leggermente diverso. È l'errore più difficile da rilevare, perché l'agente potrebbe completare correttamente l'esecuzione, ma non l'attività intesa dall'utente. Lo mitighi chiedendo all'agente di riformulare l'obiettivo con parole proprie all'inizio e implementando un passaggio finale di verifica che controlli se il risultato risponde effettivamente alla domanda originale.
async def confirm_goal_understanding(original_task: str) -> str:
resp = await client.chat.completions.create(
model='gpt-4o',
messages=[
{'role': 'system', 'content': 'Restate the task in your own words. Be specific about what the final deliverable should be.'},
{'role': 'user', 'content': f'Task: {original_task}'}
]
)
return resp.choices[0].message.content
# Use the restatement as the first step of the agent
# to catch misunderstandings before any tools are calledCostruire un sistema di classificazione degli errori
Crei un classificatore strutturato degli errori che assegni a ogni eccezione dell'agente un'etichetta corrispondente al relativo tipo. Questo consente di indirizzare automaticamente ogni errore alla strategia di recupero appropriata. Salvi i log degli errori con le etichette dei tipi, così potrà analizzare quali modalità di errore siano più comuni e stabilire quali affrontare per prime. Gli errori degli strumenti e i cicli sono in genere i più frequenti e quelli su cui è più facile intervenire.
from enum import Enum
from dataclasses import dataclass
class FailureType(Enum):
TOOL_ERROR = 'tool_error'
MALFORMED_OUTPUT = 'malformed_output'
REASONING_LOOP = 'reasoning_loop'
CONTEXT_EXHAUSTION = 'context_exhaustion'
EXTERNAL_SERVICE = 'external_service'
GOAL_MISUNDERSTANDING = 'goal_misunderstanding'
MAX_ITERATIONS = 'max_iterations'
UNKNOWN = 'unknown'
@dataclass
class AgentFailure:
failure_type: FailureType
step: int
tool_name: str | None
error_message: str
recoverable: boolAssociare gli errori alle azioni di recupero
A ogni tipo di errore corrisponde un'azione di recupero appropriata. Gli errori degli strumenti richiedono un nuovo tentativo con argomenti modificati. I cicli richiedono un prompt di diversificazione che chieda all'agente di provare qualcosa di nuovo. L'esaurimento del contesto richiede la compressione. Gli errori dei servizi esterni richiedono strumenti di fallback. L'incomprensione dell'obiettivo richiede una richiesta di chiarimento. Definisca esplicitamente queste associazioni in un router di recupero che il runtime dell'agente invochi quando si verificano gli errori.
RECOVERY_ACTIONS = {
FailureType.TOOL_ERROR: 'retry_with_corrected_args',
FailureType.MALFORMED_OUTPUT: 'reformat_output',
FailureType.REASONING_LOOP: 'inject_diversity_prompt',
FailureType.CONTEXT_EXHAUSTION: 'compress_history',
FailureType.EXTERNAL_SERVICE: 'use_fallback_tool',
FailureType.GOAL_MISUNDERSTANDING:'request_clarification',
FailureType.MAX_ITERATIONS: 'escalate_to_human',
FailureType.UNKNOWN: 'escalate_to_human'
}Impostare limiti massimi per le iterazioni
Ogni agente deve avere un limite massimo di iterazioni come vincolo di sicurezza inderogabile. Senza questo limite, un agente bloccato in un ciclo continua a funzionare indefinitamente, consumando token e denaro. Imposti il limite in base alla complessità prevista dell'attività: un semplice agente per domande e risposte potrebbe fermarsi a 5 passaggi, mentre un agente di ricerca complesso potrebbe consentirne 20. Al raggiungimento del limite, registri l'errore, salvi i risultati parziali e trasferisca il caso a una persona oppure restituisca una risposta parziale.
MAX_ITERATIONS = 15
async def run_agent(task: str) -> str:
messages = [{'role': 'user', 'content': task}]
loop_detector = LoopDetector()
for iteration in range(MAX_ITERATIONS):
response = await get_agent_action(messages)
if response.is_final:
return response.answer
action_key = f'{response.tool}:{response.args}'
if loop_detector.record(action_key):
messages.append({'role': 'system', 'content': 'You are repeating yourself. Try a completely different approach.'})
continue
result = await execute_tool(response.tool, response.args)
messages.append({'role': 'tool', 'content': result})
return 'Task exceeded maximum iterations. Partial results: ' + get_partial_result(messages)Registrare gli errori per l'analisi post-mortem
Registri ogni errore dell'agente con un contesto sufficiente per diagnosticarlo in un secondo momento: la descrizione completa dell'attività, la cronologia completa delle azioni fino al punto dell'errore, il tipo di errore e il messaggio di errore, il numero di iterazioni e l'uso dei token. Salvi queste informazioni in una tabella failures con un indice su failure_type e task_id. Esamini regolarmente i log degli errori per individuare i tipi di attività più soggetti a specifiche modalità di errore e stabilisca di conseguenza la priorità delle correzioni.
import json
from dataclasses import asdict
async def log_agent_failure(task_id: str, failure: AgentFailure, history: list, pool):
async with pool.acquire() as conn:
await conn.execute('''
INSERT INTO agent_failures
(task_id, failure_type, step, tool_name, error_message,
recoverable, action_history, failed_at)
VALUES ($1, $2, $3, $4, $5, $6, $7, NOW())
''',
task_id,
failure.failure_type.value,
failure.step,
failure.tool_name,
failure.error_message,
failure.recoverable,
json.dumps(history)
)Verifica rapida
Verifichi la Sua comprensione della classificazione delle modalità di errore degli agenti.
Riepilogo della lezione
In questa lezione ha imparato che le sei principali modalità di errore degli agenti comprendono errori degli strumenti, output malformati, cicli di ragionamento, esaurimento del contesto, errori dei servizi esterni e incomprensione dell'obiettivo, che il rilevamento dei cicli tramite la cronologia delle azioni individua i pattern ripetitivi prima che esauriscano il budget di iterazioni e che l'associazione dei tipi di errore alle azioni di recupero consente l'autoriparazione automatica. Nel prossimo modulo implementeremo l'autocorrezione e il prompting riflessivo.
Domande Frequenti
La lezione «Classificazione delle modalità di errore degli agenti» è gratuita?
Sì — il testo completo di «Classificazione delle modalità di errore degli agenti» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Engineering Academy, passa a CoddyKit PRO. Il corso AI Engineering Academy include 4 lezioni in totale.
Cosa imparerò in «Classificazione delle modalità di errore degli agenti»?
Costruisca una tassonomia degli errori degli agenti: errori degli strumenti, output malformati, cicli di ragionamento, esaurimento del contesto e indisponibilità dei servizi esterni, quindi progetti… Eserciti AI Engineering Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Engineering Academy?
Non è richiesta alcuna esperienza precedente. AI Engineering Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.
Quanto tempo richiede la lezione «Classificazione delle modalità di errore degli agenti»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Engineering Academy?
Sì. Ogni lezione AI Engineering Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Classificazione delle modalità di errore degli agenti
- Autocorrezione e prompting riflessivo
- Checkpoint e ripresa delle attività
- Escalation con intervento umano