Übersicht über die W365-API für Agents

Windows 365 for Agents macht Funktionen über komplementäre Oberflächen verfügbar, die dem Lebenszyklus der Agentsitzung zugeordnet sind:

• Microsoft Graph-APIs für die Verwaltung. IT-Administratoren und Agent-Entwickler verwenden diese APIs zum Bereitstellen und Steuern der Poolkapazität.
• Windows 365 for Agents Sitzungs-API für die Laufzeitsitzungsverwaltung. Partneranwendungen rufen diese API auf, um einen Cloud-PC auszuchecken und dann nach Abschluss der Arbeit freizugeben.
• MCP-Tools (Model Context Protocol) für sitzungsinterne Vorgänge. KI-Agents rufen diese Tools über den MCP-Endpunkt pro Sitzung auf. Für die Bildschirmfreigabe ruft eine Partneranwendung Screenshare-Aktionen im Namen eines Menschen auf.

Zusammen decken diese Oberflächen die Bereitstellung des Pools, den Erwerb eines Cloud-PCs, die Ausführung von Arbeiten und das Beobachten oder Unterstützen bei Bedarf ab.

Eine vollständige Liste der API-Dokumentation und einen Leitfaden zu den ersten Schritten finden Sie in der Windows 365 for Agents GitHub-Dokumentation.

Computer-Erstellen: Verwaltung

Aufseiten von Microsoft Graph-API verwendet die Computer-Create ebene die W365A-Graph-API und das W365-Verwaltungsportal. Über diese Oberflächen können Administratoren und unabhängige Softwarehersteller (INDEPENDENT Software Vendors, ISVs) folgende Möglichkeiten haben:

• Bereitstellen von Cloud-PC-Agent-Pools.
• Konfigurieren sie Richtlinien und Images.
• Vertrauenswürdige Partneranrufer registrieren.
• Anzahl von Skalierungspools.
• Fügen Sie die Messung über die MAC-Abrechnung an.

Weitere Informationen zu Cloud-PC-Agent-Pools finden Sie in der Graph-API-Dokumentation.

Computer-Get: Sitzungschecken und Einchecken

Die Computer-Get-Ebene ist eine kleine Laufzeitsteuerungsoberfläche für Partneranwendungen, die von der Windows 365 for Agents-Sitzungs-API (nicht Microsoft Graph) bereitgestellt wird.

Checkout reserviert einen Cloud-PC und gibt die Sitzungsidentität und die Verbindungs-URLs zurück:

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

Ein erfolgreiches Auschecken gibt Folgendes zurück:

• sessionId : Der Sitzungsbezeichner
• status : Bereitstellungsergebnis (z. B. Succeeded)
• computerUrl : Basis-URL für MCP-Toolaufrufe (anfügen /mcp)
• screenshareUrl : Basis-URL für Bildschirmfreigabeaktionen
• connectivityUrl : kann sein null, nicht davon abhängig. Verwenden Sie computerUrl immer für MCP und screenshareUrl für die Bildschirmfreigabe.

Das Auschecken kann bis zu 30 Sekunden dauern, während ein Gerät zugewiesen ist. Verwenden Sie den x-ms-sessionId Header (eine UUID v4) als Idempotenzschlüssel, damit Wiederholungen keine doppelten Sitzungen zuordnen.

Sitzungstypen werden zum Zeitpunkt des Auscheckens durch die übergebenen Header bestimmt:

Check-in gibt die Sitzung frei:

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

Für das Einchecken ist der x-ms-sessionId Header (eine UUID v4) erforderlich, der mit im sessionId Pfad übereinstimmt. Es ist fire-and-forget: Eine 204 No Content Antwort bedeutet, dass das Release akzeptiert wurde und die Bereinigung asynchron abgeschlossen wird. Leerlaufsitzungen werden nach 30 Minuten Inaktivität automatisch entfernt (jede MCP- oder Bildschirmfreigabeanforderung zählt als Aktivität), aber Partneranwendungen sollten Sitzungen immer explizit einchecken, wenn die Arbeit abgeschlossen ist.

Computer-Do: In-Session-Vorgang

Nachdem die Partneranwendung einen Cloud-PC erworben hat, verwenden Agents MCP-Tools, um ihn zu betreiben. Diese Tools folgen dem offenen Modellkontextprotokoll, sodass jeder Agent, der das Protokoll unterstützt, Tools ohne benutzerdefinierte Integration ermitteln und aufrufen kann.

Der gesamte MCP-Datenverkehr fließt durch den MCP-Endpunkt der Sitzung, der durch Anfügen /mcp an den computerUrl zurückgegebenen beim Auschecken gebildet wird:

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

Jede Anforderung muss den x-ms-computerId Header enthalten, der mit der Computer-ID in der URL übereinstimmt. Jede POST sendet eine JSON-RPC-Nachricht und gibt eine Antwort zurück.

MCP-Sitzungslebenszyklus. Der Client muss den MCP-Initialisierungshandhake abschließen, bevor er ein Tool aufruft:

