工作 IQ API 快速入门 (预览版)

重要

Work IQ 以 公共预览版提供。 功能和 API 可能会在正式发布之前更改，并且没有设置 SLA。

工作 IQ 是Microsoft AI 原生接口，用于Microsoft 365 工作智能。 它允许你构建应用程序，这些应用程序可以使用自然语言查询电子邮件、会议、文件和组织知识;以Microsoft 365 数据为基础。

本快速入门介绍代理到代理 (A2A) 协议。 A2A是代理通信的开放标准，支持针对工作 IQ 网关的同步模式。 即将推出 (服务器发送事件的流式处理模式 (SSE) ) 支持。

先决条件

• 具有智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®许可证的用户
• 用于运行示例代码的 .NET SDK 版本 8 或更高版本
• 具有一次性 Work IQ 设置的组织管理员访问权限的用户

在组织中启用 Work IQ API

⏱️ 大约 5 分钟，每个组织一次。

本部分将在组织中创建两项内容：

• Work IQ 服务主体 (预配 Work IQ 资源，以便用户可以为其请求令牌)
• 客户端代码使用委托权限进行身份验证WorkIQAgent.Ask的应用注册

(或组织管理员) 可以使用 Microsoft Entra 管理中心 或 Azure CLI 来完成此步骤。

管理员中心

步骤 1. (Graph 资源管理器) 创建 Work IQ 服务主体

1. 转到 Graph 资源管理器 并使用管理员帐户登录。

2. 将 方法设置为 POST ，将 URL 设置为 https://graph.microsoft.com/v1.0/servicePrincipals。 图形资源管理器基于 URL 和方法显示相关范围，因此必须在下一步中同意之前输入 URL。

3. 选择 “修改权限 并同意 Application.ReadWrite.All”。 此步骤是一次性的管理员操作， 仅为你自己的 Graph 资源管理器会话授予范围。 它不会更改组织范围的权限。

4. 在 “请求”正文中输入以下内容。

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

5. 选择 运行查询。 “创建 201”响应确认成功。 冲突错误意味着服务主体已存在 - 可以继续执行下一步。

步骤 2. 创建应用注册

1. 转到Microsoft Entra 管理中心。 在左侧导航窗格中，选择“Entra ID”，然后选择“应用注册”。
2. 选择“新注册”。
3. 添加描述性名称，将 “支持的帐户类型 ”设置为 “仅此组织目录中的帐户”。 选择“注册”。
4. 复制 应用程序 (客户端) ID。 此值为 。APP_ID
5. 选择“ 身份验证”。 选择 “添加平台 (”或“ 添加重定向 URI) ”。 在对话框中，选择“ 移动和桌面应用程序”。
   • 选择建议的 URI： https://login.microsoftonline.com/common/oauth2/nativeclient。
   • 在 “自定义重定向 URI”下，一次添加以下两 个 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 工作智能 (邮件、文件、会议、聊天) 。

Azure CLI

1. 在组织中创建 Work IQ 服务主体。

   az ad sp create --id fdcc1f02-fc51-4226-8753-f668596af7f7
   

2. 创建应用注册。

   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"
   

3. 为应用创建服务主体。

   az ad sp create --id $APP_ID
   

4. 配置三个公共客户端重定向 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"
   

5. 添加 WorkIQAgent.Ask 委托权限并授予同意。

   注意

   dcc1f02-fc51-4226-8753-f668596af7f7 是 Work IQ 应用程序 ID，是 0b1715fd-f4bf-4c63-b16d-5be31f9847c2WorkIQAgent.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
   

6. 获取租户 ID。

   az account show --query tenantId -o tsv
   

现在应具有两个值： APP_ID 和 TENANT_ID。 通过 --appid 和 --tenant将这些值传递给示例。

提示

) (Web 应用生成服务器端代理？ 本快速入门使用 公共客户端 注册 (移动/桌面) 作为工作示例的最简单路径。 例如，如果应用程序是代表最终用户调用 Work IQ 的服务器端服务 (，则 Web 代理将用户登录，然后将其标识转发到 Work IQ) ，使用 客户端机密客户端 注册和客户端密码或证书，并通过 “代表 (OBO) 流交换用户的令牌。 工作 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 在 接受 A2A v1.0，通过 JSON-RPChttps://workiq.svc.cloud.microsoft/a2a/在 。 (A2A v1.0 还定义 ;/v1/message:sendWork IQ 可能会在将来的预览版 update 中公开此 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."
        }
      ]
    }
  }
}

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

• 需要 JSON-RPC 信封： 每个请求必须包含 jsonrpc、 id、 method、 params。
• POST 到基 URL： 方法 (SendMessage) 位于 JSON-RPC 正文中，而不是 URL 路径内。
• 现场存在部件：部件是具有 、url、 raw或data集之一的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，即无标头默认值。

代理发现

若要调用特定代理，请通过 --agent-id传递其代理 ID。 可通过两种方法查找代理的 ID。

建议：WorkIQ CLI list-agents (实验性)

WorkIQ CLI 附带了一个试验性list-agents命令，用于打印可供登录用户使用的代理。

workiq config set experimental=true
workiq list-agents

每行显示代理的显示名称、提供程序和代理 ID， (每个条目的第二行) 。 运行示例时，请将该 ID 与 一起使用 --agent-id 。

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

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

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

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

注意

某些Microsoft 365 个代理 (值得注意的是，Copilot 对话助手 UI) 中的Word、Excel 和 PowerPoint 代理设计为在这些 Office 产品的上下文中运行，并且通过 A2A 无外设调用时不会产生有用的响应。

A2A功能

功能	状态
SendMessage (同步)	✅ 可用
多轮次 (contextId)	✅ 可用
文本部分	✅ 可用
引文	✅ 可用 (交付形状正在现代化;请参阅发行说明)

---

身份验证

方法	平台	用法
WAM (Windows 帐户管理器)	Windows	--token WAM --appid <APP_ID> --tenant <TENANT_ID>
交互式浏览器	macOS、Linux	相同的命令 - Microsoft标识客户端回退到系统浏览器登录。
预获取的 JWT	任何	--token <JWT> (必须为已注册的应用颁发令牌，而不是为任意客户端（如 Azure CLI) ） 颁发令牌

---

疑难解答

症状	修补程序
401 Unauthorized	令牌 aud 与 不匹配 api://workiq.svc.cloud.microsoft。 检查受众声明。
403 Forbidden) 没有范围错误 (	用户缺少智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®许可证。 分配并等待 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响应。

---

相关内容

• GitHub 上的示例代码
• 工作 IQ API 概述
• A2A协议规范
• A2A .NET SDK
• A2A v0.3 → v1.0 迁移指南