Agent 365 CLI 是一款跨平台命令行工具，用于在 Azure 上部署和管理 Agent 365 应用。 本参考资料解释了如何安装、更新、卸载以及使用CLI进行自动化和故障排除。
你不需要手动安装CLI。Agent 365 Skills 会检查 CLI，自动安装或更新，并代表你执行所有必要的命令。 本文是为需要直接安装或使用CLI的开发者提供的参考资料——例如在构建CI/CD自动化、排查特定步骤，或在没有AI编码代理的情况下工作时。
Note
完整的开发人员工作流（包括 AI 引导式设置、角色指南和部署后步骤）在 代理 365 开发入门中。 本文是CLI参考：安装、更新、卸载、可用命令和故障排除。
批量入职替代方案
当你需要同时载入多个代理时，可以使用 Agent 365 批量载入 PowerShell 脚本，作为为每个代理分别运行 a365 CLI 载入工作流的替代方案。 脚本通过 CSV 文件预配蓝图、代理身份、代理用户和代理注册。 它们和CLI是分开的，不是CLI命令。
完整工作流程请参见 Bulk Agent 365 上手指南。 该指南涵盖了前置条件、自动化应用设置、支持的CSV字段和验证规则、执行、结果以及故障排除。
Prerequisites
CLI 需要 .NET 8.0 或更高版本。 关于所有其他前置条件，包括 Azure 订阅和必需的 Entra 角色，请参见快速入门：将现有代理连接到 Agent 365。
Microsoft Entra 身份验证
默认情况下，Agent 365 的设置会使用 Microsoft 管理的 Agent 365 企业级 CLI 应用程序，前提是租户中可用。
| 资产 | Value |
|---|---|
| 显示名称 | Agent 365 CLI |
| 应用程序（客户端）ID | f54280f4-395e-4ea8-9e48-bf2d4952aa14 |
要验证应用，请访问 Microsoft Entra 管理中心，选择 Enterprise 应用>所有应用，并搜索应用 ID。 服务主体的 对象 ID 对于你的租户是唯一的。 不要在CLI或文档要求应用（客户端）ID的情况下使用对象ID。
CLI 会检查你的租户中的企业应用程序的服务主体，并验证访问令牌中所需的委托范围。 它不会创建或修改 Microsoft 的应用注册。 Microsoft 管理的应用程序不会提升登录用户权限，不会绕过条件访问或安全默认，也不会取消代理资源的单独同意要求。
如果由 Microsoft 管理的企业应用不可用，免配置设置会查找名为 Agent 365 CLI 的租户拥有的应用。 指定了自定义 clientAppId 的现有配置仍受支持。 有关说明，请参见 Agent 365 CLI的自定义客户端应用注册。
Microsoft 管理的应用程序使用以下交互式认证方法：
| 环境 | 身份验证方法 |
|---|---|
| 原生 Windows | Web 帐户管理器 (WAM) |
| 适用于 Linux 的 Windows 子系统（WSL）、macOS 和 Linux | 设备代码 |
租户拥有的自定义应用在无WAM时使用系统浏览器。
安装代理 365 CLI
使用以下步骤在操作系统上全局安装Agent 365 CLI。
Prerequisites
您必须安装 .NET。 （建议.NET 8.0。
使用 DotNet 工具安装
使用以下命令安装代理 365 CLI：
dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli
有关最新说明和可用版本，请访问官方 NuGet 页面：Microsoft.Agents.A365.DevTools.Cli on NuGet.org
验证安装
安装 Agent 365 CLI 后，通过执行 --help 以下命令确认安装正确：
a365 -h
此命令显示帮助信息，并确认 CLI 已准备就绪。
更新Agent 365的CLI
使用 dotnet tool update 命令更新 Agent 365 CLI。
dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli
Note
要更新 Agent 365 CLI，你需要有互联网连接才能访问最新的 NuGet 包： Microsoft.Agents.A365.DevTools.Cli。
卸载Agent 365的CLI功能
使用 dotnet tool uninstall 命令卸载 Agent 365 CLI：
dotnet tool uninstall --global Microsoft.Agents.A365.DevTools.Cli
Agent 365 CLI 文件位置
工具二进制文件的默认位置取决于操作系统：
| 操作系统 | 路径 |
|---|---|
| Linux/macOS | $HOME/.dotnet/tools |
| Windows操作系统 | %USERPROFILE%\.dotnet\tools |
SDK在你第一次运行时会把这个位置添加到你的路径中。 你可以从任意目录调用全局工具，无需指定工具位置。
工具访问特定于用户，而不针对计算机全局。 全局工具仅对安装该工具的用户开放。
美国政府云
默认情况下，Agent 365 CLI 针对的是 Microsoft 商业云。 它通过使用 https://login.microsoftonline.com 进行身份验证，在 https://graph.microsoft.com 调用 Microsoft Graph，并在 https://agent365.svc.cloud.microsoft 调用 Agent 365 服务。 要在 Microsoft 365 美国政府云中运行 CLI，将环境设置为 gcc、gcc-high 或 dod，并配置该云的终结点。
环境名称用于选择特定于云的设置，但本身不会更改任何端点。 对于GCC，设置Agent 365工具的发现端点。 对于GCC High和DoD，也要设置权威主机和Microsoft Graph的基础URL。
在 a365.config.json（environment、authorityHost 和 graphBaseUrl）中设置环境、授权主机和 Graph 基础 URL，或使用下表中列出的环境变量。 环境作用域变量以归一化云名后缀（<ENV>如 GCC 或 GCC_HIGH）结尾，优先于匹配 a365.config.json 字段。
| Variable | Description |
|---|---|
A365_ENVIRONMENT |
云环境名称。 当 a365.config.json 未设置 environment 时，CLI 使用该值，并用于不读取 a365.config.json 的命令。 默认值为 prod。 |
A365_AUTHORITY_HOST_<ENV> |
OAuth 授权主机。 该值在 a365.config.json 中优先于 authorityHost。 |
A365_GRAPH_BASE_URL_<ENV> |
Microsoft Graph 基础网址。 该值在 a365.config.json 中优先于 graphBaseUrl。 |
A365_DISCOVER_ENDPOINT_<ENV> |
Agent 365 工具的发现端点。 CLI 还会将其源用于相关的 Agent 365 服务调用。 |
A365_CREATE_ENDPOINT_<ENV> |
消息端点注册URL。 |
A365_DELETE_ENDPOINT_<ENV> |
消息端点移除URL。 |
A365_MCP_APP_ID_<ENV> |
CLI 用于获取工具服务器令牌的 Agent 365 Tools 资源应用程序 ID。 大多数开发者不需要设置这个变量。 |
关于云端点值、 <ENV> 后缀规范化规则及完整示例，请参见 “配置美国政府云的Agent 365 CLI”。
Agent 365 CLI 的命令
如需查看完整的可用命令列表，请使用该 --help 命令或参见 Agent 365 CLI 参考。
Tip
无需手动运行 CLI 命令。 Agent 365 Skills 通过 AI 编码代理自动化完整的工作流程——CLI 安装、配置、蓝图设置、部署和发布。 如果您正在构建 CI/CD 自动化、排查特定步骤，或是在没有 AI 编码代理的情况下工作，可参考此处的 CLI。
有关如何使用 CLI 设置代理 365 代理的完整说明，请参阅 代理 365 开发入门。
Troubleshooting
本节提供有关如何排查Agent 365 CLI错误的信息。
Tip
Agent 365 故障排除指南 包含高层次的故障排除建议、最佳实践以及针对 Agent 365 开发生命周期各阶段的故障排除内容链接。
本节涵盖的CLI特定问题：
- Microsoft 管理的 Agent 365 CLI 应用程序不可用
- 设备代码认证被阻止
- 身份验证失败，出现 AADSTS70007
- 缺少必要的委派范围
- Agent 不会出现在 Teams 里
- 无法在Teams中创建代理实例
Microsoft 管理的 Agent 365 CLI 应用程序不可用
更新CLI并再次运行 a365 setup requirements 。 要验证分阶段部署是否到达您的租户，请在 Microsoft Entra 中搜索 Enterprise 应用中的应用 ID f54280f4-395e-4ea8-9e48-bf2d4952aa14。
如果服务主体不存在，设置会退回到一个名为 Agent 365 CLI 的租户拥有应用。 如果你还没有这个应用，请按照 Agent 365 CLI的自定义客户端应用注册操作。
设备代码认证被阻止
该Microsoft管理的应用程序在WSL、macOS和Linux上使用设备代码认证。 安全默认设置或条件访问策略可以阻止该流并返回 AADSTS530035。
不要禁用组织的安全策略来绕过这个错误。 可以在原生 Windows 上运行 CLI 以使用 WAM，或者与你的身份管理员合作，使用租户拥有的自定义应用和策略允许的认证流程。
身份验证失败，错误代码 AADSTS70007
较旧的CLI版本可能会在Microsoft管理的应用程序中使用不支持的浏览器响应模式，返回 AADSTS70007。 更新到最新的CLI版本并重试：
dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli
缺少必要的委派范围
该 CLI 从访问令牌的 scp 声明中验证由 Microsoft 管理的应用程序的有效委托权限。 更新CLI并重新运行 a365 setup requirements。
不要向Microsoft管理的应用程序添加重定向URI、可选声明、API权限或租户本地权限。 如果验证仍提示缺少作用域，请从错误信息中获取跟踪 ID 和关联 ID，并联系 Microsoft 支持部门。 如果您使用租户拥有的应用，请按照 Agent 365 CLI的自定义客户端应用注册验证步骤操作。