Work IQ API クイックスタート (プレビュー)

重要

Work IQ は パブリックプレビュー段階です。機能と API は、一般提供前に変更される可能性があり、SLA が設定されていません。

Work IQ は、Microsoft 365 仕事インテリジェンスに対する Microsoft の AI ネイティブインターフェイスです。これにより、自然言語を使用して電子メール、会議、ファイル、組織の知識を照会できるアプリケーションを構築できます。は、Microsoft 365 データに固定されます。

このクイックスタートでは、エージェント間 (A2A) プロトコルについて説明します。 A2Aはエージェント通信のオープン標準であり、Work IQ Gateway に対する同期モードをサポートします。ストリーミングモード (サーバー送信イベント (SSE)) のサポートは近日公開予定です。

前提条件

Microsoft 365 Copilot ライセンスを持つユーザー
サンプルコードを実行するための .NET SDK バージョン 8 以降
1 回限りの Work IQ セットアップorganization管理者アクセス権を持つユーザー

organizationで Work IQ API を有効にする

⏱️ 5 分、organizationあたり 1 回。

このセクションでは、organizationに次の 2 つのことを作成します。

Work IQ サービスプリンシパル (ユーザーがトークンを要求できるように Work IQ リソースをプロビジョニングします)
WorkIQAgent.Ask委任されたアクセス許可を使用して、クライアントコードが認証に使用するアプリ登録

ユーザー (またはorganization管理者) は、Microsoft Entra 管理センターまたはAzure CLI を使用してこの手順を完了できます。

管理センター
Azure CLI

手順 1. Work IQ サービスプリンシパルを作成する (Graph エクスプローラー)

[Graph エクスプローラー] に移動し、管理者アカウントでサインインします。
メソッドを POST に設定し、URL を https://graph.microsoft.com/v1.0/servicePrincipals に設定します。グラフエクスプローラーは、URL とメソッドに基づいて関連するスコープを表示するため、次の手順で同意する前に URL を入力する必要があります。
[ アクセス許可の変更 ] を選択し、 Application.ReadWrite.Allに同意します。この手順は 1 回限りの管理者アクションであり、独自の Graph エクスプローラーセッションに対してのみスコープを付与します。 organization全体のアクセス許可は変更されません。

要求本文に次のように入力します。

{
  "appId": "fdcc1f02-fc51-4226-8753-f668596af7f7"
}

[クエリの実行] を選択します。 201 作成された応答は成功を確認します。競合エラーは、サービスプリンシパルが既に存在することを意味します。次の手順に進んでも問題ありません。

手順 2. アプリの登録を作成する

Microsoft Entra 管理センターに移動します。左側のナビゲーションウィンドウで、[ENTRA ID] を選択し、アプリの登録します。
[新規登録] を選択します。
わかりやすい名前を追加し、[ サポートされているアカウントの種類 ] を [この組織のディレクトリ内のアカウントのみ] に設定します。 [登録] を選択します。
アプリケーション (クライアント) ID をコピーします。この値は、 APP_IDです。
[ 認証] を選択します。 [ プラットフォームの追加] (または [リダイレクト URI の追加]) を選択します。ダイアログで、[ モバイルアプリケーションとデスクトップアプリケーション] を選択します。
- 推奨される URI を選択します: https://login.microsoftonline.com/common/oauth2/nativeclient。
- [ カスタムリダイレクト URI] で、次の 2 つの URI を 一度に 1 つずつ 追加します (それぞれ独自の行)。
  - http://localhost
  - ms-appx-web://microsoft.aad.brokerplugin/<APP_ID> (ここで、 <APP_ID> はあなたの APP_IDです)
- [ 詳細設定] で、[ パブリッククライアントフローを許可する] を [はい] に設定します。
- [保存] を選択します。
[API のアクセス許可]、[アクセス許可の追加] の順に選択し、organizationで使用する API を選択します。 Work IQを検索し、[委任されたアクセス許可] を選択します。 [ WorkIQAgent.Ask ] を選択し、[ アクセス許可の追加] を選択します。
[ テナント] の [管理者の同意の付与] を選択します。確認ダイアログを確認し、[ はい] を選択します。
[Microsoft Entra IDの概要] ページからディレクトリ (テナント) ID をコピーします。

WorkIQAgent.Ask アクセス許可を使用すると、サインインしているユーザーに代わって、アプリが Work IQ を介して Microsoft 365 仕事インテリジェンス (メール、ファイル、会議、チャット) に対してクエリを実行できます。

organizationで 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
```
3 つのパブリッククライアントリダイレクト URI を構成します。
- http://localhost : 対話型ブラウザーフォールバック
- login.microsoftonline.com/common/oauth2/nativeclient : レガシ MSAL ネイティブ
- ms-appx-web://microsoft.aad.brokerplugin/<APP_ID> : Windows 上の WAM ブローカー
```
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 アプリケーション ID、 0b1715fd-f4bf-4c63-b16d-5be31f9847c2 は WorkIQAgent.Ask のスコープ ID です。
```
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
```

テナント ID を取得します。

az account show --query tenantId -o tsv

これで、 APP_ID と TENANT_IDの 2 つの値が作成されます。 --appidと--tenantを使用して、これらの値をサンプルに渡します。

ヒント

サーバー側エージェント (Web アプリ) を構築しますか? このクイックスタートでは、作業サンプルへの最も簡単なパスとして 、パブリッククライアント 登録 (モバイル/デスクトップ) を使用します。アプリケーションが、エンドユーザーの代わりに Work IQ を呼び出すサーバー側サービス (たとえば、ユーザーにサインインし、その ID を Work IQ に転送する Web エージェント) である場合は、クライアントシークレットまたは証明書で 機密クライアント 登録を使用し、 On-Behalf-Of (OBO) フローを介してユーザーのトークンを交換します。 Work IQ API サーフェスと WorkIQAgent.Ask 委任されたアクセス許可は、両方のフローで同じです。

