# Notifiche push human-in-the-loop: approva un agente AI dal telefono

> Fai fermare un agente prima di ogni azione irreversibile, inviagli un pulsante Approva sul telefono e aspetta il tocco. Un endpoint di approvazione di 25 righe, un helper Python e i limiti da conoscere.

*13.10.2026*

<!-- source: https://pocketalert.app/it/blog/human-in-the-loop-notifications -->

Un agente che può fare deploy, rimborsare, eliminare o inviare email da solo è utile fino al momento in cui sbaglia una di queste cose. La soluzione non è impedirgli di agire. È fargli chiedere prima, e rendere la richiesta abbastanza semplice da farti rispondere davvero.

Human-in-the-loop significa esattamente questo: l'agente si ferma a un checkpoint, una persona approva o rifiuta, e l'agente prosegue con la risposta. La parte difficile non è la logica. È far arrivare la domanda a te quando non sei alla scrivania, e ricevere la risposta senza un laptop.

Questa guida lo fa con una notifica push che contiene un pulsante **Approva**. L'agente la invia, aspetta e legge la tua decisione da un piccolo endpoint che il pulsante chiama.

## Come funziona il ciclo

Quattro componenti, tutti semplici:

1. L'agente arriva a un passaggio rischioso e crea una richiesta con un ID casuale.
2. Invia una notifica push di Pocket Alert con due [pulsanti di azione](https://info.pocketalert.app/features/action-buttons.html). Ogni pulsante è una richiesta HTTP al tuo endpoint di approvazione, che include quell'ID.
3. Tocchi la push, leggi cosa vuole fare l'agente e tocchi **Approva** o **Rifiuta**. Il telefono chiama direttamente l'endpoint.
4. L'agente interroga l'endpoint, legge la decisione e prosegue, oppure si ferma.

Se nessuno risponde prima del timeout, l'agente considera la risposta un no. Un passaggio di approvazione che di default vale "sì" è una notifica, non una protezione.

## Cosa ti serve

- Un account Pocket Alert con un piano a pagamento. I pulsanti di azione vengono rimossi dai messaggi nel piano gratuito, quindi la push arriverebbe senza. Starter costa 6 $ al mese.
- Una chiave API da [Chiavi API](/account/apikeys), idealmente una separata per l'agente.
- Un posto dove far girare un piccolo endpoint HTTPS raggiungibile dal telefono. L'esempio usa un Cloudflare Worker, gratuito con questi volumi; va bene qualsiasi server.

## Passo 1. L'endpoint di approvazione

L'endpoint fa due cose: registra una decisione quando il telefono lo chiama, e la restituisce quando l'agente la chiede. Questo Worker conserva le decisioni in Workers KV per un'ora:

```js
export default {
  async fetch(request, env) {
    if (request.headers.get('X-Approval-Secret') !== env.SECRET) {
      return new Response('forbidden', { status: 403 });
    }

    const [, action, id] = new URL(request.url).pathname.split('/');
    if (!/^[a-f0-9]{32}$/.test(id ?? '')) {
      return new Response('bad id', { status: 400 });
    }

    if (request.method === 'POST' && (action === 'approve' || action === 'decline')) {
      const existing = await env.DECISIONS.get(id);
      if (!existing) await env.DECISIONS.put(id, action, { expirationTtl: 3600 });
      return new Response(existing ?? action);
    }

    if (request.method === 'GET' && action === 'status') {
      return new Response((await env.DECISIONS.get(id)) ?? 'pending');
    }

    return new Response('not found', { status: 404 });
  },
};
```

Collega un namespace KV come `DECISIONS`, aggiungi un `SECRET` casuale e lungo come secret del Worker, poi fai il deploy. Tre dettagli sono voluti:

- **Vince la prima risposta.** Un secondo tocco, o un tocco sull'altro pulsante, non può cambiare una decisione già registrata. Pocket Alert non blocca i tocchi ripetuti su un pulsante `http`, quindi deve farlo l'endpoint.
- **Il secret viaggia in un header**, impostato nel pulsante stesso. Lo invia il telefono, lo invia l'agente, e nessun altro lo ha.
- **Le decisioni scadono.** Un'approvazione di ieri non dovrebbe sbloccare nulla oggi.

Workers KV è eventualmente consistente, quindi l'agente potrebbe non vedere una decisione fino a 60 secondi o più dopo il tocco. Per un passaggio di approvazione va bene; se ti serve immediata, qualsiasi server con un database o un Durable Object fa lo stesso lavoro.

## Passo 2. Chiedi dall'agente

L'helper qui sotto invia la push, interroga l'endpoint e restituisce `True` solo con un'approvazione esplicita. Funziona con qualsiasi agente Python: un tool LangChain, una funzione dell'OpenAI Agents SDK, un semplice ciclo.

```python
import json
import os
import time
import uuid

import requests

PUSH_API = "https://api.pocketalert.app/v1/messages"
APPROVALS = "https://approvals.YOUR_SUBDOMAIN.workers.dev"
SECRET = os.environ["APPROVAL_SECRET"]

def ask_human(title: str, details: str, timeout: int = 900) -> bool:
    request_id = uuid.uuid4().hex

    def button(label: str, action: str) -> dict:
        return {
            "type": "http",
            "label": label,
            "value": json.dumps({
                "url": f"{APPROVALS}/{action}/{request_id}",
                "method": "POST",
                "headers": {"X-Approval-Secret": SECRET},
            }),
        }

    requests.post(
        PUSH_API,
        headers={"Token": os.environ["POCKETALERT_API_KEY"]},
        json={
            "title": title,
            "message": details,
            "level": "high",
            "actions": [button("Approve", "approve"), button("Decline", "decline")],
        },
        timeout=10,
    ).raise_for_status()

    deadline = time.time() + timeout
    while time.time() < deadline:
        status = requests.get(
            f"{APPROVALS}/status/{request_id}",
            headers={"X-Approval-Secret": SECRET},
            timeout=10,
        ).text
        if status in ("approve", "decline"):
            return status == "approve"
        time.sleep(5)
    return False
```

Poi mettilo davanti a qualsiasi azione che non vorresti far eseguire all'agente senza supervisione:

```python
if ask_human("Deploy to production?", "build #482 · 14 files · all checks green"):
    deploy()
else:
    report("Deploy skipped: not approved")
```

`level: "high"` invia la push come time-sensitive, quindi passa la Full immersion su iPhone e appare come notifica heads-up su Android. Un'approvazione che vedi un'ora dopo è un'approvazione per cui l'agente ha aspettato un'ora.

## Cosa vedi sul telefono

La push arriva con il titolo e i dettagli scritti dall'agente, e **Approva** e **Rifiuta** direttamente sulla notifica. Tieni premuto su iPhone o espandila su Android e tocca un pulsante: la richiesta parte in background, senza aprire l'app, anche se Pocket Alert è chiusa. Gli stessi pulsanti sono anche dentro il messaggio nell'app, dove un toast mostra il codice di stato restituito dal tuo endpoint.

Due dettagli di piattaforma da conoscere prima di affidarti a questo:

- **Se la richiesta fallisce**, perché il tuo endpoint ha restituito un errore o il telefono non aveva rete, compare una nuova notifica con un pulsante **Riprova**. Una richiesta che potrebbe essere arrivata all'endpoint non viene mai ritentata da sola, quindi un tocco non può approvare due volte alle tue spalle.
- **I pulsanti delle notifiche di sistema richiedono l'app Pocket Alert 2.0.1 o successiva.** Nelle versioni precedenti il banner non ha pulsanti e restano in attesa dentro il messaggio. Le etichette vengono mostrate come scritte su entrambe le piattaforme; se iOS non riesce a preparare i pulsanti personalizzati in tempo, usa un'etichetta generica **Esegui** per `http`, e il pulsante funziona comunque.

## Dove mettere i checkpoint

Chiedi troppo spesso e finirai per approvare senza leggere. I buoni checkpoint sono le azioni difficili da annullare o che costano denaro reale:

- Deploy e migrazioni di database in produzione
- Invio di email, pubblicazioni pubbliche o messaggi ai clienti
- Rimborsi, acquisti e qualsiasi chiamata a un'API di pagamento
- Eliminazione di dati, rotazione di chiavi, modifica di DNS o permessi
- Esecuzioni che spenderebbero più di un budget di token o cloud stabilito

Tutto il resto è meglio come semplice notifica a posteriori. La pagina [avvisi per agenti AI](/use-cases/ai-agent-alerts) copre questo lato: completato, fallito, bloccato.

## Farlo tramite MCP

Se l'agente gira in un client MCP, può inviare la stessa push senza l'helper Python. Il [server MCP di Pocket Alert](/tools/mcp) espone `create_message` con un parametro `actions`, quindi puoi istruire l'agente a chiamarlo con i due pulsanti e poi controllare l'URL di stato prima di proseguire.

Funziona, con un avvertimento: ora l'agente è responsabile dell'attesa, e un modello a cui viene detto di aspettare l'approvazione può comunque decidere di non farlo. Per tutto ciò che conta, applica il checkpoint in codice che il modello non può saltare, come l'helper qui sopra o un hook di permessi in [Claude Code](/blog/claude-code-push-notifications) o [Codex](/blog/codex-notifications). Usa la strada MCP per la domanda e il codice per il cancello.

## Varianti

- **Pulsante singolo.** Invia solo **Approva** e lascia che il silenzio voglia dire no. Non c'è nulla da toccare per errore sul banner, e rifiutare non ti costa nulla.
- **Strumenti di workflow.** In n8n, un nodo Wait impostato per riprendere alla chiamata di un webhook ti dà un URL di ripresa; mettilo nel pulsante Approva e il workflow prosegue quando tocchi.
- **Contesto nella push.** Inserisci i numeri nel messaggio: l'importo, l'ambiente, il numero di righe. Dovresti poter decidere solo dal testo.
- **Un pulsante di visualizzazione.** Sostituisci Rifiuta con un pulsante `view` che apre il diff, la fattura o l'esecuzione, e rifiuta semplicemente non approvando.

## FAQ

### Funziona l'approvazione dalla schermata di blocco?

Sì. I pulsanti `http` funzionano dalla schermata di blocco senza sbloccare il telefono, che Pocket Alert sia aperta, in background o chiusa. Su Android serve una schermata di blocco configurata per mostrare il contenuto delle notifiche; se lo nasconde, i pulsanti compaiono dopo lo sblocco. Se questo è troppo facile per un'azione rischiosa, metti la decisione dietro un pulsante `view` che apre una pagina per cui devi accedere; aprire una pagina richiede prima lo sblocco.

### È sicuro?

La richiesta del pulsante va dal telefono direttamente al tuo endpoint; Pocket Alert non la inoltra né vede la risposta. Proteggi l'endpoint con un header segreto, usa un ID casuale per ogni richiesta, accetta solo la prima risposta e fai scadere le decisioni. I messaggi, configurazione dei pulsanti inclusa, sono cifrati a riposo.

### Cosa succede se non rispondo mai?

L'helper restituisce `False` allo scadere del timeout, 15 minuti di default, e l'agente dovrebbe trattarlo come rifiuto. Scegli un timeout coerente con quanto il compito può ragionevolmente attendere.

### Possono approvare più persone?

Ogni dispositivo dell'account riceve la push, e vince il primo tocco. Per approvazioni per persona, invia a ciascuna la propria push con un ID di richiesta separato e decidi nell'endpoint quante approvazioni servono.

### Funziona su Android e iPhone?

Sì, su entrambi, con le tue etichette sulla notifica e dentro il messaggio. I pulsanti delle notifiche di sistema richiedono l'app versione 2.0.1 o successiva.

[Ottieni una chiave API](/signup), fai il deploy dell'endpoint e dai al tuo agente un modo per chiedere prima di agire.
