Introducción a la API de W365 for Agents

Windows 365 for Agents expone las funcionalidades a través de superficies complementarias que se asignan al ciclo de vida de la sesión del agente:

• API de Microsoft Graph para la administración. Los administradores de TI y los creadores de agentes usan estas API para aprovisionar y controlar la capacidad del grupo.
• Windows 365 for Agents API de sesión para la administración de sesiones en tiempo de ejecución. Las aplicaciones asociadas llaman a esta API para desteger un equipo en la nube y, a continuación, liberarlo cuando se complete el trabajo.
• Herramientas del Protocolo de contexto de modelo (MCP) para la operación en sesión. Los agentes de inteligencia artificial invocan estas herramientas a través del punto de conexión MCP por sesión. Para el uso compartido de pantalla, una aplicación asociada invoca acciones de uso compartido de pantalla en nombre de un usuario.

Juntos, estas superficies abarcan el aprovisionamiento del grupo, la adquisición de un equipo en la nube, el trabajo y la observación o la asistencia según sea necesario.

Para obtener una lista completa de la documentación de la API y una guía de introducción, visite la documentación de Windows 365 for Agents Github.

Computer-Create: administration

En el lado de Microsoft Graph API, el plano de Computer-Create usa el Graph API W365A y el portal de administración de W365. A través de estas superficies, los administradores y proveedores de software independientes (ISV) pueden:

• Aprovisionamiento de grupos de agentes de PC en la nube.
• Configure directivas e imágenes.
• Registrar autores de llamadas de asociados de confianza.
• Recuentos de grupos de escalado.
• Adjunte la medición a través de la facturación mac.

Para más información sobre los grupos de agentes de PC en la nube, consulte la documentación de Graph API.

Computer-Get: comprobación y desprotección de sesión

El plano de Computer-Get es una pequeña superficie de control en tiempo de ejecución para aplicaciones asociadas, servida por la API de sesión de Windows 365 for Agents (no Microsoft Graph).

Checkout reserva un equipo en la nube y devuelve la identidad de sesión y las direcciones URL de conexión:

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

Una desprotección correcta devuelve:

• sessionId : el identificador de sesión
• status : resultado del aprovisionamiento (por ejemplo, Succeeded)
• computerUrl : dirección URL base para llamadas a herramientas MCP (anexar /mcp)
• screenshareUrl : dirección URL base para acciones de recurso compartido de pantalla
• connectivityUrl : puede ser null, no dependa de él. computerUrl Use siempre para MCP y screenshareUrl para el uso compartido de pantalla.

La compra puede tardar hasta 30 segundos mientras se asigna un dispositivo. Use el x-ms-sessionId encabezado (un UUID v4) como clave de idempotencia para que los reintentos no asignen sesiones duplicadas.

Los tipos de sesión se determinan en el momento de la compra por los encabezados que se pasan:

Checkin libera la sesión:

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

Checkin requiere el x-ms-sessionId encabezado (un UUID v4) que coincida con en sessionId la ruta de acceso. Es fire-and-forget: una 204 No Content respuesta significa que la versión se aceptó y la limpieza se completa de forma asincrónica. Las sesiones inactivas se expulsan automáticamente después de 30 minutos de inactividad (cualquier MCP o solicitud de recurso compartido de pantalla cuenta como actividad), pero las aplicaciones asociadas siempre deben proteger las sesiones de forma explícita cuando se complete el trabajo.

Computer-Do: operación en sesión

Una vez que la aplicación asociada adquiere un equipo en la nube, los agentes usan herramientas de MCP para operarlo. Estas herramientas siguen el protocolo de contexto de modelo abierto, por lo que cualquier agente que admita el protocolo puede detectar e invocar herramientas sin integración personalizada.

Todo el tráfico MCP fluye a través del punto de conexión MCP de la sesión, formado por anexar /mcp al devuelto en la computerUrl compra:

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

Cada solicitud debe incluir el x-ms-computerId encabezado que coincida con el identificador de equipo en la dirección URL. Cada POST envía un mensaje JSON-RPC y devuelve una respuesta.

