API della dashboard operativa

Guida espone una piccola API operativa in sola lettura per monitorare crawl di lunga durata ed esecuzioni di indicizzazione senza aprire l’interfaccia desktop. L’API è pensata per script, agenti, dashboard leggere e client di monitoraggio su rete privata.

Non è un’interfaccia di controllo remoto. L’API della dashboard non avvia processi di lavoro, non li ferma, non riprova elementi, non elimina voci di coda, non sposta lavoro nella coda degli scarti, non esegue script, non naviga schede e non chiama strumenti MCP.

Usa la Remote Ops API quando un client su rete privata deve controllare esplicitamente Guida da remoto. Usa questa API della dashboard quando il client deve solo osservare lo stato.

Per sistemi di test deterministici con endpoint di automazione protetti da token, usa la Modalità di automazione. Per strumenti IA locali con autorizzazioni e registro di tracciabilità, usa Integrazione MCP.

URL base

Per impostazione predefinita, il server integrato ascolta su loopback:

http://127.0.0.1:9315

Quando in Impostazioni (Settings) è configurato un indirizzo di ascolto privato sicuro, Guida mantiene comunque disponibile il loopback ed espone anche l’API dashboard in sola lettura su quell’indirizzo privato. È utile, per esempio, per monitoraggio NetBird o LAN:

http://100.68.25.200:9315

La risposta di stato include dashboardUrl, dashboardBindAddress, dashboardPort, applicationVersion e campi stabili di identità nodo, così un client può mostrare l’indirizzo e il nodo Guida che sta monitorando.

Modello di sicurezza

L’API della dashboard è volutamente più stretta di MCP.

Client	Consentito
Client loopback locale	MCP più endpoint dashboard
Client remoto su rete privata	Solo endpoint dashboard in sola lettura
`POST`, `PUT`, `DELETE`, ecc. da rete privata remota verso percorsi dashboard	Rifiutati
Percorsi MCP da rete privata remota	Rifiutati
`/api/ops/*` da rete privata remota	Disponibile solo quando la Remote Ops API è abilitata esplicitamente
Indirizzo pubblico con carattere jolly come `0.0.0.0`	Rifiutato dalla validazione delle impostazioni

I client dashboard remoti dovrebbero usare richieste GET. Anche HEAD viene trattato come sola lettura. La richiesta preliminare OPTIONS è accettata solo quando il metodo richiesto è di sola lettura.

Le chiamate agli strumenti MCP usano POST sull’interfaccia MCP locale. Remote Ops usa POST /api/ops/rpc solo quando la funzionalità è abilitata. I client dashboard non dovrebbero usare POST; questa API non contiene mutazioni dashboard.

Gli indirizzi di ascolto sicuri includono loopback, intervalli IPv4 privati RFC1918, intervalli stile NetBird/CGNAT 100.64.0.0/10, IPv4 link-local, indirizzi locali univoci IPv6 e indirizzi link-local IPv6. Gli indirizzi con carattere jolly e gli indirizzi pubblici ricadono su loopback.

Tutte le letture della dashboard impostano intestazioni no-cache. Le letture dell’istantanea sono protette da un timeout breve; una lettura lenta restituisce una risposta problema 503 invece di bloccare indefinitamente il lavoro di raccolta dati.

Riepilogo endpoint

Tutti gli endpoint principali si trovano sotto /api/dashboard.

Endpoint	Scopo
`GET /api/dashboard/status`	Segnale compatto di app, spazio di lavoro, flusso di lavoro, esecuzione attiva, processi di lavoro e ambiente di esecuzione
`GET /api/dashboard/snapshot`	Istantanea operativa combinata e limitata
`GET /api/dashboard/runs`	Esecuzioni recenti dei flussi di lavoro
`GET /api/dashboard/runs/{runId}`	Dettaglio di una esecuzione di flusso di lavoro
`GET /api/dashboard/runs/{runId}/counts`	Conteggi fase/stato dell’intera esecuzione
`GET /api/dashboard/queues`	Conteggi e totali delle code
`GET /api/dashboard/workers`	Stato dei pool di processi di lavoro
`GET /api/dashboard/failures`	Attività recenti e motivi di esecuzioni fallite
`GET /api/dashboard/attention`	Elementi correnti che richiedono attenzione
`GET /api/dashboard/reconcile/{runId}`	Riepilogo del passaggio fetch/parse/index per una esecuzione
`GET /api/dashboard/events`	Flusso Server-Sent Events per invalidazioni in tempo reale ed eventi di segnale di vita