クイックスタート: A2A プロトコル

エージェント間 (A2A) プロトコルは、エージェント通信のオープン標準です。 Work IQ では、A2A v1.0 (このクイックスタート) と v0.3 の両方がサポートされています。 A2A-Version要求ヘッダーは、バージョンディスパッチを制御します。

A2A-Version: 1.0 - v1.0 ワイヤ形式 (このクイックスタート)
A2A-Version: 0.3 (またはヘッダーを省略) - v0.3 ワイヤ形式 (既存の v0.3 クライアントとの下位互換性のためにヘッダーなし既定値として保持)

サンプルコードを取得する

次のコマンドを使用して、サンプルリポジトリを複製します。

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

サンプルを実行する (A2A SDK を使用)

dotnet/a2a サンプルでは、A2A .NET SDK を使用します。

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>

動作

サンプルを実行すると、サインインプロンプトが表示されます (Windows では WAM ダイアログ、macOS/Linux ではシステムブラウザー)。サインイン後、 You > プロンプトでメッセージを入力し、Enter キーを押 します。エージェントの応答が以下に表示されます。「 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

メカニズム

Work IQ は、https://workiq.svc.cloud.microsoft/a2a/で JSON-RPC 経由で v1.0 A2A受け入れます。 (A2A v1.0 では、/v1/message:sendでの REST バインドも定義されます。Work IQ では、将来のプレビュー更新プログラムでこの REST バインドが公開される可能性があります)。

Work IQ Gateway

エンドポイント： 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要求ヘッダーは、ゲートウェイで v1.0 メソッド名 (SendMessage) を有効にします。これを指定しないと、サーバーの既定値は v0.3 になり、v1.0 メソッド名の JSON-RPC -32601 "Method not found" が返されます。

応答は、エージェントのタスクとマルチターンのcontextIdを含むresult.taskを含む JSON-RPC エンベロープです。

{
  "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."
            }
          ]
        }
      ]
    }
  }
}

Work 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 v1.0)

JSON-RPC エンベロープが必要: すべての要求に、 jsonrpc、 id、 method、 paramsが含まれている必要があります。
ベース URL への POST: メソッド (SendMessage) は、URL パスではなく JSON-RPC 本文内にあります。
フィールドプレゼンスパーツ: パーツはフラットオブジェクトであり、 text、 url、 raw、または data セットのいずれかであり、 kind 識別子はありません。
SCREAMING_SNAKE_CASE列挙型: ロールは ROLE_USER / ROLE_AGENTを使用し、状態は TASK_STATE_WORKING / TASK_STATE_COMPLETED / TASK_STATE_FAILED /などを使用します。
結果ラッパー: タスクの応答が result.taskの下に表示されます。
バージョンディスパッチ:A2A-Version: 1.0 v1.0 を選択します。ヘッダーを省略 (または A2A-Version: 0.3を送信) すると、v0.3 が選択され、ヘッダーなしが既定値になります。

エージェントの検出

特定のエージェントを呼び出すには、--agent-idを介してそのエージェント ID を渡します。エージェントの ID を見つけるには、2 つの方法があります。

推奨: WorkIQ CLI `list-agents` (試験段階)

WorkIQ CLI には、サインインしているユーザーが使用できるエージェントを出力する実験的なlist-agents コマンドが付属しています。

workiq config set experimental=true
workiq list-agents

各行には、エージェントの表示名、プロバイダー、エージェント ID (各エントリの 2 行目) が表示されます。サンプルを実行するときは、 --agent-id でその ID を使用します。

別の方法: Microsoft 365 Copilot URL からコピーする

Microsoft 365 Copilot Chat Web サイト:https://m365.cloud.microsoft/chat/に移動します。
左側のナビゲーションでエージェントを選択します。
エージェント ID は、 /chat/agent/した後にブラウザーアドレスバーにあります。

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

形式は <LETTER>_<opaqueValue1>.<opaqueValue2> です。

エージェント ID をサンプルに渡す

重要

エージェント ID 全体を不透明な文字列として扱います。コンポーネントを分解または解析しないでください。そのまま API に渡します。

エージェント ID を引数としてサンプルに渡す

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

注:

一部の Microsoft 365 エージェント (特に、Word、Excel、および PowerPoint エージェントは、Copilot Chat UI 内のエージェント) は、Office 製品のコンテキストで実行するように設計されており、A2Aを介してヘッドレスで呼び出されたときに便利な応答を生成しません。

A2A機能

機能	状態
`SendMessage` (同期)	✅ 利用可能
マルチターン (`contextId`)	✅ 利用可能
テキストパーツ	✅ 利用可能
引用	✅ 使用可能 (配信図形は最新化中です。リリースノートを参照)

認証

メソッド	プラットフォーム	使用方法
WAM (Windows アカウントマネージャー)	Windows	`--token WAM --appid <APP_ID> --tenant <TENANT_ID>`
対話型ブラウザー	macOS、Linux	同じコマンド — Microsoft Identity Client は、システムブラウザーのサインインにフォールバックします。
事前に取得された 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>`を読み取り、もう一度やり直してください。
リダイレクト URI が設定された後も WAM が失敗する	シングルテナントアプリ + `/common` 権限の不一致。 Microsoft Identity Client がテナント固有の機関を使用するように、 `--tenant <TENANT_ID>` を渡します。
`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-02