Краткое руководство по API рабочего IQ (предварительная версия)

Важно!

Рабочий IQ доступен в общедоступной предварительной версии. Функции и API могут изменяться до общедоступной доступности и не имеют установленного SLA.

Рабочий IQ — это собственный интерфейс ИИ Корпорации Майкрософт для рабочей аналитики Microsoft 365. Она позволяет создавать приложения, которые могут запрашивать сообщения электронной почты, собрания, файлы и знания организации с помощью естественного языка; на основе данных Microsoft 365.

В этом кратком руководстве рассматривается протокол "агент — агент" (A2A). A2A является открытым стандартом для обмена данными с агентом и поддерживает синхронный режим в шлюзе Work IQ. Скоро появится поддержка режима потоковой передачи (события, отправленные сервером (SSE)).

Предварительные условия

Пользователь с лицензией Microsoft 365 Copilot
Пакет SDK для .NET версии 8 или более поздней для выполнения примера кода
Пользователь с правами администратора организации для одноразовой настройки рабочего IQ

Включение API рабочего IQ в организации

⏱️ ~5 минут, один раз на организацию.

В этом разделе создаются две вещи в вашей организации:

Субъект-служба Work IQ (подготавливает ресурс Work IQ, чтобы пользователи могли запрашивать для него маркеры)
Регистрация приложения, которую использует клиентский код для проверки подлинности WorkIQAgent.Ask с делегированным разрешением.

Для выполнения этого шага вы (или администратор вашей организации) можете использовать Центр администрирования Microsoft Entra или интерфейс командной строки Azure.

центр Администратор
Azure CLI

Этап 1. Создание субъекта-службы Work IQ (Обозреватель Graph)

Перейдите в graph Обозреватель и войдите с учетной записью администратора.
Задайте для метода значение POST, а URL-адрес — .https://graph.microsoft.com/v1.0/servicePrincipals Граф Обозреватель отображает соответствующие области на основе URL-адреса и метода, поэтому url-адрес необходимо ввести перед согласием на следующем шаге.
Выберите Изменить разрешения и согласие на Application.ReadWrite.All. Этот шаг является одноразовым действием администратора и предоставляет область только для собственного сеанса Graph Обозреватель. Это не изменяет разрешения для всей организации.
Введите следующую команду в тексте запроса.
```
{
  "appId": "fdcc1f02-fc51-4226-8753-f668596af7f7"
}
```
Выберите Выполнить запрос. Ответ 201 Created подтверждает успешное выполнение. Конфликтная ошибка означает, что субъект-служба уже существует. Перейти к следующему шагу можно.

Этап 2. Создание регистрации приложения

Перейдите к Центр администрирования Microsoft Entra. В области навигации слева выберите идентификатор Entra, а затем Регистрация приложений.
Выберите Новая регистрация.
Добавьте описательное имя и задайте для параметра Поддерживаемые типы учетных записей значение Учетные записи только в этом каталоге организации. Нажмите Зарегистрировать.
Скопируйте идентификатор приложения (клиента). Это значение — .APP_ID
Выберите Проверка подлинности. Выберите Добавить платформу (или Добавить URI перенаправления). В диалоговом окне выберите Мобильные и классические приложения.
- Выберите рекомендуемый универсальный код ресурса (URI): https://login.microsoftonline.com/common/oauth2/nativeclient.
- В разделе Пользовательские URI перенаправления добавьте следующие два URI по одному (каждый в своей строке):
  - http://localhost
  - ms-appx-web://microsoft.aad.brokerplugin/<APP_ID> (где <APP_ID> — ваш APP_ID)
- В разделе Дополнительные параметры установите для параметра Разрешить общедоступные клиентские потокизначение Да.
- Выберите Сохранить.
Выберите Разрешения API, Добавить разрешение, а затем API, которые используются в моей организации. Work IQНайдите , а затем выберите Делегированные разрешения. Выберите WorkIQAgent.Ask , а затем выберите Добавить разрешения.
Выберите Предоставить согласие администратора для [вашего клиента]. Просмотрите диалоговое окно подтверждения и выберите Да.
Скопируйте идентификатор каталога (клиента) на странице обзора Microsoft Entra ID.

