Agenti di intelligenza artificiale per l'analisi video in tempo reale in Video Indexer di Azure AI (anteprima)

Video Indexer di Azure AI (VI) usa agenti di intelligenza artificiale specializzati per fornire informazioni dettagliate mirate in tempo reale dai flussi video live. Questi agenti sono componenti modulari e incentrati sulle attività che analizzano automaticamente video per eventi, condizioni o comportamenti specifici, ad esempio rischi di sicurezza, problemi di esperienza dei clienti o anomalie operative. Questo articolo illustra gli agenti disponibili, l'attivazione e la gestione usando l'API e le procedure consigliate per l'integrazione dell'intelligenza agente nei flussi di lavoro di analisi video.

Tipi di agente e relativi ruoli

L'analisi in tempo reale in VI usa un'architettura modulare basata su agente. Ogni agente esegue un'attività specifica. Gli agenti agiscono come analisti di intelligenza artificiale che esaminano il flusso video e cercano eventi specifici nel video. Gli agenti disponibili sono:

• L'agente RetailOps monitora la condizione fisica degli spazi di vendita al dettaglio. Identifica scaffali disordinati, scorte mancanti e pericoli di sicurezza come liquidi sversati. Aiuta a garantire che i negozi rimangano sicuri, puliti e ben riforniti durante la giornata.
• L'agente del servizio clienti migliora l'esperienza dei clienti rilevando articoli personali dimenticati, ad esempio portafogli e telefoni. Misura i tempi di attesa e contrassegna i problemi di accessibilità, ad esempio prodotti collocati troppo in alto. Supporta il personale nella gestione di un ambiente reattivo e inclusivo.
• L'agente di raccomandazioni sulle vendite analizza l'engagement dei clienti con i prodotti e lo mette in correlazione con i dati di vendita in tempo reale. Identifica gli elementi che attirano l'attenzione, ma non si convertono in acquisti. Offre informazioni dettagliate utili sul posizionamento, sui prezzi e sull'interesse visivo per migliorare le prestazioni.
• L'agente di sicurezza protegge le persone rilevando in modo proattivo potenziali pericoli e condizioni non sicure. Questo rilevamento include l'identificazione di segni di fumo o incendio, il rilevamento delle cadute e il riconoscimento di attività rischiose, ad esempio i dipendenti nelle aree di costruzione non seguono protocolli di sicurezza.

Requisiti dell'agente

Verificare che l'estensione e l'ambiente VI soddisfino i requisiti seguenti per usare gli agenti:

• Oltre ai requisiti hardware consigliati per VI, aggiungere due nodi NVIDIA A100 o H100 GPU.

• Durante l'installazione dell'estensione, abilitare le funzionalità agentic. Per altre informazioni, vedere Gestire le estensioni di Video Indexer di Intelligenza artificiale di Azure per l'analisi in tempo reale.

  Se l'estensione è già stata installata, aggiornare l'estensione per supportare gli agenti usando il comando seguente. Sostituire i valori segnaposto con le informazioni per il cluster Kubernetes e l'estensione VI:

  az k8s-extension update \
    --cluster-type connectedClusters \
    --cluster-name <ARC_CLUSTER_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --name <EXTENSION_NAME> \
    --config "videoIndexer.agents.enabled=true"
  

Gestione degli agenti

È possibile attivare gli agenti solo tramite l'API. Questa sezione illustra come aggiornare, visualizzare ed eliminare i processi dell'agente usando l'API Video Indexer di Intelligenza artificiale di Azure. Fornisce gli endpoint e i metodi necessari per gestire gli agenti in modo efficace.

Segnaposto dei parametri API

Gli endpoint API usano i segnaposto seguenti:

Sostituite questi segnaposto con i vostri valori effettivi quando effettuate richieste all'API.

Attivando gli agenti

Per attivare un agente, usare l'API Video Indexer di Azure per trovare l'ID agente, creare un lavoro dell'agente e ottenere informazioni tramite callback o polling.

Trovare l'ID agente effettuando la richiesta seguente:

GET {extension base url}/{accountId}/agents

Salvare l'ID dell'agente da usare.

Per creare un'attività dell'agente, effettuare la richiesta seguente:

POST {extension base url}/accounts/{accountId}/agentJobs

Esempio di corpo della richiesta:

{
  "agentId": "{agentId}",
  "name": "demo",
  "description": "Periodic Agent Job",
  "eventName": "itemonfloor2",
  "intervalInSeconds": "{intervalInSeconds}",
  "enabled": true,
  "prompt": "Is there a personal item directly on the FLOOR, in the current video segment? If so, describe the exact place and item and provide recommendations. Answer shortly in a json format: {\\isDetected\\: True if there is a personal item directly on the floor, False if not, \\description\\: item description and its place, \\recommendations\\: recommendations what should be done, \\answer\\: the full answer including recommendations}",
  "callbackUrl": "{callbackUrl}",
  "cameraId":  "{cameraId}"
}

