Descrição geral da API W365 for Agents

Importante

Windows 365 for Agents está em pré-visualização pública. A funcionalidade está em desenvolvimento ativo e pode mudar antes da disponibilidade geral.

Windows 365 for Agents expõe as capacidades através 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 utilizam estas APIs para aprovisionar e governar a capacidade do conjunto.
  • Windows 365 for Agents API de sessão para gestão de sessões de runtime. As aplicações parceiras chamam esta API para marcar um PC na Cloud e, em seguida, lançam-na quando o trabalho estiver concluído.
  • Ferramentas do Protocolo de Contexto de Modelo (MCP) para a operação na sessão. Os agentes de IA invocam estas ferramentas através do ponto final do MCP por sessão. Para a partilha de ecrã, uma aplicação parceira invoca ações de partilha de ecrã em nome de um ser humano.

Em conjunto, estas superfícies abrangem o aprovisionamento do conjunto, a aquisição de um PC na Cloud, a realização de trabalho e a observação ou assistência, conforme necessário.

Computer-Create: administration

Do lado do microsoft API do Graph, o plano Computer-Create utiliza o API do Graph W365A e o portal de administração do W365. Através destas superfícies, os administradores e os fornecedores independentes de software (ISVs) podem:

  • Aprovisionar conjuntos de agentes do CLOUD PC.
  • Configurar políticas e imagens.
  • Registar autores de chamadas de parceiro fidedignos.
  • Contagens de conjuntos de dimensionamento.
  • Anexe a medição através da faturação mac.

Computer-Get: finalização da sessão e entrada

O plano de Computer-Get é uma pequena superfície de controlo de runtime para aplicações parceiras, servida pela API de sessão Windows 365 for Agents (não pelo Microsoft Graph).

A finalização da compra reserva um PC na Cloud e devolve a identidade da sessão e os URLs de ligação:

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

Uma finalização da compra bem-sucedida devolve:

  • sessionId : o identificador da sessão
  • computerUrl : URL base para chamadas de ferramentas MCP (acrescentar /mcp)
  • screenshareUrl : URL base para ações de partilha de ecrã

A finalização da compra pode demorar até 30 segundos enquanto um dispositivo é atribuído. Utilize o x-ms-sessionId cabeçalho (um UUID v4) como uma chave de idempotência para que as repetições não aloquem sessões duplicadas.

Os tipos de sessão são determinados no momento da finalização da compra pelos cabeçalhos que passar:

Tipo Cabeçalhos Objetivo
HumanUser (predefinição) user-object-id Standard sessão interativa vinculada a uma identidade do AAD.
Agente x-ms-authorization-auxiliary (token de identidade do agente) + user-object-id (ID de utilizador do agente) Sessão condicionada por agente. O token auxiliar identifica o agente específico que está a pedir acesso. Contacto wcxcipai@microsoft.com para a configuração do inquilino.
Local Nenhum dos cabeçalhos Sessão de conta de sistema sem enlace de utilizador do AAD.

Checkin lança a sessão:

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

Checkin é fire-and-forget, uma 204 No Content resposta significa que a libertação foi aceite e a limpeza é concluída de forma assíncrona. As sessões inativas são expulsas automaticamente após 30 minutos de inatividade (qualquer pedido MCP ou screenshare conta como atividade), mas as aplicações parceiras devem sempre marcar sessões explicitamente quando o trabalho estiver concluído.

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

Depois de a aplicação parceira adquirir um PC na Cloud, os agentes utilizam ferramentas MCP para operá-lo. Estas ferramentas seguem o Protocolo de Contexto de Modelo aberto, para que qualquer agente que suporte o protocolo possa detetar e invocar ferramentas sem integração personalizada.

Todo o tráfego MCP flui através do ponto final mcP da sessão, formado ao acrescentar /mcp ao computerUrl devolvido na finalização da compra:

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

Cada pedido tem de incluir o x-ms-computerId cabeçalho que corresponde ao ID do computador no URL. Cada POST envia uma mensagem JSON-RPC e devolve uma resposta.

Ciclo de vida da sessão MCP. Antes de chamar qualquer ferramenta, o cliente tem de concluir o handshake de inicialização do MCP:

  1. Enviar um initialize pedido para receber as capacidades do servidor.
  2. Enviar uma initialized notificação (nenhuma resposta esperada).
  3. Emita chamadas tools/list de ferramentas para detetar 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 do ambiente de trabalho (rato, teclado, captura de ecrã), gestão de janelas, execução de comandos, automatização do browser e capacidades de acessibilidade da IU.

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

Computer-See: supervisão humana

Para a supervisão humana, a aplicação parceira utiliza Computer-See para observar e, opcionalmente, co-conduzir a mesma sessão do Cloud PC que o agente está a utilizar. As ações de partilha de ecrã são invocadas contra as devolvidas na finalização da screenshareUrl compra:

POST {screenshareUrl}?screenshareAction={action}&api-version=1.0

O x-ms-computerId cabeçalho é obrigatório e tem de corresponder ao ID do computador no URL. São suportadas quatro ações:

Ação Objetivo
Start Iniciar a partilha de ecrã. Devolve um URL de visualizador WebRTC (seeUrl) para ligar à transmissão em fluxo.
Stop Terminar partilha de ecrã.
TakeControl Assuma o controlo remoto do rato e do teclado. O chamador mais recente ganha sempre, não há rejeição.
ReleaseControl Liberte o controlo remoto novamente para o agente.

Fluxo de redirecionamento de dispositivos e multimédia através da pilha WebRTC. Esta pilha fornece uma experiência de visualização e controlo comparável a uma sessão de ambiente de trabalho remoto padrão, enquanto o agente continua a funcionar no mesmo contexto de sessão.

Resumo do Surface

Surface Plano Ponto de extremidade Chamado por Objetivo
API do Graph Computer-Create Portal de administração do W365A API do Graph e W365 Administrador de TI ou ISV Formatar e manter o conjunto.
API de Sessão Computer-Get POST /api/pools/{poolId}/sessions (Finalização da compra) Aplicação de parceiro Reservar um PC na Cloud.
API de Sessão Computer-Get DELETE /api/sessions/{sessionId} (Checkin) Aplicação de parceiro Liberte o PC na Cloud.
MCP Computer-Do POST {computerUrl}/mcp Agente de IA Operar o PC na Cloud.
Partilha de ecrã Computer-See, Computer-TakeControl POST {screenshareUrl}?screenshareAction=… Aplicação de parceiro, em nome de um humano Observe e co-drive.

Como se encaixam

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

  1. Os administradores e os criadores de agentes utilizam Computer-Create para aprovisionar o conjunto.
  2. A aplicação parceira chama Checkout no Computer-Get para reservar um CLOUD PC para uma parte específica do trabalho do agente, especificando o tipo de sessão através de cabeçalhos de pedido.
  3. O agente de IA inicializa a sessão mcP e {computerUrl}/mcp conduz o PC na Cloud através das ferramentas Computer-Do . A maioria das chamadas passa por este avião.
  4. Quando necessário, a aplicação parceira invoca ações {screenshareUrl}Computer-See em nome de um ser humano para observar ou assumir o controlo.
  5. A aplicação parceira chama Checkin no Computer-Get para libertar o PC na Cloud quando o trabalho estiver concluído. As sessões deixadas inativas durante 30 minutos são automaticamente expulsas.

Próximas etapas

Conteúdo relacionado

  • Last updated on