Разрешение WorkIQAgent.Ask позволяет приложению от имени вошедшего пользователя запрашивать рабочую аналитику Microsoft 365 (почта, файлы, собрания, чаты) через Work IQ.

Создайте субъект-службу Work IQ в организации.
```
az ad sp create --id fdcc1f02-fc51-4226-8753-f668596af7f7
```

Создайте регистрацию приложения.

APP_ID=$(az ad app create \
  --display-name "Work IQ Samples Client" \
  --sign-in-audience AzureADMyOrg \
  --is-fallback-public-client true \
  --query appId -o tsv)
echo "APP_ID: $APP_ID"

Создайте субъект-службу для приложения.
```
az ad sp create --id $APP_ID
```
Настройте три URI перенаправления общедоступного клиента.
- http://localhost : интерактивный резервный браузер
- login.microsoftonline.com/common/oauth2/nativeclient : устаревшая версия MSAL native
- ms-appx-web://microsoft.aad.brokerplugin/<APP_ID> : брокер WAM в Windows
```
az ad app update --id $APP_ID \
  --public-client-redirect-uris \
    "http://localhost" \
    "https://login.microsoftonline.com/common/oauth2/nativeclient" \
    "ms-appx-web://microsoft.aad.brokerplugin/$APP_ID"
```
Добавьте делегированное разрешение WorkIQAgent.Ask и предоставьте согласие.

Примечание.

dcc1f02-fc51-4226-8753-f668596af7f7— идентификатор приложения Work IQ и 0b1715fd-f4bf-4c63-b16d-5be31f9847c2 идентификатор область для WorkIQAgent.Ask.
```
az ad app permission add --id $APP_ID \
  --api fdcc1f02-fc51-4226-8753-f668596af7f7 \
  --api-permissions "0b1715fd-f4bf-4c63-b16d-5be31f9847c2=Scope"
az ad app permission admin-consent --id $APP_ID
```
Получите идентификатор клиента.
```
az account show --query tenantId -o tsv
```

Теперь у вас должно быть два значения: APP_ID и TENANT_ID. Передайте эти значения в пример с помощью --appid и --tenant.

Совет

Создание агента на стороне сервера (веб-приложения)? В этом кратком руководстве используется регистрация общедоступного клиента (мобильный или настольный компьютер) для простейших путей к рабочему примеру. Если ваше приложение является серверной службой, которая вызывает Work IQ от имени конечного пользователя (например, веб-агент, который входит в систему пользователя, а затем пересылает его удостоверение в Work IQ), используйте конфиденциальную регистрацию клиента с секретом клиента или сертификатом и обменяйте маркер пользователя через поток On-Behalf-Of (OBO). Область API Work IQ и делегированное разрешение WorkIQAgent.Ask одинаковы в обоих потоках.

Краткое руководство. Протокол A2A

Протокол "агент — агент" (A2A) — это открытый стандарт для обмена данными между агентами. Рабочий IQ поддерживает как A2A версии 1.0 (это краткое руководство), так и версии 0.3. Заголовок A2A-Version запроса управляет отправкой версии.

A2A-Version: 1.0 — формат провода версии 1.0 (это краткое руководство)
A2A-Version: 0.3 (или заголовок опущен) — формат провода версии 0.3 (по умолчанию без заголовка для обратной совместимости с существующими клиентами версии 0.3)

Получение примера кода

Клонируйте пример репозитория с помощью следующей команды.

git clone https://github.com/microsoft/work-iq-samples.git
cd work-iq-samples

Запустите пример (с помощью пакета SDK для A2A)

В dotnet/a2a примере используется пакет SDK для A2A .NET.

cd dotnet/a2a
dotnet run -- --token WAM --appid <APP_ID> --tenant <TENANT_ID>

Запустите пример (необработанный HTTP, без пакета SDK)

В dotnet/a2a-raw примере показан протокол провода без абстракции пакета SDK. Этот пример полезен для переноса на non-.NET языки.

