에이전트용 W365 API 개요

Windows 365 for Agents 에이전트 세션 수명 주기에 매핑되는 보완적인 표면을 통해 기능을 노출합니다.

• 관리용 Microsoft Graph API. IT 관리자 및 에이전트 제조업체는 이러한 API를 사용하여 풀 용량을 프로비전하고 제어합니다.
• 런타임 세션 관리를 위한 세션 API를 Windows 365 for Agents. 파트너 애플리케이션은 이 API를 호출하여 클라우드 PC를 검사 다음, 작업이 완료되면 릴리스합니다.
• 세션 내 작업을 위한 MCP(모델 컨텍스트 프로토콜) 도구입니다. AI 에이전트는 세션별 MCP 엔드포인트를 통해 이러한 도구를 호출합니다. 화면 공유의 경우 파트너 애플리케이션은 사용자를 대신하여 화면 공유 작업을 호출합니다.

이러한 표면은 풀 프로비전, 클라우드 PC 획득, 작업 수행, 필요에 따라 관찰 또는 지원을 다룹니다.

API 설명서의 전체 목록 및 시작 가이드는 Windows 365 for Agents Github 설명서를 참조하세요.

Computer-Create: 관리

Microsoft Graph API 쪽에서 Computer-Create 평면은 W365A Graph API 및 W365 관리 포털을 사용합니다. 이러한 표면을 통해 관리자 및 ISV(독립 소프트웨어 공급업체)는 다음을 수행할 수 있습니다.

• 클라우드 PC 에이전트 풀을 프로비전합니다.
• 정책 및 이미지를 구성합니다.
• 신뢰할 수 있는 파트너 호출자를 등록합니다.
• 풀 수를 조정합니다.
• MAC 청구를 통해 계량을 연결합니다.

클라우드 PC 에이전트 풀에 대한 자세한 내용은 Graph API 설명서를 참조하세요.

Computer-Get: 세션 체크 아웃 및 체크 인

Computer-Get 평면은 microsoft Graph가 아닌 Windows 365 for Agents 세션 API에서 제공하는 파트너 애플리케이션에 대한 작은 런타임 제어 표면입니다.

체크 아웃 은 클라우드 PC를 예약하고 세션 ID 및 연결 URL을 반환합니다.

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

성공적인 체크 아웃은 다음을 반환합니다.

• sessionId : 세션 식별자
• status : 프로비전 결과(예: Succeeded)
• computerUrl : MCP 도구 호출에 대한 기본 URL(추가 /mcp)
• screenshareUrl : 화면 공유 작업에 대한 기본 URL
• connectivityUrl : 일 null수 있습니다. 에 의존하지 마세요. 항상 MCP 및 screenshareUrl 화면 공유에 사용합니다computerUrl.

디바이스가 할당되는 동안 체크 아웃에는 최대 30초가 걸릴 수 있습니다. 재시도에서 x-ms-sessionId 중복 세션을 할당하지 않도록 헤더(UUID v4)를 멱등성 키로 사용합니다.

세션 종류는 체크 아웃 시 전달한 헤더에 의해 결정됩니다.

종류	머리글	용도
HumanUser (기본값)	user-object-id	AAD ID에 바인딩된 대화형 세션을 Standard.
에이전트	x-ms-authorization-auxiliary (에이전트 ID 토큰) + user-object-id (에이전트 사용자 ID)	에이전트 기반 세션. 보조 토큰은 테넌트에서 프로비전된 ID RM 서비스에서 발급한 에이전트 ID 토큰이며 액세스를 요청하는 특정 에이전트(예: "Sales Agent")를 식별합니다.

체크 인은 세션을 해제합니다.

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

체크 인하려면 경로의 x-ms-sessionId 와 일치하는 헤더(UUID v4)가 sessionId 필요합니다. Fire-and-forget: 응답은 204 No Content 릴리스가 수락되고 정리가 비동기적으로 완료되었음을 의미합니다. 유휴 세션은 비활성 상태인 30분 후에 자동으로 제거되지만(MCP 또는 화면 공유 요청은 활동으로 계산됨) 파트너 애플리케이션은 작업이 완료되면 항상 명시적으로 세션을 검사 합니다.

