Escalation con intervento umano
Definisca i trigger di escalation che mettono in pausa l’agente e richiedono l’intervento umano quando la confidenza è bassa, sta per essere eseguita un’azione distruttiva o il budget di tentativi è esaurito.
Escalation con intervento umano è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 4 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.
Quando gli agenti hanno bisogno della guida umana
Gli agenti completamente autonomi sono appropriati per attività ben definite e a basso rischio. Tuttavia, alcune situazioni richiedono il giudizio umano: istruzioni ambigue, bassa fiducia del modello, azioni distruttive irreversibili o attività in cui un errore avrebbe conseguenze gravi. L'escalation human-in-the-loop (HITL) mette in pausa l'agente in questi punti decisionali e richiede l'intervento umano prima di procedere, combinando l'efficienza dell'automazione con il giudizio delle persone.
Definire i trigger di escalation
L'escalation dovrebbe essere attivata da condizioni specifiche e misurabili, non da un'intuizione vaga. Definisca trigger di escalation espliciti per la propria applicazione. Tra i trigger comuni rientrano: fiducia del modello inferiore a una soglia, imminenza di un'azione distruttiva, avvicinamento a un limite definito dalla policy, esaurimento del budget di tentativi o superamento del limite di tempo dell'attività. Documenti i trigger nel codice come costanti denominate, così potranno essere regolati senza modificare la logica del flusso di controllo.
from enum import Enum
class EscalationReason(Enum):
LOW_CONFIDENCE = 'low_confidence' # model uncertainty
DESTRUCTIVE_ACTION = 'destructive_action' # irreversible change
AMBIGUOUS_TASK = 'ambiguous_task' # unclear instructions
RETRY_BUDGET_EXHAUSTED = 'retry_exhausted' # too many failures
POLICY_BOUNDARY = 'policy_boundary' # approaching limit
HUMAN_REQUESTED = 'human_requested' # explicit request
TIMEOUT = 'timeout' # took too long
ESCALATION_THRESHOLDS = {
'min_confidence': 0.6,
'max_retries': 5,
'max_runtime_minutes': 30,
}Rilevare una bassa fiducia
Chieda al modello di esprimere la propria fiducia in un'azione proposta prima di eseguirla. Un punteggio di fiducia inferiore alla soglia attiva l'escalation. Utilizzi un controllo strutturato della fiducia con un punteggio numerico e una breve motivazione, così il revisore umano comprenderà esattamente perché l'agente era incerto. La motivazione aiuta la persona a fornire indicazioni mirate, senza dover esaminare l'intera cronologia dell'attività.
from pydantic import BaseModel
class ConfidenceCheck(BaseModel):
proposed_action: str
confidence: float # 0.0 to 1.0
uncertainty_reason: str | None
proceed: bool
async def check_confidence(context: str, proposed_action: str) -> ConfidenceCheck:
return await judge_client.chat.completions.create(
model='gpt-4o',
response_model=ConfidenceCheck,
messages=[{
'role': 'user',
'content': f'Context: {context}\n\nI am about to: {proposed_action}\n\nHow confident am I that this is correct? Be honest about uncertainty.'
}]
)Rilevare le azioni distruttive
Contrassegni gli strumenti che eseguono azioni irreversibili con un flag destructive=True e richieda la conferma umana prima di eseguirli. Esempi: eliminare file, inviare e-mail a utenti reali, apportare modifiche al database che non possono essere annullate, addebitare un cliente o pubblicare contenuti al pubblico. L'agente deve fermarsi davanti a queste azioni e attendere l'approvazione esplicita di una persona, anche se per il resto opera autonomamente.
from dataclasses import dataclass
from typing import Callable
@dataclass
class Tool:
name: str
func: Callable
destructive: bool = False
description: str = ''
tools = [
Tool('search_web', search_web, destructive=False),
Tool('read_file', read_file, destructive=False),
Tool('write_file', write_file, destructive=True, description='Overwrites existing file'),
Tool('send_email', send_email, destructive=True, description='Sends real email to user'),
Tool('delete_records', delete_records, destructive=True, description='Permanent DB deletion'),
]
def requires_approval(tool: Tool) -> bool:
return tool.destructiveMettere in pausa l'agente e attendere l'input
Quando scatta un trigger di escalation, salvi il checkpoint (così l'attività potrà riprendere), crei un record della richiesta di escalation e avvisi il revisore umano. L'agente interrompe l'elaborazione e attende. Il revisore esamina l'escalation tramite una dashboard o una notifica, fornisce indicazioni o approvazione e l'agente riprende dal checkpoint, includendo tali indicazioni come nuovo messaggio nella cronologia.
import asyncio
async def escalate_and_wait(task_id: str, reason: EscalationReason, context: str,
question: str, timeout_hours: int = 24) -> str:
# Save checkpoint
save_checkpoint(load_checkpoint(task_id))
# Create escalation record
escalation_id = create_escalation(task_id, reason, context, question)
# Notify reviewer
notify_reviewer(escalation_id, question)
# Wait for response (polling with timeout)
deadline = asyncio.get_event_loop().time() + timeout_hours * 3600
while asyncio.get_event_loop().time() < deadline:
response = get_escalation_response(escalation_id)
if response:
return response.guidance
await asyncio.sleep(60) # check every minute
raise TimeoutError(f'Escalation {escalation_id} not answered within {timeout_hours}h')Creare l'interfaccia del revisore
I revisori umani hanno bisogno di un'interfaccia semplice per rispondere alle escalation. Come minimo, mostri: la descrizione dell'attività, i progressi compiuti finora dall'agente, la domanda specifica o l'azione proposta che richiede approvazione e i pulsanti Approva, Rifiuta e Fornisci indicazioni. Registri ogni decisione del revisore con la sua identità e il timestamp, a fini di audit. Per i team interni funzionano bene sia un bot Slack sia un semplice modulo web.
# FastAPI escalation endpoint
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class EscalationResponse(BaseModel):
escalation_id: str
decision: str # 'approve', 'reject', 'guide'
guidance: str | None = None
reviewer_id: str
@app.post('/escalations/{escalation_id}/respond')
async def respond_to_escalation(esc_id: str, response: EscalationResponse):
escalation = get_escalation(esc_id)
if not escalation or escalation.status != 'pending':
return {'error': 'Escalation not found or already resolved'}
save_escalation_response(esc_id, response)
return {'status': 'response_recorded', 'task_will_resume': True}Integrare le indicazioni umane nel contesto dell'agente
Dopo la risposta della persona, integri le sue indicazioni come un nuovo messaggio nella cronologia della conversazione dell'agente, prima di riprendere l'esecuzione. Lo presenti come proveniente da un «supervisore», per distinguerlo dalle osservazioni dell'agente. L'agente potrà quindi fare riferimento a queste indicazioni nel passaggio successivo. Se la persona ha rifiutato l'azione proposta, includa istruzioni su cosa fare invece.
def inject_human_guidance(messages: list, decision: str, guidance: str | None) -> list:
if decision == 'approve':
messages.append({
'role': 'user',
'content': 'Supervisor: Your proposed action has been approved. Proceed.'
})
elif decision == 'reject':
messages.append({
'role': 'user',
'content': f'Supervisor: Your proposed action was rejected. Instead: {guidance}'
})
elif decision == 'guide':
messages.append({
'role': 'user',
'content': f'Supervisor: Additional guidance: {guidance}'
})
return messagesMonitorare le metriche delle escalation
Monitori il volume delle escalation, le motivazioni e i tempi di risposta. Un volume elevato di escalation indica che l'agente non ha sufficiente sicurezza: l'attività potrebbe essere troppo ambigua, il modello potrebbe aver bisogno di istruzioni migliori oppure le soglie di sicurezza potrebbero essere impostate troppo in basso. Tempi di risposta lunghi indicano problemi legati al carico di lavoro dei revisori. Queste metriche aiutano a calibrare l'equilibrio tra automazione e intervento umano, riducendo al minimo le interruzioni non necessarie e mantenendo le persone nel ciclo decisionale per le decisioni realmente rischiose.
def escalation_report(db_connection, days: int = 7) -> dict:
# SQL query (pseudocode)
rows = db_connection.execute('''
SELECT
reason,
COUNT(*) as count,
AVG(EXTRACT(EPOCH FROM (responded_at - created_at)) / 3600) as avg_response_hours,
SUM(CASE WHEN decision = 'approve' THEN 1 ELSE 0 END) as approvals,
SUM(CASE WHEN decision = 'reject' THEN 1 ELSE 0 END) as rejections
FROM escalations
WHERE created_at > NOW() - INTERVAL '%s days'
GROUP BY reason
ORDER BY count DESC
''' % days).fetchall()
return [dict(r) for r in rows]Aumentare gradualmente l'autonomia
Inizi con un'elevata sensibilità alle escalation (soglia di sicurezza bassa ed escalation per tutte le azioni distruttive) e riduca gradualmente la frequenza delle escalation man mano che acquisisce fiducia nel comportamento dell'agente. Tenga traccia delle escalation che portano ad approvazioni rispetto a quelle che richiedono correzioni effettive. Un tasso di approvazione costantemente elevato per uno specifico tipo di trigger indica che può automatizzare quel trigger in sicurezza, riducendo il carico di lavoro umano e mantenendo la supervisione dove è davvero necessaria.
# Autonomy expansion strategy:
# Week 1: escalate for ALL destructive actions
# Week 2: auto-approve file writes to /tmp (low-risk), escalate others
# Week 4: auto-approve all file writes, escalate only email/DB changes
# Week 8: auto-approve emails under 10 recipients, escalate mass emails
# Track approval rates per trigger type:
# Tool: write_file -> 98% approve -> safe to automate
# Tool: send_email -> 89% approve -> near-automate with content check
# Tool: delete_records -> 43% approve -> always escalateOverride di emergenza e annullamento delle attività
Fornisca sempre un meccanismo di override di emergenza che consenta a una persona di annullare immediatamente un'attività dell'agente in esecuzione. Se un agente si comporta in modo anomalo, ad esempio chiamando strumenti che non dovrebbe usare o eseguendo azioni al di fuori dell'ambito previsto, una persona deve poterlo fermare in pochi secondi. Implementi un segnale di annullamento (un flag nel database che l'agente controlla a ogni passaggio) e si assicuri che i risultati delle chiamate agli strumenti vengano scartati se l'agente viene annullato durante un passaggio.
async def run_agent_with_cancel(task_id: str, messages: list) -> str:
for step in range(MAX_ITERATIONS):
# Check cancel flag at start of every step
if redis_client.get(f'agent:cancel:{task_id}'):
save_final_status(task_id, 'cancelled')
return 'Task cancelled by operator.'
response = await get_next_action(messages)
if response.is_final:
return response.answer
result = await execute_tool(response.tool, response.args)
messages.append({'role': 'user', 'content': result})
save_checkpoint_after_step(task_id, step, messages)
return 'Max iterations reached'Calibrare le soglie di escalation
Le soglie di escalation devono essere calibrate. Se la soglia di sicurezza è troppo alta, l'agente genera un'escalation per quasi ogni azione, sovraccaricando i revisori. Se è troppo bassa, le azioni rischiose passano senza controllo. Nella prima settimana inizi con soglie prudenti, monitori il volume delle escalation e il tasso di approvazione dei revisori, quindi apporti le opportune modifiche. Un sistema stabile dovrebbe generare escalation per il 5-15% delle attività a causa di problemi di sicurezza e per quasi il 100% delle azioni distruttive, con un tasso di approvazione complessivo superiore all'80%.
# Threshold tuning guide:
# Escalation rate vs quality trade-off:
#
# confidence_threshold=0.8 -> 35% escalation rate (too many)
# confidence_threshold=0.6 -> 12% escalation rate (target)
# confidence_threshold=0.4 -> 4% escalation rate (too few)
#
# Weekly review of escalation decisions:
# - Approval rate > 90%: lower threshold (too conservative)
# - Approval rate < 70%: raise threshold (not catching real issues)
# - Target: 75-85% approval rateVerifica rapida
Verifichi la sua comprensione della progettazione delle escalation con intervento umano.
Riepilogo della lezione
In questa lezione ha imparato che i trigger di escalation definiscono condizioni precise in cui l'agente deve fermarsi e chiedere indicazioni a una persona, i flag delle azioni distruttive sugli strumenti impongono requisiti di approvazione per le operazioni irreversibili e l'aumento graduale dell'autonomia consente di incrementare l'automazione in sicurezza man mano che l'agente conquista fiducia. Ora progetteremo l'architettura di produzione per il nostro progetto finale.
Domande Frequenti
La lezione «Escalation con intervento umano» è gratuita?
Sì — il testo completo di «Escalation con intervento umano» è 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 «Escalation con intervento umano»?
Definisca i trigger di escalation che mettono in pausa l’agente e richiedono l’intervento umano quando la confidenza è bassa, sta per essere eseguita un’azione distruttiva o il budget di tentativi è… 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 4 di 4.
Quanto tempo richiede la lezione «Escalation con intervento umano»?
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