cd dotnet/a2a-raw
dotnet run -- --token WAM --appid <APP_ID> --tenant <TENANT_ID>

Что происходит

При запуске примера появляется запрос на вход (диалоговое окно WAM в Windows, системный браузер в macOS или Linux). После входа введите сообщение в командной строке You > и нажмите клавишу ВВОД. Ниже отобразится ответ агента. Введите quit для выхода.

── READY — Work IQ Gateway — Sync — https://workiq.svc.cloud.microsoft/a2a/ ──
Type a message. 'quit' to exit.

You > Summarize my recent emails from Alice.
Agent > You've exchanged 8 emails with Alice this week. Key threads:
  - ...
  (2145 ms)

You > quit

Принципы действия

Рабочий IQ принимает A2A версии 1.0 через JSON-RPC в https://workiq.svc.cloud.microsoft/a2a/. (A2A версии 1.0 также определяет привязку REST в /v1/message:send; Рабочий IQ может предоставить эту привязку REST в будущем предварительном обновлении.)

Рабочий шлюз IQ

Конечной точки: https://workiq.svc.cloud.microsoft/a2a/
Аудитория токенов: api://workiq.svc.cloud.microsoft
Область: WorkIQAgent.Ask

Синхронный `SendMessage`

POST https://workiq.svc.cloud.microsoft/a2a/
Authorization: Bearer <token>
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": "<request-guid>",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "<message-guid>",
      "parts": [
        {
          "text": "What meetings do I have today?"
        }
      ],
      "metadata": {
        "Location": {
          "timeZoneOffset": -480,
          "timeZone": "America/Los_Angeles"
        }
      }
    }
  }
}

Заголовок A2A-Version: 1.0 запроса включает имена методов версии 1.0 (SendMessage) в шлюзе. Без него сервер по умолчанию использует версию 0.3 и возвращает JSON-RPC -32601 "Method not found" для имен методов версии 1.0.

Ответ представляет собой конверт JSON-RPC с result.task задачей агента и contextId для многоэтапного:

{
  "jsonrpc": "2.0",
  "id": "<request-guid>",
  "result": {
    "task": {
      "id": "<task-id>",
      "contextId": "ctx-1",
      "status": {
        "state": "TASK_STATE_COMPLETED"
      },
      "artifacts": [
        {
          "artifactId": "<artifact-id>",
          "name": "Answer",
          "parts": [
            {
              "text": "Today you have: 9 AM standup, 11 AM review with Dana, 2 PM customer call."
            }
          ]
        }
      ]
    }
  }
}

Рабочий IQ требует Location метаданных для наземных запросов с учетом времени ("сегодня" или "на этой неделе") в местное время пользователя.

Многоэтапные беседы

Чтобы сохранить состояние беседы, передайте contextId из предыдущего ответа в следующем сообщении.

{
  "jsonrpc": "2.0",
  "id": "<request-guid-2>",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "<message-guid-2>",
      "contextId": "ctx-1",
      "parts": [
        {
          "text": "Tell me more about the 2 PM customer call."
        }
      ]
    }
  }
}

Сведения о протоколе ключа (A2A версии 1.0)

Требуется конверт JSON-RPC: каждый запрос должен включать jsonrpc, id, method, , params.
POST в базовый URL-адрес: метод (SendMessage) находится в тексте JSON-RPC, а не в URL-пути.
Части присутствия по полю: части представляют собой плоские объекты с одним из text, urlraw, или data набором; не kind дискриминируют.
SCREAMING_SNAKE_CASE перечисления: роли используют ROLE_USER / ROLE_AGENT; состояния используют / TASK_STATE_WORKING / TASK_STATE_COMPLETEDTASK_STATE_FAILED / и т. д.
Оболочка результатов: ответы задачи отображаются в разделе result.task.
Отправка версии:A2A-Version: 1.0 выбирает версию 1.0; Опуская заголовок (или отправляя A2A-Version: 0.3), выбирается версия 0.3, значение по умолчанию без заголовка.

Обнаружение агента

Чтобы вызвать определенный агент, передайте его идентификатор агента через --agent-id. Существует два способа найти идентификатор агента.