1. Senden sie eine initialize Anforderung zum Empfangen von Serverfunktionen.
2. Senden einer initialized Benachrichtigung (keine Antwort erwartet).
3. Führen Sie Toolaufrufe tools/list aus, um verfügbare Tools zu ermitteln oder tools/call eines aufzurufen.

Die Initialisierung ist einmal pro Sitzung erforderlich. Die MCP-Ebene umfasst Desktopinteraktion (Maus, Tastatur, Screenshotaufnahme), Fensterverwaltung, Befehlsausführung, Browserautomatisierung und Barrierefreiheit der Benutzeroberfläche.

Den vollständigen Katalog der Tools und deren Parameterschemas finden Sie unter Windows 365 for Agents MCP-Server.

Computer-See/Take-Control: Menschliche Aufsicht

Mit dem Screenshare SDK kann eine Partneranwendung die Menschliche Beobachtung von Agent-Aktivitäten in Echtzeit direkt in die eigene Benutzeroberfläche einbetten. Es streamt den Cloud-PC des Agents über WebRTC und leitet bei Bedarf Maus- und Tastatureingaben an die Sitzung weiter. Das SDK erstellt einen iFrame auf Ihrer Seite, der alle Videostreaming-, Eingaberelay- und Bildschirmfreigabe-API-Aufrufe verarbeitet, sodass Ihre Anwendung niemals direkt mit dem Streamingstapel kommuniziert.

Der Viewer stellt eine Verbindung mit dem an der screenshareUrl Kasse zurückgegebenen her. Es ist keine separate Erstellung des Endpunkts für die Bildschirmfreigabe erforderlich. Das SDK leitet seine Aufrufe von der Basis-URL (computerUrl) und der Computer-ID ab, die Sie angeben.

Integrationsflow

Die Partneranwendung checkt eine Sitzung aus, lädt das SDK aus dem CDN und übergibt das zurückgegebene computerUrl Token und das Bearertoken an ein ScreenShareViewer. Der iframe übernimmt von dort aus die ARI-Bildschirmfreigabe-API und nimmt an dem Videoanruf in Ihrem Namen teil:

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            │
        │  ←──────────────────────────────────────│

SDK-Verteilung

Laden Sie den screenshare-embed.js Build aus dem CDN:

Viewer-Methoden

Ein ScreenShareViewer instance den vollständigen Sitzungslebenszyklus, die Verbindung, die optionale Steuerungsweitergabe, die Tokenaktualisierung und das Beenden verfügbar macht:

Fehlerantworten

Fehler werden durch das error Ereignis mit einem Code und einer Meldung angezeigt. Jeder Code wird einer bestimmten Wiederherstellungsaktion zugeordnet:

Schnellstart

Eine minimale Seite, die einen Viewer in einen Container einbindet und ihn mit einer bereits ausgecheckten Sitzung verbindet. Es wird davon ausgegangen, dass Sie bereits über die Auscheckantwort (siehe Computer-Get) und ein Bearertoken (siehe Authentifizierung) verfügen:

<!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.azure.com/screenshare-sdk/latest/screenshare-embed.js"></script>
    <script>
        // Assumes you already have the checkout response (see Computer-Get)
        // and a bearer token (see Authentication).
        var computerUrl = checkoutResponse.computerUrl;
        // computerId is embedded in computerUrl as /computers/{computerId}
        var computerId = computerUrl.split('/computers/')[1];

        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>

Surface-Zusammenfassung

Wie sie zusammenpassen

Die Oberflächen funktionieren nacheinander, mit einer klaren Übergabe zwischen den Anrufern:

1. Administratoren und Agent-Ersteller verwenden Computer-Create , um den Pool bereitzustellen.
2. Die Partneranwendung ruft Checkout auf Computer-Get auf, um einen Cloud-PC für eine bestimmte Agent-Arbeit zu reservieren und die Sitzungsart über Anforderungsheader anzugeben.
3. Der KI-Agent initialisiert die MCP-Sitzung für {computerUrl}/mcp und steuert den Cloud-PC über die Computer-Do-Tools . Die meisten Aufrufe durchlaufen diese Ebene.
4. Bei Bedarf ruft die Partneranwendung Computer-See-Aktionen{screenshareUrl} im Namen eines Menschen auf, um sie zu beobachten oder zu übernehmen.
5. Die Partneranwendung ruft Checkin auf Computer-Get auf, um den Cloud-PC freizugeben, wenn die Arbeit abgeschlossen ist. Sitzungen, die 30 Minuten im Leerlauf verbleiben, werden automatisch entfernt.

Nächste Schritte

• Erfahren Sie mehr über Windows 365 for Agents MCP-Server.
• Erfahren Sie mehr über die Windows 365 for Agents-Architektur.
• Erfahren Sie mehr über den Agent-Sitzungslebenszyklus.

Verwandte Inhalte

• Cloud-PC-Agentpools
• Agent-Authentifizierungsmodell
• Was ist Windows 365 for Agents?