Computer-Do: 세션 내 작업

파트너 애플리케이션이 클라우드 PC를 획득한 후 에이전트는 MCP 도구를 사용하여 운영합니다. 이러한 도구는 개방형 모델 컨텍스트 프로토콜을 따르므로 프로토콜을 지원하는 모든 에이전트는 사용자 지정 통합 없이 도구를 검색하고 호출할 수 있습니다.

모든 MCP 트래픽은 체크 아웃 시 반환된 에 를 추가하여 형성된 세션의 MCP 엔드포인트를 /mcpcomputerUrl 통해 흐릅니다.

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

모든 요청에는 URL에 x-ms-computerId 컴퓨터 ID와 일치하는 헤더가 포함되어야 합니다. 각 POST는 하나의 JSON-RPC 메시지를 보내고 하나의 응답을 반환합니다.

MCP 세션 수명 주기. 클라이언트는 도구를 호출하기 전에 MCP 초기화 핸드셰이크를 완료해야 합니다.

1. initialize 서버 기능을 수신하도록 요청을 보냅니다.
2. 알림을 보냅니다 initialized (응답이 필요하지 않음).
3. 도구 호출을 실행 tools/list 하여 사용 가능한 도구를 검색하거나 tools/call 호출합니다.

초기화는 세션당 한 번 필요합니다. MCP 평면은 데스크톱 상호 작용(마우스, 키보드, 스크린샷 캡처), 창 관리, 명령 실행, 브라우저 자동화 및 UI 접근성 기능을 다룹니다.

도구 및 해당 매개 변수 스키마의 전체 카탈로그는 WINDOWS 365 FOR AGENTS MCP Server를 참조하세요.

Computer-See/Take-Control: 사람 감독

Screenshare SDK를 사용하면 파트너 애플리케이션이 에이전트 활동에 대한 실시간 사용자 관찰을 자체 UI에 직접 포함할 수 있습니다. WebRTC를 통해 에이전트의 클라우드 PC를 스트리밍하고 필요한 경우 마우스 및 키보드 입력을 세션으로 다시 릴레이합니다. SDK는 모든 비디오 스트리밍, 입력 릴레이 및 화면 공유 API 호출을 처리하는 iframe을 페이지 내에 만들어 애플리케이션이 스트리밍 스택과 직접 대화하지 않도록 합니다.

뷰어는 체크 아웃 시 반환된 에 screenshareUrl 연결합니다. 별도의 화면 공유 엔드포인트 생성이 필요하지 않으며, SDK는 사용자가 제공하는 기본 URL(computerUrl) 및 컴퓨터 ID에서 호출을 파생합니다.

통합 흐름

파트너 애플리케이션은 세션을 체크 아웃하고 CDN에서 SDK를 로드한 다음 반환 computerUrl 된 및 전달자 토큰을 에 ScreenShareViewer전달합니다. iframe은 여기에서 인수되어 ARI 화면 공유 API를 호출하고 사용자를 대신하여 비디오 통화에 참여합니다.

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

SDK 배포

screenshare-embed.js CDN에서 빌드를 로드합니다.

CDN URL
https://packages.global.cloudinferenceplatform.azure.com/screenshare-sdk/latest/screenshare-embed.js

뷰어 메서드

ScreenShareViewer instance 전체 세션 수명 주기, 연결, 선택적 제어 핸드오프, 토큰 새로 고침 및 중단을 노출합니다.

방법	설명
connect(bearerToken)	화면 공유 세션을 시작합니다. Promise를 반환합니다.
takeControl()	마우스 및 키보드 컨트롤을 요청합니다(대화형 모드에만 해당). 가장 최근의 호출자는 항상 승리하고 거부는 없습니다.
releaseControl()	컨트롤을 해제하고 뷰어를 보기 전용으로 반환합니다.
updateToken(bearerToken)	세션을 다시 시작하지 않고 전달자 토큰을 바꿉니다. 오류가 표시되면 를 TOKEN_EXPIRED 사용합니다.
stop()	세션을 종료하고 DOM에서 iframe을 제거합니다. instance 다시 사용할 수 없습니다. 다시 연결할 새 ScreenShareViewer 를 만듭니다.