Рекомендуется: WorkIQ CLI `list-agents` (экспериментальный)

WorkIQ CLI предоставляет экспериментальную list-agents команду, которая выводит агенты, доступные для вошедшего пользователя.

workiq config set experimental=true
workiq list-agents

В каждой строке отображается отображаемое имя агента, поставщик и идентификатор агента (вторая строка каждой записи). Используйте этот идентификатор с --agent-id при запуске примера.

Альтернатива: копирование из URL-адреса Microsoft 365 Copilot

Перейдите на веб-сайт Microsoft 365 Copilot Chat: https://m365.cloud.microsoft/chat/.
Выберите агент в области навигации слева.
Идентификатор агента находится в адресной строке браузера после /chat/agent/:

https://m365.cloud.microsoft/chat/agent/P_c0fd1ab0-cbf3-7eb9-1a7d-2d823549ef31.8ad61c39-5b6e-447c-b26a-a64eee436502
                                       └──────────────────────────── agent ID ─────────────────────────────────────┘

Представлено в формате <LETTER>_<opaqueValue1>.<opaqueValue2>.

Передача идентификатора агента в пример

Важно!

Весь идентификатор агента обрабатывается как непрозрачная строка. Не деконструируйте и не анализируйте его компоненты. Передайте его в API как есть.

Передача идентификатора агента в качестве аргумента в пример

dotnet run -- --token WAM --agent-id <AGENT_ID> --appid <APP_ID> --tenant <TENANT_ID>

Примечание.

Некоторые агенты Microsoft 365 (в частности, Word, Excel и PowerPoint в пользовательском интерфейсе Copilot Chat) предназначены для запуска в контексте этих продуктов Office и не создают полезные ответы при вызове без головы через A2A.

возможности A2A

Возможность	Состояние
`SendMessage` (синхронизация)	✅ Доступны
Многоэтапный (`contextId`)	✅ Доступны
Текстовые части	✅ Доступны
Цитаты	✅ Доступно (форма доставки модернизируется; см. заметки о выпуске)

Проверка подлинности

Метод	Платформа	Применение
WAM (диспетчер учетных записей Windows)	Windows	`--token WAM --appid <APP_ID> --tenant <TENANT_ID>`
Интерактивный браузер	macOS, Linux	Та же команда— Клиент удостоверений Майкрософт возвращается к системному входу в браузер.
Предварительно полученный JWT	Любой	`--token <JWT>`(маркер должен быть выдан для зарегистрированного приложения, а не для произвольного клиента, например для Azure CLI)

Устранение неполадок

Признак	Исправление
`401 Unauthorized`	Маркер `aud` не соответствует `api://workiq.svc.cloud.microsoft`. Проверьте утверждение аудитории.
`403 Forbidden`(ошибка область отсутствует)	У пользователя отсутствует лицензия Microsoft 365 Copilot. Назначьте и подождите 15–30 минут.
`403 Forbidden` с `Required scopes = [...]`	Администратор согласие для `WorkIQAgent.Ask` не было предоставлено. Повторно запустите согласие администратора (настройка администратора, шаг 6 или Azure cli, шаг 3).
WAM `IncorrectConfiguration` (3399614466)	Для регистрации приложения отсутствует универсальный код ресурса (URI) перенаправления брокера. Прочитано `ms-appx-web://microsoft.aad.brokerplugin/<APP_ID>` и повторите попытку.
WAM по-прежнему завершается ошибкой после установки URI перенаправления	Несоответствие однотенантного приложения и `/common` центра. Передайте `--tenant <TENANT_ID>` таким образом, чтобы клиент Microsoft Identity использовал центр, зависящий от клиента.
`AADSTS65001: consent required`	Администратор согласие не предоставлено. Запустите `az ad app permission admin-consent --id <APP_ID>`.
Пустое 200 / без текста агента	Если пользователю недавно была назначена лицензия Copilot, сборка индекса может занять 15–30 минут. Если вы вызвали агент Word,Excel/PowerPoint, эти агенты запускаются в продукте Office и не создают ответы без головы A2A.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-05-01