Convenzioni comuni delle risposte

Le proprietà JSON usano camel case.

Molti endpoint restituiscono elenchi limitati. Una risposta con elenco limitato usa questo involucro:

{
  "items": [],
  "totalCount": 0,
  "limit": 50,
  "truncated": false,
  "degraded": false,
  "errors": []
}

Quando truncated è true, l’endpoint ha restituito la prima pagina o il primo campione limitato, ma totalCount riporta comunque il conteggio completo noto al repository/servizio. Per domande aggregate, usa i campi aggregati, non la lunghezza di items.

Quando degraded è true, una parte dell’istantanea non è stata raccolta. La risposta va comunque trattata come istantanea parziale utile, e errors spiega cosa è fallito.

`GET /api/dashboard/status`

Restituisce un segnale di vita compatto dell’istanza Guida in esecuzione.

Usa questo endpoint per controlli di disponibilità, titoli finestra, diagnostica tra nodi e schede di stato “Guida è vivo?”.

curl http://127.0.0.1:9315/api/dashboard/status

Esempio di risposta:

{
  "generatedAt": "2026-05-24T18:30:20.082Z",
  "workspaceOpen": true,
  "workspaceName": "btbrowser-workspace",
  "workspacePath": "C:\\dev\\btbrowser-workspace",
  "activeWorkflowName": "careers-crawl",
  "workersRunning": true,
  "workersPaused": false,
  "runningTaskCount": 4,
  "unreadNotificationCount": 0,
  "activeRun": {
    "id": "92d987e072ab4649a5a7f1846446a420",
    "workflowName": "careers-crawl",
    "status": "running",
    "source": "manual",
    "startedAt": "2026-05-23T08:12:00Z",
    "finishedAt": null,
    "lastError": null
  },
  "degraded": false,
  "errors": [],
  "version": 9,
  "applicationVersion": "0.7.3-alpha.0",
  "applicationStartedAt": "2026-05-24T18:28:05.264Z",
  "dashboardBindAddress": "100.68.25.200",
  "dashboardPort": 9315,
  "dashboardUrl": "http://100.68.25.200:9315",
  "nodeIdentity": {
    "nodeId": "guida-b20ba90d102443c8a74f4c9903dce78d",
    "nodeName": "desktop-crawler",
    "nodeRole": "crawler",
    "machineName": "DESKTOP-QGUCB5J"
  },
  "nodeId": "guida-b20ba90d102443c8a74f4c9903dce78d",
  "nodeName": "desktop-crawler",
  "nodeRole": "crawler",
  "machineName": "DESKTOP-QGUCB5J",
  "workerCountsByStatus": {
    "running": 2,
    "idle": 1,
    "stopped": 4
  },
  "workerRunningCount": 2,
  "workerPausedCount": 0,
  "workerFailedCount": 0,
  "workerIdleCount": 1,
  "workerStoppedCount": 4,
  "workerStalledCount": 0
}

Campi importanti:

Campo	Significato
`workspaceOpen`	Indica se uno spazio di lavoro è attualmente aperto
`activeWorkflowName`	Selezione corrente del flusso di lavoro nello spazio di lavoro
`workersRunning`	Almeno un processo di lavoro o attività run-one è attivo
`workersPaused`	Almeno un pool di processi di lavoro è in pausa
`runningTaskCount`	Numero di attività script in esecuzione
`activeRun`	Esecuzione del flusso di lavoro in corso, se esiste, altrimenti esecuzione più recente
`degraded`, `errors`	Indicano se parte della lettura è fallita e perché
`version`	Versione monotona di invalidazione dashboard
`applicationVersion`	Versione semantica dell’app Guida, per esempio `0.7.3-alpha.0`; non parsare metadati commit
`applicationStartedAt`	Timestamp di avvio del processo
`dashboardBindAddress`, `dashboardPort`, `dashboardUrl`	Indirizzo dashboard da cui Guida ritiene di servire
`nodeIdentity`, `nodeId`, `nodeName`, `nodeRole`, `machineName`	Metadati stabili del nodo per osservatori multi-nodo
`workerCountsByStatus`, `workerRunningCount`, `workerPausedCount`, `workerFailedCount`, `workerIdleCount`, `workerStoppedCount`, `workerStalledCount`	Aggregati dello stato dei pool di processi di lavoro

`GET /api/dashboard/snapshot`

