Vue d’ensemble de l’API W365 for Agents

Windows 365 for Agents expose les fonctionnalités via des surfaces complémentaires qui correspondent au cycle de vie de session de l’agent :

• API Microsoft Graph pour l’administration. Les administrateurs informatiques et les créateurs d’agents utilisent ces API pour approvisionner et régir la capacité du pool.
• API de session Windows 365 for Agents pour la gestion des sessions d’exécution. Les applications partenaires appellent cette API pour case activée un PC cloud, puis la libèrent une fois le travail terminé.
• Outils MCP (Model Context Protocol) pour l’opération en session. Les agents IA appellent ces outils via le point de terminaison MCP par session. Pour le partage d’écran, une application partenaire appelle des actions de partage d’écran au nom d’une personne.

Ensemble, ces surfaces couvrent le provisionnement du pool, l’acquisition d’un PC cloud, l’exécution du travail et l’observation ou l’assistance si nécessaire.

Pour obtenir la liste complète de la documentation de l’API et un guide de prise en main, consultez la documentation Windows 365 for Agents Github.

Computer-Create : administration

Côté API Graph Microsoft, le plan Computer-Create utilise le API Graph W365A et le portail d’administration W365. Grâce à ces surfaces, les administrateurs et les éditeurs de logiciels indépendants (ISV) peuvent :

• Provisionner des pools d’agents de PC cloud.
• Configurez des stratégies et des images.
• Inscrire les appelants de partenaires approuvés.
• Mettre à l’échelle le nombre de pools.
• Attachez le contrôle via la facturation MAC.

Pour en savoir plus sur les pools d’agents de PC cloud, consultez la documentation API Graph.

Computer-Get : validation et archivage de la session

Le plan de Computer-Get est une petite surface de contrôle d’exécution pour les applications partenaires, servie par l’API de session Windows 365 for Agents (et non Microsoft Graph).

Checkout réserve un PC cloud et retourne l’identité de session et les URL de connexion :

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

Une extraction réussie retourne :

• sessionId : identificateur de session
• status : résultat de l’approvisionnement (par exemple Succeeded, )
• computerUrl : URL de base pour les appels d’outils MCP (ajouter /mcp)
• screenshareUrl : URL de base pour les actions de partage d’écran
• connectivityUrl : peut être null, ne dépendez pas de celui-ci. computerUrl Utilisez toujours pour MCP et screenshareUrl pour le partage d’écran.

L’extraction peut prendre jusqu’à 30 secondes pendant qu’un appareil est affecté. Utilisez l’en-tête x-ms-sessionId (un UUID v4) comme clé d’idempotence afin que les nouvelles tentatives n’allouent pas de sessions en double.

Les types de session sont déterminés au moment de l’extraction par les en-têtes que vous passez :

Checkin libère la session :

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

L’archivage nécessite l’en-tête x-ms-sessionId (un UUID v4) correspondant au sessionId dans le chemin d’accès. C’est fire-and-forget : une 204 No Content réponse signifie que la mise en production a été acceptée et que le nettoyage se termine de façon asynchrone. Les sessions inactives sont supprimées automatiquement après 30 minutes d’inactivité (toute demande MCP ou de partage d’écran compte comme activité), mais les applications partenaires doivent toujours case activée sessions explicitement lorsque le travail est terminé.

Computer-Do : opération en session

Une fois que l’application partenaire a acquis un PC cloud, les agents utilisent les outils MCP pour l’utiliser. Ces outils suivent le protocole de contexte de modèle ouvert, de sorte que tout agent qui prend en charge le protocole peut découvrir et appeler des outils sans intégration personnalisée.

Tout le trafic MCP transite par le point de terminaison MCP de la session, formé en ajoutant /mcp au retourné lors de la computerUrl validation :

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

Chaque requête doit inclure l’en-tête x-ms-computerId correspondant à l’ID de l’ordinateur dans l’URL. Chaque POST envoie un message JSON-RPC et retourne une réponse.

