Panoramica dell'API W365 for Agents

Windows 365 for Agents espone le funzionalità tramite superfici complementari mappate al ciclo di vita della sessione dell'agente:

• API Microsoft Graph per l'amministrazione. Gli amministratori IT e gli sviluppatori di agenti usano queste API per effettuare il provisioning e gestire la capacità del pool.
• Windows 365 for Agents API di sessione per la gestione delle sessioni di runtime. Le applicazioni partner chiamano questa API per estrarre un PC cloud e quindi rilasciarlo al termine del lavoro.
• Strumenti MCP (Model Context Protocol) per l'operazione in sessione. Gli agenti di intelligenza artificiale richiamano questi strumenti tramite l'endpoint MCP per sessione. Per la condivisione dello schermo, un'applicazione partner richiama le azioni di condivisione dello schermo per conto di un utente.

Insieme, queste superfici coprono il provisioning del pool, l'acquisizione di un PC cloud, l'esecuzione di lavoro e l'osservazione o l'assistenza in base alle esigenze.

Computer-Create: administration

Sul lato Microsoft API Graph, il piano Computer-Create usa il API Graph W365A e il portale di amministrazione di W365. Attraverso queste superfici, gli amministratori e i fornitori di software indipendenti (ISV) possono:

• Effettuare il provisioning di pool di agenti Cloud PC.
• Configurare criteri e immagini.
• Registrare i chiamanti partner attendibili.
• Ridimensionare i conteggi dei pool.
• Collegare la misurazione tramite la fatturazione MAC.

Computer-Get: estrazione e archiviazione della sessione

Il piano Computer-Get è una piccola superficie di controllo del runtime per le applicazioni partner, servita dall'API sessione Windows 365 for Agents (non Da Microsoft Graph).

Checkout riserva un PC cloud e restituisce l'identità della sessione e gli URL di connessione:

POST /api/pools/{poolId}/sessions?api-version=2.0

Un checkout riuscito restituisce:

• sessionId : identificatore della sessione
• computerUrl : URL di base per le chiamate agli strumenti MCP (accodamento /mcp)
• screenshareUrl : URL di base per le azioni di condivisione dello schermo

Il checkout può richiedere fino a 30 secondi durante l'assegnazione di un dispositivo. Usare l'intestazione x-ms-sessionId (un UUID v4) come chiave di idempotency in modo che i tentativi non allocano sessioni duplicate.

I tipi di sessione sono determinati all'ora di checkout dalle intestazioni passate:

Checkin rilascia la sessione:

DELETE /api/sessions/{sessionId}?api-version=2.0

Checkin è fire-and-forget, una 204 No Content risposta significa che la versione è stata accettata e la pulizia viene completata in modo asincrono. Le sessioni inattive vengono rimosse automaticamente dopo 30 minuti di inattività (qualsiasi richiesta MCP o condivisione dello schermo viene conteggiata come attività), ma le applicazioni partner devono sempre controllare le sessioni in modo esplicito al termine del lavoro.

Operazione Computer-Do: in-session

Dopo che l'applicazione partner ha acquisito un PC cloud, gli agenti usano gli strumenti MCP per usarlo. Questi strumenti seguono il protocollo di contesto del modello aperto, in modo che qualsiasi agente che supporta il protocollo possa individuare e richiamare strumenti senza integrazione personalizzata.

Tutto il traffico MCP scorre attraverso l'endpoint MCP della sessione, formato dall'aggiunta /mcp all'oggetto computerUrl restituito alla cassa:

POST {computerUrl}/mcp?api-version=1.0

Ogni richiesta deve includere l'intestazione x-ms-computerId corrispondente all'ID computer nell'URL. Ogni POST invia un messaggio JSON-RPC e restituisce una risposta.

Ciclo di vita della sessione MCP. Prima di chiamare uno strumento, il client deve completare l'handshake di inizializzazione MCP:

1. Inviare una initialize richiesta per ricevere le funzionalità del server.
2. Inviare una initialized notifica (nessuna risposta prevista).
3. Inviare chiamate tools/list agli strumenti per individuare gli strumenti disponibili o tools/call richiamarne uno.

L'inizializzazione è necessaria una volta per sessione. Il piano MCP illustra l'interazione con il desktop (mouse, tastiera, acquisizione di screenshot), la gestione delle finestre, l'esecuzione dei comandi, l'automazione del browser e le funzionalità di accessibilità dell'interfaccia utente.

Per il catalogo completo degli strumenti e i relativi schemi dei parametri, vedere Windows 365 for Agents server MCP.

Computer-See/Take-Control: supervisione umana