Restituisce un’istantanea operativa combinata. Usala per caricamenti iniziali di pagina e azioni di resincronizzazione forzata.

curl "http://127.0.0.1:9315/api/dashboard/snapshot?forceReload=true"

Parametri query:

Parametro	Tipo	Significato
`forceReload`	boolean	Quando `true`, bypassa la cache di breve durata e ricarica dalla verità di repository/servizi

L’istantanea include:

Campo	Significato
`version`, `generatedAt`	Identità e timestamp dell’istantanea
`workspaceName`, `workspacePath`, `activeWorkflowName`	Contesto corrente dello spazio di lavoro
`queues`	Righe di coda limitate
`workerPools`	Righe di processi di lavoro limitate
`taskCountsByStatus`	Conteggi attività script raggruppati per stato attività
`workflowLedger`	Aggregati completi del registro di tracciabilità dei flussi di lavoro
`recentRuns`	Elenco limitato delle esecuzioni recenti
`recentFailures`	Elenco limitato di errori attività/esecuzione
`attentionItems`	Elenco limitato di elementi che richiedono attenzione
`activeRun`	Riepilogo dell’esecuzione attiva o più recente
`activeRunReconciliation`	Riepilogo del passaggio fetch/parse/index per l’esecuzione attiva
`queuePendingCount`, `queueCheckedOutCount`, `queueCompletedCount`, `queueDeadLetterCount`	Totali completi delle code su tutte le code
`queueTotalsByState`	Totali delle code raggruppati per stato coda
`totalQueueCount`, `queueLimit`, `queuesTruncated`	Limiti dell’elenco code
`totalWorkerPoolCount`, `workerPoolLimit`, `workerPoolsTruncated`	Limiti dell’elenco processi di lavoro
`workerPoolCountsByStatus`, `workerPoolRunningCount`, `workerPoolPausedCount`, `workerPoolFailedCount`, `workerPoolIdleCount`, `workerPoolStoppedCount`, `workerPoolStalledCount`	Aggregati completi dello stato dei processi di lavoro
`recentRunsTotalCount`, `recentRunsLimit`, `recentRunsTruncated`	Limiti dell’elenco esecuzioni recenti
`recentFailuresTotalCount`, `recentFailuresLimit`, `recentFailuresTruncated`	Limiti dell’elenco errori
`attentionItemsTotalCount`, `attentionItemsLimit`, `attentionItemsTruncated`	Limiti dell’elenco elementi che richiedono attenzione
`nodeIdentity`, `nodeId`, `nodeName`, `nodeRole`, `machineName`	Metadati stabili del nodo
`degraded`, `errors`	Metadati di errore parziale

L’oggetto workflowLedger contiene dati aggregati, non un campione:

{
  "totalRuns": 12,
  "totalItems": 12242,
  "runCountsByStatus": {
    "running": 1,
    "completed": 10,
    "failed": 1
  },
  "itemCountsByState": {
    "queued": 923,
    "running": 21,
    "completed": 11189,
    "dead": 9
  },
  "itemCountsByStage": {
    "fetch": 285,
    "parse_index": 11672
  },
  "retryReadyCount": 0,
  "activeLeaseCount": 21,
  "expiredLeaseCount": 0,
  "attentionCount": 38
}

I conteggi vengono caricati da query aggregate del repository. Non sono calcolati dalla prima pagina di elementi.

`GET /api/dashboard/runs`

Restituisce esecuzioni recenti del flusso di lavoro attivo.

curl "http://127.0.0.1:9315/api/dashboard/runs?take=10"

Parametri query:

Parametro	Tipo	Predefinito	Max	Significato
`take`	integer	`25`	`100`	Numero di esecuzioni recenti da restituire

Forma della risposta:

{
  "items": [
    {
      "id": "92d987e072ab4649a5a7f1846446a420",
      "workflowName": "careers-crawl",
      "status": "running",
      "source": "manual",
      "startedAt": "2026-05-23T08:12:00Z",
      "finishedAt": null,
      "lastError": null
    }
  ],
  "totalCount": 12,
  "limit": 10,
  "truncated": true,
  "degraded": false,
  "errors": []
}

`GET /api/dashboard/runs/{runId}`

Restituisce il dettaglio di una esecuzione di flusso di lavoro.

curl http://127.0.0.1:9315/api/dashboard/runs/92d987e072ab4649a5a7f1846446a420

Campi della risposta:

