前提条件
- テナントで Work IQ を有効にする
- サンプル コードを実行するための .NET SDK バージョン 8 以降
Microsoft Entra にアプリケーションを登録する
Work IQ にアクセスするためのアクセス許可を持つアプリケーションを登録します。 アプリを登録すると、 APP_ID と TENANT_ID の 2 つの値が取得されます。 これらの値を A2A サンプルで使用して、テナント構成をテストします。
ヒント
サーバー側エージェント (Web アプリ) を構築しますか? このクイックスタートでは、作業サンプルへの最も簡単なパスとしてパブリック クライアント 登録 (モバイル/デスクトップ) を使用します。 アプリケーションがエンド ユーザーの代わりに Work IQ を呼び出すサーバー側サービス (たとえば、ユーザーをサインインして ID を Work IQ に転送する Web エージェント) の場合は、クライアント シークレットまたは証明書を使用した 機密クライアント 登録を使用します。 On-Behalf-Of (OBO) フローを使用してユーザーのトークンを交換します。 Work IQ API サーフェスと WorkIQAgent.Ask 委任されたアクセス許可は、どちらのフローでも同じです。
- 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です)
- 詳細設定で、[パブリック クライアント フローを許可する] を [はい] に設定します。
- [保存] を選択します。
- 提案される URI (
- [API アクセス許可]、[アクセス許可を追加]、[APIs my organization uses] の順に選択します。
Work IQを検索し、[委任されたアクセス許可] を選択します。 [WorkIQAgent.Ask]、[アクセス許可の追加] の順に選択します。 - [ テナント] に管理者の同意を与える] を選択します。 確認ダイアログを確認し、[ はい] を選択します。
- Microsoft Entra ID の概要ページからディレクトリ (テナント) ID をコピーします。
WorkIQAgent.Ask アクセス許可を使用すると、サインインしているユーザーに代わってアプリが Work IQ を介して Microsoft 365 ワーク インテリジェンス (メール、ファイル、会議、チャット) を照会できます。
クイック スタート: 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 経由の A2A v1.0 を受け入れます。 (A2A v1.0 では、REST バインディングも /v1/message:send で定義されています。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.0v1.0 を選択します。ヘッダーを省略する (またはA2A-Version: 0.3を送信する) と、ヘッダーなしの既定値である v0.3 が選択されます。
エージェントの検出
特定のエージェントを呼び出すには、その エージェントID を --agent-idに渡します。 エージェントの ID は、2 つの方法で確認できます。
推奨: WorkIQ CLI list-agents (試験段階)
WorkIQ CLI には、サインインしたユーザーが使用できるエージェントを一覧表示する実験的な list-agents コマンドが含まれています。
workiq config set experimental=true
workiq list-agents
各行には、エージェントの表示名、プロバイダー、およびエージェント ID (各エントリの 2 行目) が表示されます。 サンプルを実行するときは、その ID を --agent-id で使用します。
代替方法: Microsoft 365 Copilot URL からコピーする
- Microsoft 365 Copilot Chat Web サイトに移動します。
- 左側のナビゲーションでエージェントを選択します。
-
/chat/agent/後、エージェント ID がブラウザーのアドレス バーに表示されます。
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 エージェント (特に Copilot Chat UI の Word、Excel、PowerPoint エージェント) は、これらの Office 製品のコンテキストで実行するように設計されており、A2A を介してヘッドレスで呼び出されたときに有用な応答を生成しません。
A2A 機能
| 機能 | 状態 |
|---|---|
SendMessage (sync) |
✅ 利用可能 |
マルチターン (contextId) |
✅ 利用可能 |
| テキスト パーツ | ✅ 利用可能 |
| 引用 | ✅ 利用可能 (デリバリー形状は最新化中、リリース ノートを参照) |
認証
| メソッド | プラットフォーム | 使用方法 |
|---|---|---|
| WAM (Windows アカウント マネージャー) | Windows | --token WAM --appid <APP_ID> --tenant <TENANT_ID> |
| 対話型ブラウザー | macOS、Linux | 同じコマンド — Microsoft ID クライアントは、システム ブラウザーによるサインインにフォールバックします。 |
| 事前に取得した JWT | 任意 |
--token <JWT>(トークンは、Azure CLI などの任意のクライアントではなく、登録済みのアプリに対して発行する必要があります) |
トラブルシューティング
| 現象 | 修正プログラム |
|---|---|
401 Unauthorized |
トークン aud が api://workiq.svc.cloud.microsoft と一致しません。 オーディエンス クレームを確認します。 |
403 Forbidden (スコープなしエラー) |
使用量ベースの課金プランのメンバーではないユーザー。 割り当てて 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 ID クライアントがテナント固有の権限を使用するように --tenant <TENANT_ID> 渡します。 |
AADSTS65001: consent required |
管理の同意が付与されていません。
az ad app permission admin-consent --id <APP_ID> を実行します。 |
| 空 200/エージェント テキストなし | ユーザーの Copilot ライセンスが最近割り当てられた場合、インデックスの構築には 15 - 30 分かかることがあります。 Word/Excel/PowerPoint エージェントを呼び出した場合、それらのエージェントは Office 製品で実行され、ヘッドレス A2A 応答を生成しません。 |