Omówienie interfejsu API usługi W365 for Agents

Windows 365 for Agents uwidacznia możliwości poprzez uzupełniające się powierzchnie mapowane na cykl życia sesji agenta:

• Interfejsy API programu Microsoft Graph do administrowania. Administratorzy IT i twórcy agentów używają tych interfejsów API do aprowizowania pojemności puli i zarządzania nią.
• Windows 365 for Agents interfejs API sesji na potrzeby zarządzania sesjami środowiska uruchomieniowego. Aplikacje partnerskie nazywają ten interfejs API, aby wyewidencjonować komputer w chmurze, a następnie wydać go po zakończeniu pracy.
• Narzędzia protokołu MCP (Model Context Protocol) do operacji w sesji. Agenci sztucznej inteligencji wywołują te narzędzia za pośrednictwem punktu końcowego MCP dla sesji. W przypadku udostępniania ekranu aplikacja partnera wywołuje akcje udostępniania ekranu w imieniu człowieka.

Razem te powierzchnie obejmują aprowizację puli, uzyskiwanie komputera w chmurze, wykonywanie pracy oraz obserwowanie lub pomoc w razie potrzeby.

Pełną listę dokumentacji interfejsu API i przewodnik wprowadzający można znaleźć w dokumentacji usługi Github Windows 365 for Agents.

Tworzenie komputera: administracja

Po stronie interfejs interfejs Graph API firmy Microsoft płaszczyzna Computer-Create używa interfejs interfejs Graph API W365A i portalu administracyjnego W365. Dzięki tym obszarom administratorzy i niezależni dostawcy oprogramowania mogą:

• Aprowizowanie pul agentów komputerów w chmurze.
• Konfigurowanie zasad i obrazów.
• Rejestrowanie zaufanych rozmówców partnerów.
• Skalowanie liczby pul.
• Dołączanie pomiarów za pośrednictwem rozliczeń mac.

Aby dowiedzieć się więcej o pulach agentów komputerów w chmurze, zobacz dokumentację interfejs interfejs Graph API.

Computer-Get: wyewidencjonowynie sesji i ewidencjonowania

Płaszczyzna Computer-Get to mała powierzchnia sterowania środowiska uruchomieniowego dla aplikacji partnerskich obsługiwana przez interfejs API sesji Windows 365 for Agents (a nie program Microsoft Graph).

Wyewidencjonowanie rezerwuje komputer w chmurze i zwraca adresy URL tożsamości sesji i połączenia:

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

Pomyślne wyewidencjonowynie zwraca:

• sessionId : identyfikator sesji
• status : wynik aprowizacji (np. Succeeded)
• computerUrl : podstawowy adres URL wywołań narzędzi MCP (dołącz /mcp)
• screenshareUrl : podstawowy adres URL akcji udostępniania ekranu
• connectivityUrl : może być null, nie zależą od niego. Zawsze używaj funkcji computerUrl mcp i screenshareUrl udostępniania ekranu.

Wyewidencjonowanie może potrwać do 30 sekund podczas przypisywania urządzenia. Użyj nagłówka x-ms-sessionId (UUID w wersji 4) jako klucza idempotency, aby ponowne próby nie przydzielały zduplikowanych sesji.

Typy sesji są określane w momencie wyewidencjonowania według przekazanych nagłówków:

Funkcja Checkin zwalnia sesję:

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

Funkcja Checkin wymaga nagłówka x-ms-sessionId (UUID w wersji 4) pasującego do sessionId ścieżki. To fire-and-forget: 204 No Content odpowiedź oznacza, że wydanie zostało zaakceptowane i oczyszczanie kończy się asynchronicznie. Bezczynne sesje są eksmitowane automatycznie po 30 minutach braku aktywności (każde żądanie udziału mcp lub ekranu jest liczone jako działanie), ale aplikacje partnerskie powinny zawsze jawnie sprawdzać sesje po zakończeniu pracy.

Computer-Do: operacja w sesji

Po uzyskaniu komputera w chmurze przez aplikację partnera agenci używają narzędzi MCP do jej obsługi. Te narzędzia są zgodne z otwartym protokołem kontekstowym modelu, dzięki czemu każdy agent obsługjący protokół może odnajdywać i wywoływać narzędzia bez integracji niestandardowej.

Cały ruch MCP przepływa przez punkt końcowy MCP sesji utworzony przez dołączenie /mcp do zwróconego computerUrl przy wyewidencjonowaniu:

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

Każde żądanie musi zawierać x-ms-computerId nagłówek zgodny z identyfikatorem komputera w adresie URL. Każdy post wysyła jeden komunikat JSON-RPC i zwraca jedną odpowiedź.