Campo	Significato
`run`	Riepilogo esecuzione
`stageStateCounts`	Conteggi fase/stato raggruppati dell’intera esecuzione
`reconciliation`	Riepilogo del passaggio fetch/parse/index
`attentionItems`	Campione limitato di elementi che richiedono attenzione per questa esecuzione

Se l’esecuzione non esiste, l’endpoint restituisce 404.

`GET /api/dashboard/runs/{runId}/counts`

Restituisce conteggi raggruppati per fase e stato dell’intera esecuzione.

curl http://127.0.0.1:9315/api/dashboard/runs/92d987e072ab4649a5a7f1846446a420/counts

Esempio di risposta:

[
  {
    "stage": "fetch",
    "state": "queued",
    "count": 238,
    "problemCount": 0
  },
  {
    "stage": "parse_index",
    "state": "completed",
    "count": 11189,
    "problemCount": 0
  }
]

problemCount è il numero di elementi in quel gruppo che sono falliti, pronti per nuovo tentativo, morti o contengono metadati di errore. Questo endpoint è il riferimento corretto per matrici fase/stato. Non è limitato dalla dimensione pagina degli elenchi di elementi.

Se l’esecuzione non esiste, l’endpoint restituisce 404.

`GET /api/dashboard/queues`

Restituisce righe di coda limitate e totali completi delle code.

curl http://127.0.0.1:9315/api/dashboard/queues

Campi della risposta:

Campo	Significato
`items`	Fino a 100 righe di coda
`totalCount`	Numero di code
`limit`	Limite righe coda, attualmente `100`
`truncated`	Indica se alcune righe di coda sono state omesse
`totalPendingCount`	Elementi in attesa su tutte le code
`totalCheckedOutCount`	Elementi estratti/in esecuzione su tutte le code
`totalCompletedCount`	Elementi completati su tutte le code
`totalDeadLetterCount`	Elementi nella coda degli scarti su tutte le code
`totalsByState`	Totali completi delle code raggruppati per stato coda
`degraded`, `errors`	Metadati di errore parziale

Ogni riga di coda ha:

{
  "name": "careers_fetch",
  "pendingCount": 471,
  "countsByState": {
    "Pending": 471,
    "CheckedOut": 21,
    "DeadLetter": 3
  },
  "checkedOutCount": 21,
  "completedCount": 0,
  "deadLetterCount": 3
}

`GET /api/dashboard/workers`

Restituisce righe limitate dello stato dei pool di processi di lavoro e conteggi aggregati dello stato dei processi.

curl http://127.0.0.1:9315/api/dashboard/workers

Campi di una riga processo:

Campo	Significato
`queue`	Coda elaborata da questo pool
`script`	Percorso dello script del processo di lavoro
`dequeueStrategy`	Strategia di estrazione opzionale
`concurrency`	Concorrenza configurata
`activeWorkers`	Loop di processi di lavoro in esecuzione
`processed`	Elementi elaborati dal pool corrente
`failed`	Elementi falliti nel pool corrente
`remaining`	Elementi di coda rimanenti secondo lo stato del processo
`paused`	Indica se il pool è in pausa
`activeRunOneCount`	Esecuzioni one-off attive del processo di lavoro
`status`	`running`, `paused`, `stalled`, `failed`, `idle` o `stopped`
`scope`	`global`, `workflow` o `dynamic`
`checkedOutCount`	Elementi estratti per la coda del pool

Le definizioni configurate dei processi di lavoro appaiono anche quando sono ferme. Una definizione ferma con elementi di coda estratti viene riportata come stalled.

La risposta include anche campi aggregati:

Campo	Significato
`countsByStatus`	Conteggi dei pool di processi di lavoro raggruppati per stato
`runningCount`, `pausedCount`, `failedCount`, `idleCount`, `stoppedCount`, `stalledCount`	Totali completi degli stati dei processi di lavoro
`activeWorkerCount`	Somma dei loop attivi dei processi di lavoro
`activeRunOneCount`	Somma delle esecuzioni one-off attive dei processi di lavoro

`GET /api/dashboard/failures`

Restituisce attività script fallite recenti più esecuzioni di flussi di lavoro fallite.

curl "http://127.0.0.1:9315/api/dashboard/failures?take=5"

Parametri query:

Parametro	Tipo	Predefinito	Max	Significato
`take`	integer	`25`	`100`	Numero di righe errore da restituire

Campi di una riga errore:

