Visão geral da API do W365 for Agents

O Windows 365 for Agents expõe recursos por meio de superfícies complementares que mapeiam para o ciclo de vida da sessão do agente:

• APIs do Microsoft Graph para administração. Os administradores de TI e os criadores de agentes usam essas APIs para provisionar e controlar a capacidade do pool.
• API de sessão do Windows 365 for Agents para gerenciamento de sessão de runtime. Os aplicativos parceiros chamam essa API para marcar um PC na nuvem e liberá-la quando o trabalho for concluído.
• Ferramentas MCP (Model Context Protocol) para operação na sessão. Os agentes de IA invocam essas ferramentas por meio do ponto de extremidade MCP por sessão. Para compartilhamento de tela, um aplicativo parceiro invoca ações de compartilhamento de tela em nome de um humano.

Juntas, essas superfícies abrangem o provisionamento do pool, a aquisição de um PC na nuvem, a execução do trabalho e a observação ou assistência conforme necessário.

Para obter uma lista completa da documentação da API e um guia de introdução, visite a Documentação do Github do Windows 365 for Agents.

Criação de computador: administração

Do lado do Microsoft API do Graph, o plano Computer-Create usa o API do Graph W365A e o portal de administração do W365. Por meio dessas superfícies, os administradores e ISVs (fornecedores independentes de software) podem:

• Provisione pools de agentes do PC na nuvem.
• Configurar políticas e imagens.
• Registre chamadores de parceiros confiáveis.
• Escalar contagens de pools.
• Anexe a medição por meio da cobrança MAC.

Para saber mais sobre pools de agentes do Cloud PC, consulte a documentação da API do Graph.

Computer-Get: check-out e check-in da sessão

O plano Computer-Get é uma pequena superfície de controle de runtime para aplicativos parceiros, atendida pela API de sessão Windows 365 for Agents (não pelo Microsoft Graph).

O Checkout reserva um PC na nuvem e retorna a identidade da sessão e as URLs de conexão:

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

Um checkout bem-sucedido retorna:

• sessionId : o identificador de sessão
• status: resultado do provisionamento (por exemplo) Succeeded
• computerUrl : URL base para chamadas de ferramenta MCP (acréscimo /mcp)
• screenshareUrl : URL base para ações de compartilhamento de tela
• connectivityUrl : pode ser null, não dependa disso. Sempre use computerUrl para MCP e screenshareUrl para compartilhamento de tela.

O check-out pode levar até 30 segundos enquanto um dispositivo é atribuído. Use o x-ms-sessionId cabeçalho (um UUID v4) como uma chave de idempotência para que novas tentativas não aloquem sessões duplicadas.

Os tipos de sessão são determinados no momento do check-out pelos cabeçalhos que você passa:

O check-in libera a sessão:

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

O check-in requer que o x-ms-sessionId cabeçalho (um UUID v4) corresponda ao sessionId no caminho. É disparar e esquecer: uma 204 No Content resposta significa que a versão foi aceita e a limpeza é concluída de forma assíncrona. As sessões ociosas são removidas automaticamente após 30 minutos de inatividade (qualquer solicitação de compartilhamento de tela ou MCP conta como atividade), mas os aplicativos de parceiros devem sempre marcar sessões explicitamente quando o trabalho for concluído.

Computer-Do: operação na sessão

Depois que o aplicativo parceiro adquire um PC na nuvem, os agentes usam ferramentas MCP para operá-lo. Essas ferramentas seguem o protocolo de contexto de modelo aberto, portanto, qualquer agente compatível com o protocolo pode descobrir e invocar ferramentas sem integração personalizada.

Todo o computerUrl tráfego MCP flui pelo ponto de extremidade MCP da sessão, formado pela anexação /mcp ao retornado no check-out:

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

Cada solicitação deve incluir o x-ms-computerId cabeçalho correspondente à ID do computador na URL. Cada POST envia uma mensagem JSON-RPC e retorna uma resposta.

