Overzicht van W365 for Agents API

Windows 365 for Agents maakt mogelijkheden beschikbaar via aanvullende oppervlakken die zijn toegewezen aan de levenscyclus van de agentsessie:

• Microsoft Graph API's voor beheer. IT-beheerders en agentmakers gebruiken deze API's om poolcapaciteit in te richten en te beheren.
• Windows 365 for Agents sessie-API voor runtimesessiebeheer. Partnertoepassingen roepen deze API aan om een cloud-pc te bekijken en deze vervolgens vrij te geven wanneer het werk is voltooid.
• MCP-hulpprogramma's (Model Context Protocol) voor in-sessiebewerkingen. AI-agents roepen deze hulpprogramma's aan via het MCP-eindpunt per sessie. Voor scherm delen roept een partnertoepassing namens een persoon screenshare-acties aan.

Deze oppervlakken omvatten samen het inrichten van de pool, het verkrijgen van een cloud-pc, het uitvoeren van werk en het observeren of helpen indien nodig.

Ga voor een volledige lijst met API-documentatie en een handleiding aan de slag naar de Windows 365 for Agents Github-documentatie.

Computer maken: beheer

Aan de zijde van Microsoft Graph API maakt het Computer-Create vlak gebruik van de W365A Graph API en de W365-beheerportal. Via deze surfaces kunnen beheerders en onafhankelijke softwareleveranciers (ISV's) het volgende doen:

• Cloud-PC-agentgroepen inrichten.
• Beleidsregels en installatiekopieën configureren.
• Registreer bellers van vertrouwde partners.
• Aantal schaalgroepen.
• Koppel metering via MAC-facturering.

Zie de documentatie voor Graph API voor meer informatie over cloud-pc-agentgroepen.

Computer-Get: sessie uitchecken en inchecken

Het Computer-Get vlak is een klein runtime-besturingsoppervlak voor partnertoepassingen, dat wordt bediend door de Windows 365 for Agents sessie-API (niet Microsoft Graph).

Checkout reserveert een cloud-pc en retourneert de sessie-id en verbindings-URL's:

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

Een geslaagde betaling retourneert:

• sessionId : de sessie-id
• status : inrichtingsresultaat (bijvoorbeeld Succeeded)
• computerUrl : basis-URL voor MCP-hulpprogramma-aanroepen (toevoegen /mcp)
• screenshareUrl : basis-URL voor acties voor schermshares
• connectivityUrl : is nullmogelijk , niet afhankelijk ervan. Altijd gebruiken computerUrl voor MCP en screenshareUrl voor het delen van het scherm.

Het uitchecken kan tot 30 seconden duren terwijl een apparaat is toegewezen. Gebruik de x-ms-sessionId header (een UUID v4) als idempotentiesleutel, zodat nieuwe pogingen geen dubbele sessies toewijzen.

Sessietypen worden tijdens het afrekenen bepaald door de headers die u doorgeeft:

Checkin geeft de sessie vrij:

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

Checkin vereist de x-ms-sessionId header (een UUID v4) die overeenkomt met de sessionId in het pad. Het is onopgemerkt: een 204 No Content antwoord betekent dat de release is geaccepteerd en dat het opschonen asynchroon wordt voltooid. Niet-actieve sessies worden automatisch verwijderd na 30 minuten inactiviteit (elke MCP- of schermshare-aanvraag telt als activiteit), maar partnertoepassingen moeten sessies altijd expliciet controleren wanneer het werk is voltooid.

Computer-Do: in-sessiebewerking

Nadat de partnertoepassing een cloud-pc heeft verkregen, gebruiken agents MCP-hulpprogramma's om deze te bedienen. Deze hulpprogramma's volgen het open Model Context Protocol, zodat elke agent die het protocol ondersteunt hulpprogramma's kan detecteren en aanroepen zonder aangepaste integratie.

Al het MCP-verkeer stroomt via het MCP-eindpunt van de sessie, gevormd door toe te voegen /mcp aan het geretourneerde bij het computerUrl afrekenen:

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

Elke aanvraag moet de x-ms-computerId header bevatten die overeenkomt met de computer-id in de URL. Elke POST verzendt één JSON-RPC-bericht en retourneert één antwoord.

MCP-sessielevenscyclus. De client moet de MCP-initialisatiehanddruk voltooien voordat een hulpprogramma wordt aangeroepen:

1. initialize Een aanvraag verzenden om servermogelijkheden te ontvangen.
2. initialized Een melding verzenden (geen antwoord verwacht).
3. Voer hulpprogramma-aanroepen tools/list uit om beschikbare hulpprogramma's te detecteren of tools/call aan te roepen.

Initialisatie is eenmaal per sessie vereist. Het MCP-vlak bevat bureaubladinteractie (muis, toetsenbord, schermopname), vensterbeheer, opdrachtuitvoering, browserautomatisering en toegankelijkheidsmogelijkheden voor gebruikersinterfaces.

Zie Windows 365 for Agents MCP-server voor de volledige catalogus met hulpprogramma's en de bijbehorende parameterschema's.

Computer-See/Take-Control: menselijk toezicht

Met de Screenshare SDK kan een partnertoepassing realtime menselijke observatie van agentactiviteiten rechtstreeks insluiten in de eigen gebruikersinterface. De cloud-pc van de agent wordt via WebRTC gestreamd en indien nodig wordt de muis- en toetsenbordinvoer teruggegeven aan de sessie. De SDK maakt een iframe op uw pagina dat alle videostreaming, invoerrelay en schermshare-API-aanroepen verwerkt, zodat uw toepassing nooit rechtstreeks met de streamingstack praat.

De viewer maakt verbinding met de screenshareUrl geretourneerde bij het afrekenen. Er is geen afzonderlijke eindpuntconstructie voor schermshares vereist. De SDK leidt de aanroepen af van de basis-URL (computerUrl) en computer-id die u opgeeft.

Integratiestroom

De partnertoepassing controleert een sessie, laadt de SDK van het CDN en geeft het geretourneerde computerUrl en bearer-token aan een ScreenShareViewer. Het iframe neemt het over, roept de API voor ari-schermshare aan en neemt namens u deel aan het videogesprek:

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-distributie

Laad de screenshare-embed.js build vanuit het CDN:

Viewer-methoden

Een ScreenShareViewer exemplaar toont de volledige sessielevenscyclus, verbinding maken, optioneel beheerhandoff, token vernieuwen en teardown:

Foutreacties

Fouten worden tijdens de error gebeurtenis weergegeven met een code en bericht. Elke code is toegewezen aan een specifieke herstelactie:

Snel aan de slag

Een minimale pagina die een viewer koppelt aan een container en deze verbindt met een al uitgecheckte sessie. Er wordt van uitgegaan dat u al het afrekenantwoord (zie Computer-Get) en een bearer-token hebt (zie Verificatie):

<!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-overzicht

Hoe ze in elkaar passen

De oppervlakken werken in volgorde, met een duidelijke handoff tussen bellers:

1. Beheerders en agentmakers gebruiken Computer-Create om de pool in te richten.
2. De partnertoepassing roept Checkout aan op Computer-Get om een cloud-pc te reserveren voor een specifiek stuk agentwerk, waarbij het sessietype wordt opgegeven via aanvraagheaders.
3. De AI-agent initialiseert de MCP-sessie op {computerUrl}/mcp en stuurt de cloud-pc via de Computer-Do-hulpprogramma's . De meeste aanroepen lopen door dit vliegtuig.
4. Indien nodig roept de partnertoepassing Computer-See-acties tegen {screenshareUrl} aan namens een persoon om te observeren of over te nemen.
5. De partnertoepassing roept Checkin aan op Computer-Get om de cloud-pc vrij te geven wanneer het werk is voltooid. Sessies die gedurende 30 minuten inactief blijven, worden automatisch verwijderd.

Volgende stappen

• Meer informatie over Windows 365 for Agents MCP-server.
• Meer informatie over de architectuur van de Windows 365 for Agents.
• Meer informatie over de levenscyclus van de agentsessie.

Verwante onderwerpen

• Cloud-PC-agentgroepen
• Verificatiemodel van agent
• Wat is Windows 365 for Agents?