Dalla risposta al job di creazione dell'agente, si ottiene il chatId di questo job dell'agente. Mantenerla per visualizzare la risposta dell'agente.

Utilizza il callbackUrl per ottenere automaticamente la risposta dell'agente nel tuo ambiente o applicazione. Il servizio chiama questo URL e invia richieste HTTP.

Ricezione della risposta dell'agente

È possibile ottenere informazioni dettagliate sull'agente in due modi:

• Automatizzare la ricezione delle informazioni dettagliate dell'agente usando il callback. Il corpo che il callback riceve è simile all'esempio seguente.

  Esempio di risposta di callback:

  {
     "eventName": "Messy Store",
     "cameraId": "{cameraId}",
     "cameraName": "Store Front",
     "agentId": "{agentId}",
     "agentJobId": "{agentJobId}",
     "agentJobName": "Store Monitoring",
     "chatId": "{chatId}",
     "startTime": "2025-10-15T21:02:42Z",
     "endTime": "2025-10-15T21:07:42Z",
     "status": "completed",
     "errorMessage": null,
     "agentResponse": {
       "answer": "Yes, the store appears messy with items scattered on the floor and shelves disorganized. I recommend to send someone to organize the store."
     }
  }
  

• Eseguire il polling dell'ID chat eseguendo la chiamata API seguente, sostituendo i segnaposto con i valori:

  GET {extension base url}/{accountId}/chats/{chatId}/messages
  

Modifica ed eliminazione di un agente

Usare queste chiamate API per aggiornare, visualizzare ed eliminare un agente:

Procedure consigliate

Usare queste procedure consigliate per aiutare gli agenti a interpretare la finalità in modo coerente e produrre informazioni dettagliate affidabili. Scrivi prompt precisi, itera sulla formulazione e dichiara cosa includere o ignorare.

• Essere specifici e dettagliati quando si descrive l'evento che si vuole rilevare dall'agente. Ad esempio, invece di "quando c'è un casino", usare "quando ci sono vestiti sul pavimento o qualsiasi elemento sdraiato a terra".   

  Alcuni eventi e richieste includono un certo livello di interpretazione. Le parole come "vicino", "lontano" e "disordinato" possono essere aperti a interpretazione. Aiuta l'agente ad avere maggiore enfasi sul livello o sulla risoluzione appropriata della richiesta. Frasi come "direttamente sul pavimento", "completamente vuoto" e "ignorare i disordini minori e avvisare solo per problemi o disordine significativi" funzionano bene. L'uso del frame diretto funziona in genere meglio di consentire all'agente di determinare il grado di interpretazione.  

  Considerare la creazione dei job degli agenti come un processo iterativo. Provare termini, frasi e formulazioni diversi per perfezionare i risultati e il livello di dettaglio. 

• Se non si è certi del tipo di agente da scegliere, selezionare l'agente generale. Determina automaticamente quale agente specifico usare per la richiesta.

• Usare l'enfasi o le esclusioni tramite parole come "ignora", "minore" o "grande" per guidare il modo in cui l'evento deve essere interpretato.  

Limitazioni

Anche se l'intelligenza agenziale offre potenti informazioni dettagliate in tempo reale, considerare questo vincolo importante quando si usa questa funzionalità. La comprensione di queste limitazioni consente di impostare le aspettative corrette e progettare i flussi di lavoro per ottenere risultati ottimali.

• Gli agenti interpretano letteralmente le descrizioni. Fornire diversi livelli di dettaglio può migliorare i risultati. Si supponga, ad esempio, che "un casino sia costituito da elementi sparsi sul pavimento" piuttosto che semplicemente "casino". 

  Termini vaghi o relativi, ad esempio "vicino" o "disordinato" generano in genere un rilevamento incoerente. Specificarli in modo più chiaro per evitare errori di interpretazione.  

• Le descrizioni che si basano sulla posizione dell'oggetto, sugli elementi mancanti o sul posizionamento relativo possono causare un rilevamento inaffidabile. 

• Gli agenti potrebbero perdere eventi rapidi.  

Contenuti correlati

• Analisi video in tempo reale in Video Indexer di Azure AI
• Gestire le estensioni di Video Indexer di Intelligenza artificiale di Azure per l'analisi in tempo reale
• Portale per sviluppatori dell'API Video Indexer di Azure PER intelligenza artificiale