Work IQ A2A クイックスタート

前提条件

• Work IQ のテナントを有効にする
• サンプル コードを実行するための .NET SDK バージョン 8 以降

Microsoft Entraでアプリケーションを登録する

Work IQ にアクセスするためのアクセス許可を持つアプリケーションを登録します。 アプリを登録すると、 APP_ID と TENANT_IDの 2 つの値が取得されます。 A2A サンプルでこれらの値を使用して、テナント構成をテストします。

クイック スタート: 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 が選択され、ヘッダーなしが既定値になります。

エージェントの検出

特定のエージェントを呼び出すには、 エージェント ID を--agent-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 からコピーする

1. Microsoft 365 Copilot Chat Web サイト:https://m365.cloud.microsoft/chat/に移動します。
2. 左側のナビゲーションでエージェントを選択します。
3. エージェント 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 を引数としてサンプルに渡す

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

A2A機能

認証

トラブルシューティング

関連コンテンツ

• GitHub のサンプル コード
• Work IQ API の概要
• テナントで Work IQ を有効にする
• A2Aプロトコル仕様
• .NET SDK のA2A
• A2A v0.3 → v1.0 移行ガイド