Work IQ A2A 快速入门

先决条件

在 Microsoft Entra 中注册应用程序

注册具有访问 Work IQ 权限的应用程序。 注册应用时,你会获得两个值: APP_ID 和 TENANT_ID。 将这些值与 A2A 示例一起使用,以测试租户配置。

提示

构建服务器端代理 (Web 应用) ? 本快速入门使用 公共客户端 注册 (移动/桌面) 获取工作示例的最简单路径。 如果您的应用程序是代表最终用户调用 Work IQ 的服务器端服务 (例如,Web 代理登录用户然后将其身份转发到 Work IQ) ,请使用带有客户端密码或证书的 机密客户端 注册。 使用 On-Behalf-Of (OBO) 流交换用户的令牌。 Work IQ API 图面和 WorkIQAgent.Ask 委托权限在两个流中相同。

  1. 转到 Microsoft Entra 管理中心。 在左侧导航窗格中,选择 Entra ID,然后选择 应用注册。
  2. 选择“新注册”。
  3. 添加描述性名称,将支持的帐户类型设置为仅此组织目录中的帐户,然后选择注册。
  4. 将 应用程序复制 (客户端) ID。 此值属于你的 APP_ID.
  5. 选择“ 身份验证”。 选择“ 添加平台 (”或“ 添加重定向 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>
    • 在 高级设置下,将 “允许公共客户端流” 设置为 “是”。
    • 选择“保存”。
  6. 选择“API 权限”、“添加权限”,然后选择“我的组织使用的 API”。 搜索 Work IQ,然后选择“ 委托的权限”。 选择 WorkIQAgent.Ask ,然后选择 “添加权限”。
  7. 选择“ 为 [你的租户] 授予管理员同意”。 查看确认对话框,然后选择 是。
  8. 从 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 在 JSON-RPChttps://workiq.svc.cloud.microsoft/a2a/上接受 A2A v1.0。 (A2A v1.0 还在 /v1/message:send;Work 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请求标头启用 v1.0 方法名称 (SendMessage 网关上的) 。 如果没有它,服务器默认为 v0.3,并为 v1.0 方法名称返回 JSON-RPC -32601 "Method not found" 。

响应是一个 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."
            }
          ]
        }
      ]
    }
  }
}

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

v1.0) (A2A 关键协议详细信息

  • 需要 JSON-RPC 信封: 每个请求都必须包括 jsonrpc、 id、 method、 params。
  • POST 到基本 URL:) (SendMessage 方法位于 JSON-RPC 正文中,而不是 URL 路径中。
  • 场状态部分:部分是平面对象,具有 、 urlraw或 data set_之一text;无kind鉴别器。
  • SCREAMING_SNAKE_CASE 枚举:角色使用ROLE_USER / ROLE_AGENT;状态使用 / TASK_STATE_WORKING / TASK_STATE_COMPLETEDTASK_STATE_FAILED / 等等。
  • 结果包装器: 任务响应显示在 result.task下。
  • 版本调度:A2A-Version: 1.0 选择 v1.0;省略标头 (或发送 A2A-Version: 0.3) 将选择 v0.3,即无标头默认值。

代理发现

要调用特定代理,请将其 代理 ID 传递给 --agent-id。 可以通过两种方式查找代理的 ID。

WorkIQ CLI 包括一个实验list-agents性命令,其中列出了可供登录用户使用的代理。

workiq config set experimental=true
workiq list-agents

每行在每个条目) 的第二行 (显示代理的显示名称、提供商和代理 ID。 运行示例时使用该 ID --agent-id 。

替代方法:从 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® URL 复制

  1. 转到 智能 Microsoft 365 Copilot 副驾驶® 对话助手网站。
  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 视为不透明的字符串。 不要解析或解析其组件。 将其按原样传递给 API。

将代理 ID 作为参数传递到示例

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

▶ 在交互式演示中打开特定于代理的库存提示。

注意

Copilot 对话助手 UI) 中的某些 Microsoft 365 智能体 (特别是 Word、Excel 和 PowerPoint 智能体,它们设计为在这些 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 (无作用域错误) 用户不是基于使用情况的计费计划的成员。 分配并等待 15–30 分钟。
具有 Required scopes = [...] 的 403 Forbidden 未授予管理员同意WorkIQAgent.Ask。 重新运行管理员同意 (管理员设置步骤 6 / Azure CLI 步骤 3) 。
WAM IncorrectConfiguration (3399614466) 应用注册缺少代理重定向 URI。 重新添加 ms-appx-web://microsoft.aad.brokerplugin/<APP_ID> ,然后重试。
设置重定向 URI 后 WAM 仍失败 单租户应用 + /common 颁发机构不匹配。 传递 --tenant <TENANT_ID> ,以便 Microsoft 标识客户端使用特定于租户的权限。
AADSTS65001: consent required 尚未授予管理员同意。 运行 az ad app permission admin-consent --id <APP_ID>。
空 200/无代理文本 如果最近分配了用户的 Copilot 许可证,则可能需要 15-30 分钟才能生成索引。 如果调用了 Word/Excel/PowerPoint 智能体,这些智能体将在 Office 产品中运行,不会生成无外设 A2A 响应。