Ciclo de vida de sesión de MCP. El cliente debe completar el protocolo de enlace de inicialización de MCP antes de llamar a cualquier herramienta:

1. Enviar una initialize solicitud para recibir funcionalidades del servidor.
2. Enviar una initialized notificación (no se espera ninguna respuesta).
3. Emita llamadas tools/list a herramientas para detectar herramientas disponibles o tools/call para invocar una.

La inicialización es necesaria una vez por sesión. El plano MCP cubre la interacción del escritorio (mouse, teclado, captura de pantalla), administración de ventanas, ejecución de comandos, automatización del explorador y funcionalidades de accesibilidad de la interfaz de usuario.

Para ver el catálogo completo de herramientas y sus esquemas de parámetros, consulte Windows 365 for Agents servidor MCP.

Computer-See/Take-Control: supervisión humana

El SDK de Screenshare permite a una aplicación asociada insertar la observación humana en tiempo real de la actividad del agente directamente en su propia interfaz de usuario. Transmite el equipo en la nube del agente a través de WebRTC y, cuando sea necesario, retransmite la entrada del mouse y del teclado a la sesión. El SDK crea un iframe dentro de la página que controla todas las llamadas API de streaming de vídeo, retransmisión de entrada y recurso compartido de pantalla, por lo que la aplicación nunca se comunica directamente con la pila de streaming.

El visor se conecta al screenshareUrl devuelto al finalizar la compra. No se requiere ninguna construcción de punto de conexión de recurso compartido de pantalla independiente, el SDK deriva sus llamadas desde la dirección URL base (computerUrl) y el identificador de equipo que proporcione.

Flujo de integración

La aplicación asociada extrae una sesión, carga el SDK de la red CDN y entrega el token devuelto computerUrl y portador a .ScreenShareViewer El iframe toma el control desde allí, llamando a la API de recurso compartido de pantalla ARI y uniéndose a la videollamada en su nombre:

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

Distribución del SDK

Cargue la screenshare-embed.js compilación desde la red CDN:

Métodos de visor

Una ScreenShareViewer instancia expone el ciclo de vida completo de la sesión, la conexión, la entrega de control opcional, la actualización de tokens y el desmontaje:

Respuestas de error

Los errores aparecen a través del error evento con un código y un mensaje. Cada código se asigna a una acción de recuperación específica:

Inicio rápido

Página mínima que monta un visor en un contenedor y lo conecta a una sesión ya desprotegida. Se supone que ya tiene la respuesta de desprotección (consulte Computer-Get) y un token de portador (consulte Autenticación):

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

Resumen de Surface

Cómo encajan juntos

Las superficies funcionan en secuencia, con una entrega clara entre los autores de llamadas:

1. Los administradores y creadores de agentes usan Computer-Create para aprovisionar el grupo.
2. La aplicación asociada llama a Checkout en Computer-Get para reservar un equipo en la nube para un trabajo de agente específico, especificando el tipo de sesión a través de encabezados de solicitud.
3. El agente de inteligencia artificial inicializa la sesión mcp en {computerUrl}/mcp y controla el equipo en la nube a través de las herramientas de computer-do . La mayoría de las llamadas fluyen a través de este plano.
4. Cuando sea necesario, la aplicación asociada invoca acciones Computer-See en {screenshareUrl} nombre de un humano para observar o asumir el control.
5. La aplicación asociada llama a Checkin en Computer-Get para liberar el equipo en la nube cuando se realiza el trabajo. Las sesiones que quedan inactivas durante 30 minutos se expulsan automáticamente.

Pasos siguientes

• Más información sobre Windows 365 for Agents servidor MCP.
• Obtenga información sobre la arquitectura de Windows 365 for Agents.
• Obtenga información sobre el ciclo de vida de la sesión del agente.

Contenido relacionado

• Grupos de agentes de PC en la nube
• Modelo de autenticación del agente
• ¿Qué es Windows 365 for Agents?