Cykl życia sesji MCP. Klient musi ukończyć uzgadnianie inicjowania mcp przed wywołaniem dowolnego narzędzia:

1. initialize Wyślij żądanie, aby odebrać możliwości serwera.
2. Wyślij powiadomienie (brak oczekiwanej initialized odpowiedzi).
3. Wystawianie wywołań tools/list narzędzi w celu odnalezienia dostępnych narzędzi lub tools/call wywołania ich.

Inicjowanie jest wymagane raz na sesję. Płaszczyzna MCP obejmuje interakcję pulpitu (mysz, klawiatura, przechwytywanie zrzutów ekranu), zarządzanie oknami, wykonywanie poleceń, automatyzację przeglądarki i funkcje ułatwień dostępu interfejsu użytkownika.

Aby zapoznać się z pełnym wykazem narzędzi i ich schematów parametrów, zobacz Windows 365 for Agents SERWER MCP.

Computer-See/Take-Control: nadzór człowieka

Zestaw Screenshare SDK umożliwia aplikacji partnerskiej osadzanie obserwacji aktywności agenta w czasie rzeczywistym przez człowieka bezpośrednio we własnym interfejsie użytkownika. Przesyła ona strumieniowo komputer z chmurą agenta za pośrednictwem usługi WebRTC, a w razie potrzeby przekazuje dane wejściowe myszy i klawiatury z powrotem do sesji. Zestaw SDK tworzy wewnątrz strony ramkę, która obsługuje wszystkie wywołania interfejsu API przesyłania strumieniowego wideo, przekazywania danych wejściowych i udostępniania ekranu, dzięki czemu aplikacja nigdy nie rozmawia bezpośrednio ze stosem przesyłania strumieniowego.

Przeglądarka nawiązuje połączenie z zwróconym screenshareUrl przy wyewidencjonowaniu. Nie jest wymagana konstrukcja oddzielnego punktu końcowego udziału ekranu, zestaw SDK wyprowadza swoje wywołania z podstawowego adresu URL (computerUrl) i identyfikatora komputera.

Przepływ integracji

Aplikacja partnera wyewidencjonuje sesję, ładuje zestaw SDK z sieci CDN i przekazuje zwrócony computerUrl token elementu nośnego do ScreenShareViewerelementu . Element iframe przejmuje stamtąd połączenie interfejsu API udostępniania ekranu ARI i dołączanie do wywołania wideo w Twoim imieniu:

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

Dystrybucja zestawu SDK

Załaduj kompilację screenshare-embed.js z sieci CDN:

Metody przeglądarki

Wystąpienie ScreenShareViewer uwidacznia pełny cykl życia sesji, łączenie, opcjonalne przekazywanie kontrolek, odświeżanie tokenu i łza:

Odpowiedzi na błędy

Błędy są przekazywane przez error zdarzenie przy użyciu kodu i komunikatu. Każdy kod jest mapowany na określoną akcję odzyskiwania:

Szybki start

Minimalna strona, która intensywuje przeglądarkę w kontenerze i łączy ją z już wyewidencjonowanym wyewidencjonowaniem sesji. Przyjęto założenie, że masz już odpowiedź dotyczącą wyewidencjonowania (zobacz Computer-Get) i token elementu nośnego (zobacz Uwierzytelnianie):

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

Podsumowanie powierzchni

Jak pasują do siebie

Powierzchnie działają w sekwencji, z wyraźnym przekazaniem między wywołującymi:

1. Administratorzy i twórcy agentów używają funkcji Computer-Create do aprowizacji puli.
2. Aplikacja partnera wywołuje polecenie Checkout on Computer-Get, aby zarezerwować komputer w chmurze dla określonego elementu pracy agenta, określając rodzaj sesji za pośrednictwem nagłówków żądań.
3. Agent sztucznej inteligencji inicjuje sesję {computerUrl}/mcp mcp i napędza komputer w chmurze za pośrednictwem narzędzi Computer-Do . Większość wywołań przepływa przez tę płaszczyznę.
4. W razie potrzeby aplikacja partnera wywołuje akcje Computer-See w {screenshareUrl} imieniu człowieka w celu obserwowania lub przejęcia.
5. Aplikacja partnera wywołuje funkcję Checkin na Computer-Get, aby zwolnić komputer w chmurze po zakończeniu pracy. Sesje pozostawione w stanie bezczynności przez 30 minut są eksmitowane automatycznie.

Następne kroki

• Dowiedz się więcej o Windows 365 for Agents serwera MCP.
• Dowiedz się więcej o architekturze Windows 365 for Agents.
• Dowiedz się więcej o cyklu życia sesji agenta.

Zawartość pokrewna

• Pule agentów komputerów w chmurze
• Model uwierzytelniania agenta
• Co to jest Windows 365 for Agents?