Ciclo de vida da sessão MCP. O cliente deve concluir o handshake de inicialização do MCP antes de chamar qualquer ferramenta:

1. Envie uma initialize solicitação para receber funcionalidades do servidor.
2. Enviar uma initialized notificação (nenhuma resposta esperada).
3. Emita chamadas tools/list de ferramenta para descobrir ferramentas disponíveis ou tools/call para invocar uma.

A inicialização é necessária uma vez por sessão. O plano MCP abrange a interação da área de trabalho (mouse, teclado, captura de tela), gerenciamento de janelas, execução de comandos, automação do navegador e recursos de acessibilidade da interface do usuário.

Para obter o catálogo completo de ferramentas e seus esquemas de parâmetros, consulte Windows 365 for Agents MCP Server.

Computer-See/Take-Control: supervisão humana

O SDK do Screenshare permite que um aplicativo parceiro incorpore a observação humana em tempo real da atividade do agente diretamente em sua própria interface do usuário. Ele transmite o Cloud PC do agente por WebRTC e, quando necessário, retransmite a entrada do mouse e do teclado de volta para a sessão. O SDK cria um iframe dentro de sua página que lida com todas as chamadas de API de streaming de vídeo, retransmissão de entrada e compartilhamento de tela, para que seu aplicativo nunca se comunique diretamente com a pilha de streaming.

O visualizador se conecta ao retornado na finalização screenshareUrl da compra. Nenhuma construção de ponto de extremidade de compartilhamento de tela separada é necessária, o SDK deriva suas chamadas da URL base () e da ID do computador quecomputerUrl você fornece.

Fluxo de integração

O aplicativo parceiro faz check-out de uma sessão, carrega o SDK da CDN e entrega o token retornado computerUrl e de portador a um ScreenShareViewerarquivo . O iframe assume a partir daí, chamando a API de compartilhamento de tela ARI e ingressando na chamada de vídeo em seu nome:

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

Distribuição do SDK

Carregue a screenshare-embed.js compilação da CDN:

Métodos do visualizador

Uma ScreenShareViewer instância expõe o ciclo de vida completo da sessão, conexão, entrega de controle opcional, atualização de token e desmontagem:

Respostas de erros

Os erros são exibidos no error evento com um código e uma mensagem. Cada código é mapeado para uma ação de recuperação específica:

Início rápido

Uma página mínima que monta um visualizador em um contêiner e o conecta a uma sessão já verificada. Ele pressupõe que você já tenha a resposta de checkout (consulte Computer-Get) e um token de portador (consulte Autenticação):

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

Resumo do Surface

Como eles se encaixam

As superfícies funcionam em sequência, com uma entrega clara entre os chamadores:

1. Administradores e criadores de agentes usam Computer-Create para provisionar o pool.
2. O aplicativo parceiro chama Checkout no Computer-Get para reservar um PC na nuvem para um trabalho específico do agente, especificando o tipo de sessão por meio de cabeçalhos de solicitação.
3. O agente de IA inicializa a sessão de MCP e {computerUrl}/mcp conduz o PC na nuvem por meio das ferramentas de execução do computador . A maioria das chamadas flui por esse plano.
4. Quando necessário, o aplicativo parceiro invoca ações {screenshareUrl}Computer-See em nome de um humano para observar ou assumir.
5. O aplicativo parceiro chama Checkin no Computer-Get para liberar o PC na nuvem quando o trabalho estiver concluído. As sessões deixadas ociosas por 30 minutos são removidas automaticamente.

Próximas etapas

• Saiba mais sobre o servidor MCP do Windows 365 for Agents.
• Saiba mais sobre a arquitetura do Windows 365 for Agents.
• Saiba mais sobre o ciclo de vida da sessão do agente.

Conteúdo relacionado

• Pools de agentes do PC na nuvem
• Modelo de autenticação de agente
• O que é o Windows 365 for Agents?