使用 Agent 365 CLI 接入单个智能体

使用Agent 365的CLI为某个代理创建Microsoft Entra身份对象,并向Agent 365注册该代理。 先用一个非生产代理,这样你可以在 批量接入代理之前验证身份、权限、用户同意和注册。

本文以费用审核作为标准智能体的基准名称,该智能体代表已登录的员工审核费用报销单。 它使用代表身份验证 (OBO),不需要自己的 Microsoft Entra 用户账户、邮箱或 Teams 状态。

此无需配置的工作流将创建:

  • 一个名为“费用审查蓝图”的代理身份蓝图。
  • 一个名为 Expense Review Agent的代理身份。
  • 用于 OBO 身份验证的委托权限授予
  • 该智能体的 Agent 365 注册信息。
  • 一个 a365.generated.config.json 记录生成标识符和设置状态的文件。

关于身份对象的解释,请参见 Agent 365 identity。

Prerequisites

在开始之前,请确保:

  • 一个启用了 Agent 365 的 Microsoft 租户。 请在非生产租户或测试环境中进行本操作演示。
  • 同一租户中的Azure订阅。
  • Azure 订阅的参与者角色。
  • 至少需要在 Microsoft Entra ID 中具有 Agent ID Developer 角色,才能创建蓝图和代理身份。
  • 一个可授予OAuth权限的 全局管理员 。 如果你担任这个角色,可以在一次会话内完成整个工作流程。 否则,CLI 会提供需发送给全局管理员的同意 URL。
  • 如果您将场景更改为使用服务到服务 (S2S) 身份验证,则需要应用程序管理员或全局管理员角色。
  • .NET 8.0或更高版本。
  • Azure CLI,已登录到您要使用的租户和订阅。
  • Agent 365 CLI。

Agent 365 的设置会使用 Microsoft 管理的 Agent 365 企业级 CLI 应用,前提是租户中有该应用。 其应用(客户端)ID为 f54280f4-395e-4ea8-9e48-bf2d4952aa14。 如果应用不可用,CLI会寻找一个名为 Agent 365 CLI的租户拥有的应用。 全局管理员可以通过CLI提示符创建和配置租户拥有的应用。 有关回退的详细信息,请参见 Agent 365 CLI 的自定义客户端应用注册。

Note

这种情景不会生成代理用户。 代理用户仅在代理需要其自身授权的 Microsoft 365 资源(如邮箱)时使用,且仅对参与 Frontier 预览计划的租户开放。

安装代理 365 CLI

将CLI安装为全局.NET工具:

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli

如果CLI已经安装,请更新它:

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

验证安装:

a365 --version

有关安装故障排查和支持的文件位置,请参见 安装并使用 Agent 365 CLI。

选择租户和订阅

登录到 Azure:

az login

列出你账户可用的订阅:

az account list --output table

在租户中选择要为智能体进行接入的订阅:

az account set --subscription "<subscription-id-or-name>"

确认活跃租户和订阅:

az account show --query "{tenantId:tenantId, subscriptionId:id, subscriptionName:name}" --output table

记录租户 ID。 CLI 会根据当前活动的 Azure CLI 帐户自动检测该订阅。 你也可以通过使用 --tenant-id显式提供。

验证先修条件

从任意目录中运行依赖项检查:

a365 setup requirements

该命令会检查身份验证、Azure 访问权限、租户注册、角色以及客户端应用程序。 检查失败后会继续,这样你就可以统一查看所有检测到的问题。

在继续之前,先解决所有失败的必检项。 如果 Microsoft 管理的企业应用不可用,请按照提示选择或创建租户拥有的客户端应用,然后重新运行该命令。

重要

不要修改Microsoft管理的Agent 365 CLI应用程序。 CLI会验证其服务主体和访问令牌中的作用域,但不会修改Microsoft的应用注册。

预览入职变更

为生成的配置创建一个空的工作目录,然后切换到该目录:

New-Item -ItemType Directory -Path .\expense-review-agent
Set-Location .\expense-review-agent

在不创建租户对象的情况下预览更改:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false `
    --dry-run

查看租户ID、衍生对象名、所选客户端应用、权限和认证模式。 由于智能体代表已登录的员工行事,因此此场景使用默认的 obo 身份验证模式。

如果检测到的租户不正确,请明确说明:

a365 setup all `
    --agent-name "Expense Review" `
    --tenant-id "<tenant-id>" `
    --aiteammate false `
    --dry-run

接入智能体

不带 --dry-run 运行相同的命令:

a365 setup all `
    --agent-name "Expense Review" `
    --aiteammate false

CLI再次验证需求,创建蓝图和代理身份,配置委派权限,注册代理,并写入a365.generated.config.json。

如果你以全局管理员身份登录,请完成设置过程中打开的任何同意提示。 如果你使用代理ID开发者或代理ID管理员角色,CLI会完成你角色允许的步骤,并打印全局管理员的同意操作。 将生成的同意 URL 发送给全局管理员,并要求他们完成所有授权。

Note

无配置设置假设代理托管在外部。 它不会创建Azure托管资源,也不会更新代理项目。

验证接入结果

查看设置摘要。 每个必需步骤都应显示已完成。 如果全局管理员仍需授予同意,请在完成该转接操作后,才视为接入完成。

检查生成的配置:

Get-Content .\a365.generated.config.json | ConvertFrom-Json

确认输出内容包括:

  • 一个代理蓝图 ID。
  • 设置已完成,没有待处理的同意操作。

确认设置摘要报告代理身份创建和代理注册成功。

然后在 Microsoft 365 管理中心 验证注册情况:

  1. 转到Microsoft 365 管理中心。
  2. 选择 代理人,>所有代理人。
  3. 查找费用审核智能体。
  4. 打开代理,确认其身份和注册信息是否与生成的配置一致。

排查接入问题

症状 解决方案
要求检查报告显示租户或订阅有误。 运行 az account set --subscription "<subscription-id-or-name>",用 az account show 验证结果,然后重新运行需求检查。 或者,将 --tenant-id 传给 a365 setup all。
找不到 Microsoft 管理的 Agent 365 CLI 应用程序。 更新CLI并重新运行 a365 setup requirements。 如果分阶段部署尚未向你的租户推出,可以使用租户拥有的客户端应用。
设置报告称缺少某个角色。 将“贡献者”和“Agent ID Developer”角色分配给操作员。 请等待分配生效,重新登录,然后重新运行要求检查。
设置已完成,但列出了待处理的同意操作。 让全局管理员打开CLI打印的每一个同意URL,并授予所请求的权限。
蓝图或身份存在,但代理不在 所有代理中。 请查看代理注册失败的设置摘要。 解决错误后,重新运行 a365 setup all --agent-name "Expense Review" --agent-registration-only。
设置选择了错误的身份验证模式。 当代理为登录用户操作时,使用默认的OBO模式。 使用--authmode s2s处理后台工作,或在需要两种模式时使用--authmode both S2S 授权需要应用程序管理员或全局管理员。

如需更多针对CLI的解决方案,请参见 Agent 365故障排除。

后续步骤