Screenshare SDK consente a un'applicazione partner di incorporare l'osservazione umana in tempo reale dell'attività dell'agente direttamente nella propria interfaccia utente. Trasmette il CLOUD PC dell'agente su WebRTC e, quando necessario, inoltra l'input di mouse e tastiera alla sessione. L'SDK crea un iframe all'interno della pagina che gestisce tutte le chiamate API di streaming video, inoltro di input e condivisione dello schermo, in modo che l'applicazione non parli mai direttamente con lo stack di streaming.

Il visualizzatore si connette all'oggetto screenshareUrl restituito al momento del checkout. Non è necessaria alcuna costruzione di endpoint di condivisione dello schermo separata, l'SDK deriva le chiamate dall'URL di base e dall'ID computer forniti.

Flusso di integrazione

L'applicazione partner esegue il check-out di una sessione, carica l'SDK dalla rete CDN e consegna il token di connessione e restituito screenshareUrl a un ScreenShareVieweroggetto . L'iframe prende il posto di qui, chiamando l'API di condivisione dello schermo ARI e aggiungendo la videochiamata per conto dell'utente:

Partner application                       ARI service
  │                                          │
  │  POST /api/pools/{poolId}/sessions       │
  │  ──────────────────────────────────────→ │
  │                                          │
  │  200 OK { screenshareUrl: "…" }          │
  │  ←────────────────────────────────────── │
  │                                          │
  │  Load screenshare-embed.js from CDN      │
  │  new ScreenShareViewer(container,        │
  │      baseUrl, computerId)                │
  │  viewer.connect(bearerToken)             │
  │  ─── postMessage to iframe ────────────→ │
  │                                          │
  │      iframe calls ARI screenshare API    │
  │      iframe joins ACS video call         │
  │      live video streams back             │
  │  ←────────────────────────────────────── │

Distribuzione dell'SDK

L'SDK viene pubblicato per ogni ambiente. Caricare la screenshare-embed.js compilazione che corrisponde all'anello su cui viene eseguita l'applicazione:

Distribuzione dell'SDK

L'SDK viene pubblicato per ogni ambiente. Caricare la screenshare-embed.js compilazione che corrisponde all'anello su cui viene eseguita l'applicazione:

Metodi visualizzatore

Un'istanza ScreenShareViewer espone l'intero ciclo di vita della sessione, la connessione, l'handoff facoltativo del controllo, l'aggiornamento del token e l'interruzione:

Risposte agli errori

Gli errori vengono visualizzati attraverso l'evento error con un codice e un messaggio. Ogni codice esegue il mapping a un'azione di ripristino specifica:

Guida introduttiva

Pagina minima che monta un visualizzatore in un contenitore e lo connette a una sessione già estratta. Si presuppone che si disponga della risposta di checkout (vedere la sezione 6.1) e di un token di connessione (vedere la sezione 2.2):

<!DOCTYPE html>
<html>
<head><title>Screen Share</title></head>
<body>
    <div id="viewer" style="width: 100%; height: 600px;"></div>

    <script src="https://packages.global.cloudinferenceplatform-int.azure.com/screenshare-sdk/latest/screenshare-embed.js"></script>
    <script>
        // Assumes you already have the checkout response (Section 6.1) and bearer token (Section 2.2)
        var computerUrl = checkoutResponse.computerUrl;
        var computerId = checkoutResponse.computerId;

        var viewer = new ScreenShareViewer({
            container: document.getElementById('viewer'),
            baseUrl: computerUrl,
            computerId: computerId
        });

        viewer.on('error', function (code, msg) {
            console.error(code, msg);
        });

        viewer.connect(bearerToken);
    </script>
</body>
</html>

Riepilogo di Surface

Come si adattano insieme

Le superfici funzionano in sequenza, con un chiaro handoff tra i chiamanti:

1. Gli amministratori e i creatori di agenti usano Computer-Create per effettuare il provisioning del pool.
2. L'applicazione partner chiama Checkout on Computer-Get per riservare un PC cloud per un lavoro specifico dell'agente, specificando il tipo di sessione tramite le intestazioni della richiesta.
3. L'agente di intelligenza artificiale inizializza la sessione {computerUrl}/mcp MCP su e guida il CLOUD PC tramite gli strumenti Computer-Do . La maggior parte delle chiamate scorre attraverso questo piano.
4. Quando necessario, l'applicazione partner richiama azioni {screenshareUrl}Computer-See per conto di un utente per osservare o assumere il controllo.
5. L'applicazione partner chiama Checkin su Computer-Get per rilasciare il CLOUD PC al termine del lavoro. Le sessioni lasciate inattive per 30 minuti vengono rimosse automaticamente.

Passaggi successivi

• Altre informazioni su Windows 365 for Agents server MCP.
• Informazioni sull'architettura Windows 365 for Agents.
• Informazioni sul ciclo di vita della sessione dell'agente.

Contenuto correlato

• Pool di agenti cloud PC
• Modello di autenticazione dell'agente
• Che cos'è Windows 365 for Agents?