Campo	Significato
`taskId`	ID attività script o ID esecuzione flusso di lavoro
`name`	Nome attività o etichetta esecuzione flusso di lavoro
`origin`	Origine attività, per esempio `Worker`, oppure `WorkflowLedger` per esecuzioni fallite
`status`	Stato di errore
`startTime`, `endTime`	Timestamp attività/esecuzione
`error`	Messaggio di errore
`queueName`, `queueItemKey`, `workerIndex`	Contesto processo di lavoro quando disponibile
`mcpToolName`, `triggerEvent`	Contesto MCP/trigger quando disponibile
`kind`	`task` o `workflow_run`
`workflowName`, `runId`	Contesto flusso di lavoro quando disponibile

`GET /api/dashboard/attention`

Restituisce elementi che richiedono attenzione per il flusso di lavoro attivo, oppure per una esecuzione selezionata quando viene fornito runId.

curl "http://127.0.0.1:9315/api/dashboard/attention?take=20"
curl "http://127.0.0.1:9315/api/dashboard/attention?runId=92d987e072ab4649a5a7f1846446a420&take=20"

Parametri query:

Parametro	Tipo	Predefinito	Max	Significato
`runId`	string	nessuno	n/a	Limita l’attenzione a una esecuzione
`take`	integer	`50`	`200`	Numero di righe attenzione da restituire

Campi di una riga attenzione:

Campo	Significato
`kind`	`expired_lease`, `dead_item`, `failed_item`, `retry_ready` o `failed_run`
`severity`	`critical`, `error` o `warning`
`workflowName`, `runId`	Contesto flusso di lavoro/esecuzione
`itemId`, `itemKey`	Identità elemento quando l’elemento di attenzione è legato a un elemento
`stage`, `state`	Posizione dell’elemento del flusso di lavoro
`message`	Breve spiegazione rivolta all’operatore
`timestamp`	Timestamp dell’evento/aggiornamento rilevante
`lastError`	Ultimo errore registrato quando disponibile

`GET /api/dashboard/reconcile/{runId}`

Restituisce una riconciliazione compatta del flusso per una esecuzione di flusso di lavoro.

curl http://127.0.0.1:9315/api/dashboard/reconcile/92d987e072ab4649a5a7f1846446a420

Esempio di risposta:

{
  "runId": "92d987e072ab4649a5a7f1846446a420",
  "workflowName": "careers-crawl",
  "totalItems": 12235,
  "stageStateCounts": [
    {
      "stage": "parse_index",
      "state": "completed",
      "count": 11189,
      "problemCount": 0
    }
  ],
  "fetchProcessedCount": 0,
  "fetchSkippedCount": 17,
  "fetchDeadCount": 9,
  "fetchRetryReadyCount": 0,
  "fetchRunningCount": 21,
  "fetchLeasedCount": 21,
  "parseIndexQueuedCount": 483,
  "parseIndexCompletedCount": 11189,
  "parseIndexReceivedCount": 11672,
  "fetchToParseMissingCount": 0,
  "parseIndexBacklogCount": 483,
  "handoffAttentionCount": 0,
  "handoffStatus": "backlog"
}

Usa questo endpoint per rispondere a domande sul passaggio di lavoro tra fasi, come:

Quanti elementi fetch sono ancora in coda, in esecuzione, presi in carico, saltati, morti o pronti per nuovo tentativo?
Quanti elementi parse/index sono in coda?
Quanti elementi parse/index sono completati?
Quanti elementi parse/index sono stati ricevuti da fetch?
C’è uno scarto fetch-to-parse o un backlog parse/index?
Il conteggio completo fase/stato corrisponde alla forma attesa del flusso?

Se l’esecuzione non esiste, l’endpoint restituisce 404.

`GET /api/dashboard/events`

Apre un flusso Server-Sent Events per aggiornamenti in tempo reale della dashboard.

curl -N http://127.0.0.1:9315/api/dashboard/events

Il flusso invia solo suggerimenti compatti. Non invia istantanee complete. Un client dovrebbe trattare gli eventi come “qualcosa è cambiato” e poi chiamare l’endpoint mirato di cui ha bisogno, di solito /api/dashboard/status, /api/dashboard/snapshot?forceReload=true o un endpoint di esecuzione selezionata.

Evento di connessione iniziale:

event: status
data: {"occurredAt":"2026-05-24T18:36:00.0398288+00:00","version":9,"status":"connected","workspaceOpen":true,"workspaceName":"btbrowser-workspace","activeWorkflowName":"careers-crawl","workersRunning":true,"workersPaused":false,"runningTaskCount":4,"unreadNotificationCount":0,"degraded":false,"errors":[],"applicationVersion":"0.7.3-alpha.0","applicationStartedAt":"2026-05-24T18:28:05.2641123+00:00","dashboardBindAddress":"100.68.25.200","dashboardPort":9315,"dashboardUrl":"http://100.68.25.200:9315","nodeIdentity":{"nodeId":"guida-b20ba90d102443c8a74f4c9903dce78d","nodeName":"desktop-crawler","nodeRole":"crawler","machineName":"DESKTOP-QGUCB5J"},"nodeId":"guida-b20ba90d102443c8a74f4c9903dce78d","nodeName":"desktop-crawler","nodeRole":"crawler","machineName":"DESKTOP-QGUCB5J"}

Evento di segnale di vita:

event: status
data: {"occurredAt":"2026-05-24T18:36:47.6112429+00:00","version":9,"status":"heartbeat","workspaceOpen":true,"workersRunning":true,"degraded":false,"errors":[],"applicationVersion":"0.7.3-alpha.0","nodeIdentity":{"nodeId":"guida-b20ba90d102443c8a74f4c9903dce78d","nodeName":"desktop-crawler","nodeRole":"crawler","machineName":"DESKTOP-QGUCB5J"},"nodeId":"guida-b20ba90d102443c8a74f4c9903dce78d","nodeName":"desktop-crawler","machineName":"DESKTOP-QGUCB5J"}

Evento di invalidazione:

event: invalidation
data: {"occurredAt":"2026-05-24T18:36:12.1000000+00:00","version":10,"reason":"operational_event"}

Tipi di evento:

Evento	Significato
`status` con `status: "connected"`	Flusso aperto correttamente
`status` con `status: "heartbeat"`	Flusso ancora attivo; intervallo predefinito del segnale di vita di 15 secondi
`invalidation`	Stato di spazio di lavoro, coda, processo di lavoro, attività, registro di tracciabilità dei flussi di lavoro o notifiche cambiato

Gli eventi di stato includono gli stessi campi compatti di identità app/spazio di lavoro/nodo di /api/dashboard/status. Restano comunque solo istantanee di stato, non istantanee dashboard complete.

Il canale SSE è limitato. Se arrivano molte invalidazioni rapidamente, Guida può scartare suggerimenti di invalidazione più vecchi. È sicuro perché gli eventi sono suggerimenti e i repository restano il riferimento autorevole.

Codici di stato

Stato	Significato
`200`	Risposta JSON o flusso SSE riuscito
`403`	Il client remoto ha tentato un percorso esterno alla dashboard o un metodo non di sola lettura
`404`	L’esecuzione selezionata non esiste, oppure è stata richiesta localmente una route inesistente come `/dashboard`
`499`	Il client si è disconnesso prima del completamento della lettura
`503`	Lettura della dashboard scaduta
`500`	Lettura della dashboard fallita in modo inatteso

Indicazioni per i client

Usa /api/dashboard/status per controlli leggeri di disponibilità.
Usa /api/dashboard/snapshot?forceReload=true per caricamenti iniziali e resincronizzazione esplicita.
Usa /api/dashboard/events per sapere quando ricaricare i dati interessati.
Usa /api/dashboard/runs/{runId}/counts per matrici fase/stato.
Usa /api/dashboard/reconcile/{runId} per domande sul passaggio da fetch a parse/index.
Usa applicationVersion come versione semantica dell’app e nodeId come identità stabile del nodo Guida.
Tratta gli elenchi limitati come campioni o pagine; usa totalCount, totali aggregati e truncated per avere il quadro completo.
Non fare interrogazioni periodiche aggressive quando è aperta una connessione SSE. Lascia che gli eventi di invalidazione attivino ricaricamenti mirati.
Non presumere che i dati degli eventi siano una fonte persistente di verità. Ricarica dagli endpoint JSON.

Passi successivi

Integrazione MCP - accesso locale agli strumenti MCP, autorizzazioni e registro di tracciabilità
Remote Ops API - controllo remoto su canale fidato tramite JSON-RPC
Registro di tracciabilità dei flussi di lavoro - esecuzioni persistenti dei flussi di lavoro, elementi, conteggi fase/stato e riconciliazione
Processi di lavoro delle code - pool di processi di lavoro basati su code ed elaborazione in blocco
Code e revisione - ispezione delle code e smistamento operativo