오류 응답

오류는 error 코드 및 메시지와 함께 이벤트를 통해 표시됩니다. 각 코드는 특정 복구 작업에 매핑합니다.

코드	의미	작업
TOKEN_EXPIRED	전달자 토큰이 만료되었습니다(401).	를 호출합니다 viewer.updateToken(newToken).
START_FAILED	ARI 시작 API가 실패했습니다.	확인 computerId 및 풀 등록.
JOIN_FAILED	ACS 호출 조인이 실패했습니다.	새 토큰을 사용하여 다시 시도합니다.
RECONNECT_FAILED	자동 다시 연결이 모두 사용되었습니다(3회 시도).	를 호출 viewer.stop()하여 새 뷰어를 만들고 새 토큰으로 다시 연결합니다.
IFRAME_LOAD_FAILED	Iframe은 10초 이내에 응답하지 않았습니다.	브라우저에서 연결할 수 있는지 baseUrl 확인합니다.
MODE_RESTRICTED	모드에서 실행된 제어 명령입니다 viewOnly .	를 사용하여 뷰어를 만듭니다 mode: 'interactive'.

빠른 시작

뷰어를 컨테이너에 탑재하고 이미 체크 아웃된 세션에 연결하는 최소 페이지입니다. 이미 체크 아웃 응답(Computer-Get 참조)과 전달자 토큰이 있다고 가정합니다(인증 참조).

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

Surface 요약

Surface	비행기	끝점	호출자	용도
그래프 API	Computer-Create	W365A Graph API 및 W365 관리 포털	IT 관리자 또는 ISV	풀을 셰이프하고 유지 관리합니다.
세션 API	Computer-Get	POST /api/pools/{poolId}/sessions (체크 아웃)	파트너 애플리케이션	클라우드 PC를 예약합니다.
세션 API	Computer-Get	DELETE /api/sessions/{sessionId} (체크 인)	파트너 애플리케이션	클라우드 PC를 릴리스합니다.
Mcp	Computer-Do	POST {computerUrl}/mcp	AI 에이전트	클라우드 PC를 운영합니다.
화면 공유 SDK	Computer-See, Computer-TakeControl	ScreenShareViewer (CDN screenshare-embed.js에서)	인간을 대신하여 파트너 앱	관찰하고 공동 구동합니다.

함께 맞추는 방법

표면은 호출자 간에 명확한 핸드오프와 함께 순서대로 작동합니다.

1. 관리자 및 에이전트 작성자는 Computer-Create를 사용하여 풀을 프로비전합니다.
2. 파트너 애플리케이션은 Computer-Get Checkout 을 호출하여 특정 에이전트 작업에 클라우드 PC를 예약하고 요청 헤더를 통해 세션 종류를 지정합니다.
3. AI 에이전트는 MCP 세션을 {computerUrl}/mcp 초기화하고 Computer-Do 도구를 통해 클라우드 PC를 구동합니다. 대부분의 호출은 이 평면을 통해 흐릅니다.
4. 필요한 경우 파트너 애플리케이션은 관찰하거나 인수하기 위해 인간을 대신하여 Computer-See 작업을 {screenshareUrl} 호출합니다.
5. 파트너 애플리케이션은 Computer-Get Checkin 을 호출하여 작업이 완료되면 클라우드 PC를 해제합니다. 30분 동안 유휴 상태로 남아 있는 세션은 자동으로 제거됩니다.

다음 단계

• WINDOWS 365 FOR AGENTS MCP Server에 대해 자세히 알아보세요.
• Windows 365 for Agents 아키텍처에 대해 알아봅니다.
• 에이전트 세션 수명 주기에 대해 알아봅니다.

관련 콘텐츠

• 클라우드 PC 에이전트 풀
• 에이전트 인증 모델
• Windows 365 for Agents 무엇인가요?