Общие сведения об API W365 для агентов

Windows 365 for Agents предоставляет возможности с помощью дополнительных поверхностей, которые сопоставляют с жизненным циклом сеанса агента:

• API Microsoft Graph для администрирования. ИТ-администраторы и создатели агентов используют эти API для подготовки и управления емкостью пула.
• Windows 365 for Agents API сеансов для управления сеансами среды выполнения. Партнерские приложения вызывают этот API, чтобы проверка облачный компьютер, а затем освободить его после завершения работы.
• Средства протокола контекста модели (MCP) для работы в сеансе. Агенты ИИ вызывают эти средства через конечную точку MCP для каждого сеанса. Для совместного использования экрана партнерское приложение вызывает действия с общим доступом к экрану от имени человека.

Вместе эти поверхности охватывают подготовку пула, приобретение облачного компьютера, выполнение работы, наблюдение или помощь по мере необходимости.

Полный список документации по API и руководство по началу работы см. в документации по Windows 365 for Agents GitHub.

Computer-Create: администрирование

На стороне Microsoft API Graph плоскость Computer-Create использует API Graph W365A и портал администрирования W365. Благодаря этим интерфейсам администраторы и независимые поставщики программного обеспечения могут:

• Подготовка пулов агентов облачных компьютеров.
• Настройка политик и образов.
• Регистрация вызывающих доверенных партнеров.
• Количество пулов масштабирования.
• Подключение контроля за счет выставления счетов MAC.

Дополнительные сведения о пулах агентов облачных компьютеров см. в документации по API Graph.

Computer-Get: получение сеанса и регистрация

Плоскость Computer-Get — это небольшая область управления средой выполнения для партнерских приложений, обслуживаемая API сеансов Windows 365 for Agents (а не Microsoft Graph).

Checkout резервирует облачный компьютер и возвращает удостоверение сеанса и URL-адреса подключений:

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

При успешном оформлении заказа возвращается:

• sessionId : идентификатор сеанса.
• status : результат подготовки (например, Succeeded).
• computerUrl : базовый URL-адрес для вызовов инструментов MCP (добавление /mcp)
• screenshareUrl : базовый URL-адрес для действий с общим доступом к экрану
• connectivityUrl : может быть null, не зависеть от него. Всегда используйте computerUrl для MCP и screenshareUrl для демонстрации экрана.

При назначении устройства может потребоваться до 30 секунд. x-ms-sessionId Используйте заголовок (UUID версии 4) в качестве ключа идемпотентности, чтобы повторные попытки не выделяли повторяющиеся сеансы.

Типы сеансов определяются во время оформления заказа по передаваемым заголовкам:

Проверка освобождает сеанс:

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

Для проверки требуется x-ms-sessionId заголовок (UUID версии 4), соответствующий sessionId в пути. Это горит и забывает: 204 No Content ответ означает, что выпуск был принят, а очистка завершается асинхронно. Неактивные сеансы автоматически удаляются после 30 минут бездействия (любой запрос MCP или экранного ресурса считается действием), но партнерские приложения всегда должны проверка сеансы в явном виде по завершении работы.

Computer-Do: операция в сеансе

После того как партнерское приложение получит облачный компьютер, агенты используют средства MCP для его работы. Эти средства следуют открытому протоколу контекста модели, поэтому любой агент, поддерживающий этот протокол, может обнаруживать и вызывать средства без пользовательской интеграции.

Весь трафик MCP проходит через конечную точку MCP сеанса, сформированную путем добавления /mcp к возвращенной computerUrl при оформлении заказа:

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

Каждый запрос должен содержать x-ms-computerId заголовок, соответствующий идентификатору компьютера в URL-адресе. Каждая функция POST отправляет одно сообщение JSON-RPC и возвращает один ответ.

Жизненный цикл сеанса MCP. Клиент должен завершить подтверждение инициализации MCP перед вызовом любого средства:

1. initialize Отправка запроса на получение возможностей сервера.
2. initialized Отправить уведомление (ответа не ожидается).
3. Вызовы tools/list инструментов для обнаружения доступных средств или tools/call для вызова одного из них.

Инициализация требуется один раз в сеансе. Плоскость MCP охватывает взаимодействие с рабочим столом (мышь, клавиатура, захват снимков экрана), управление окнами, выполнение команд, автоматизацию браузера и возможности специальных возможностей пользовательского интерфейса.

Полный каталог средств и их схемы параметров см. в разделе Windows 365 for Agents MCP Server.

Computer-See/Take-Control: контроль человека

Пакет SDK для Screenshare позволяет партнерскому приложению внедрять наблюдение за действиями агента в режиме реального времени непосредственно в собственный пользовательский интерфейс. Он выполняет потоковую передачу облачного компьютера агента по WebRTC и при необходимости ретранслирует ввод с помощью мыши и клавиатуры обратно в сеанс. Пакет SDK создает iframe внутри страницы, который обрабатывает все вызовы API потоковой передачи видео, ретранслятора ввода и общего доступа к экрану, чтобы приложение никогда не общалось со стеком потоковой передачи напрямую.

Средство просмотра подключается к возвращенной при оформлении screenshareUrl заказа. Создание отдельной конечной точки общего ресурса с экрана не требуется, пакет SDK наследует свои вызовы из базового URL-адреса (computerUrl) и идентификатора компьютера, который вы указали.

Поток интеграции

Партнерское приложение извлекает сеанс, загружает пакет SDK из CDN и передает возвращенный computerUrl маркер ScreenShareViewerносителя в . Iframe берет на себя оттуда, вызывая API ari screen share и присоединяясь к видеозвонку от вашего имени:

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:

Методы средства просмотра

Экземпляр ScreenShareViewer предоставляет полный жизненный цикл сеанса, подключение, необязательную передачу управления, обновление маркера и отключение:

Ответы с ошибками

Ошибки отображаются в событии error с кодом и сообщением. Каждый код сопоставляется с определенным действием восстановления:

Краткое руководство

Минимальная страница, которая подключает средство просмотра к контейнеру и подключает его к уже извлеченном сеансу. Предполагается, что у вас уже есть ответ на проверку (см. раздел 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

Как они подходят друг к другу

Поверхности работают последовательно, с четкой передачой между вызывающими:

1. Администраторы и создатели агентов используют Computer-Create для подготовки пула.
2. Партнерское приложение вызывает Запрос на Computer-Get, чтобы зарезервировать облачный компьютер для определенной части работы агента, указывая тип сеанса через заголовки запросов.
3. Агент ИИ инициализирует сеанс MCP для {computerUrl}/mcp и управляет облачным компьютером с помощью средств Computer-Do . Большинство вызовов проходят через эту плоскость.
4. При необходимости партнерское приложение вызывает действия {screenshareUrl}Computer-See от имени человека для наблюдения или принятия на себя.
5. Партнерское приложение вызывает Checkin на Computer-Get, чтобы освободить облачный компьютер после завершения работы. Сеансы, оставшиеся бездействуя в течение 30 минут, вытесаются автоматически.

Дальнейшие действия

• Дополнительные сведения о Windows 365 for Agents MCP Server.
• Сведения об архитектуре Windows 365 for Agents.
• Сведения о жизненном цикле сеанса агента.

Связанные материалы

• Пулы агентов облачных компьютеров
• Модель проверки подлинности агента
• Что такое Windows 365 for Agents?