Cycle de vie des sessions MCP. Le client doit terminer la négociation d’initialisation MCP avant d’appeler un outil :

1. Envoyez une initialize demande pour recevoir les fonctionnalités du serveur.
2. Envoyer une initialized notification (aucune réponse attendue).
3. Émettre des appels tools/list d’outils pour découvrir les outils disponibles ou tools/call en appeler un.

L’initialisation est requise une fois par session. Le plan MCP couvre l’interaction du bureau (souris, clavier, capture d’écran), la gestion des fenêtres, l’exécution de commandes, l’automatisation du navigateur et les fonctionnalités d’accessibilité de l’interface utilisateur.

Pour obtenir le catalogue complet des outils et leurs schémas de paramètres, consultez Windows 365 for Agents serveur MCP.

Computer-See/Take-Control : human supervision

Le SDK Screenshare permet à une application partenaire d’incorporer une observation humaine en temps réel de l’activité de l’agent directement dans sa propre interface utilisateur. Il diffuse en continu le PC cloud de l’agent via WebRTC et, si nécessaire, relaie l’entrée de la souris et du clavier à la session. Le SDK crée un iframe à l’intérieur de votre page qui gère tous les appels d’API de streaming vidéo, de relais d’entrée et de partage d’écran, de sorte que votre application ne communique jamais directement avec la pile de streaming.

La visionneuse se connecte au retourné lors de la screenshareUrl validation. Aucune construction de point de terminaison de partage d’écran distincte n’est requise. Le SDK dérive ses appels de l’URL de base (computerUrl) et de l’ID d’ordinateur que vous fournissez.

Flux d’intégration

L’application partenaire extrait une session, charge le Kit de développement logiciel (SDK) à partir du CDN, puis remet le jeton retourné computerUrl et le jeton du porteur à un ScreenShareViewer. L’iframe prend le relais à partir de là, en appelant l’API de partage d’écran ARI et en rejoignant l’appel vidéo en votre nom :

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

Distribution du Kit de développement logiciel (SDK

Chargez la screenshare-embed.js build à partir du CDN :

Méthodes de visionneuse

Une ScreenShareViewer instance expose le cycle de vie complet de la session, la connexion, le transfert de contrôle facultatif, l’actualisation du jeton et la désactivation :

Réponses d’erreur

Des erreurs apparaissent dans l’événement error avec un code et un message. Chaque code est mappé à une action de récupération spécifique :

Démarrage rapide

Page minimale qui monte une visionneuse dans un conteneur et la connecte à une session déjà extraite. Cela suppose que vous disposez déjà de la réponse de validation (voir Computer-Get) et d’un jeton du porteur (voir Authentification) :

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

Résumé de Surface

Comment ils s’emboîtent

Les surfaces fonctionnent dans l’ordre, avec un transfert clair entre les appelants :

1. Les administrateurs et les créateurs d’agents utilisent Computer-Create pour approvisionner le pool.
2. L’application partenaire appelle Checkout on Computer-Get pour réserver un PC cloud pour un travail d’agent spécifique, en spécifiant le type de session via les en-têtes de requête.
3. L’agent IA initialise la session MCP sur {computerUrl}/mcp et pilote le PC cloud via les outils Computer-Do . La plupart des appels transitent par ce plan.
4. Si nécessaire, l’application partenaire appelle des actions Computer-See contre {screenshareUrl} au nom d’un humain pour observer ou prendre le contrôle.
5. L’application partenaire appelle Checkin sur Computer-Get pour libérer le PC cloud une fois le travail terminé. Les sessions laissées inactives pendant 30 minutes sont supprimées automatiquement.

Étapes suivantes

• En savoir plus sur Windows 365 for Agents serveur MCP.
• Découvrez l’architecture Windows 365 for Agents.
• En savoir plus sur le cycle de vie de la session de l’agent.

Contenu connexe

• Pools d’agents de PC cloud
• Modèle d’authentification de l’agent
• Qu’est-ce que Windows 365 for Agents ?