Microsoft Agent 365 DevTools CLI

Skill by ara.so — Devtools Skills collection.

The Microsoft Agent 365 DevTools CLI is a command-line interface tool designed to streamline the development, deployment, and management of Microsoft Agent 365 applications. It provides comprehensive tooling for configuration management, Azure resource provisioning, MCP (Model Context Protocol) server integration, and agent deployment workflows.

由ara.so提供的Skill —— Devtools Skills集合。

Microsoft Agent 365 DevTools CLI是一款命令行界面工具，旨在简化Microsoft Agent 365应用程序的开发、部署和管理流程。它提供了全面的工具集，用于配置管理、Azure资源调配、MCP（模型上下文协议）服务器集成以及代理部署工作流。

What It Does

功能介绍

Develop: Manage MCP tool servers for local agent development
Setup: Create Azure resources, configure permissions, and register agent blueprints
Publish: Update agent manifest IDs and package for Microsoft 365 Admin Center
Deploy: Deploy application binaries to Azure App Service and update tool permissions
Config: Configure Azure subscription, resources, and deployment options
Query Entra: Query Microsoft Entra ID for agent permissions and consent status
Cleanup: Remove all resources (blueprints, instances, Azure resources)

开发：管理MCP工具服务器以进行本地代理开发
设置：创建Azure资源、配置权限并注册代理蓝图
发布：更新代理清单ID并打包用于Microsoft 365管理中心
部署：将应用程序二进制文件部署到Azure App Service并更新工具权限
配置：配置Azure订阅、资源和部署选项
查询Entra：查询Microsoft Entra ID以获取代理权限和同意状态
清理：移除所有资源（蓝图、实例、Azure资源）

Installation

安装步骤

Prerequisites

前置条件

.NET 8.0 or higher - Download .NET
Entra ID App Registration with delegated Microsoft Graph API permissions
Azure Subscription with appropriate permissions

.NET 8.0或更高版本 - 下载.NET
Entra ID应用注册，需具备委托的Microsoft Graph API权限
Azure订阅，拥有相应权限

Install from NuGet

从NuGet安装

powershell

dotnet tool install -g Microsoft.Agents.A365.DevTools.Cli --prerelease

powershell

dotnet tool install -g Microsoft.Agents.A365.DevTools.Cli --prerelease

Verify Installation

验证安装

powershell

a365 --version

powershell

a365 --version

Entra ID App Registration Setup

Entra ID应用注册设置

Before using the CLI, create a custom Entra ID app registration:

Navigate to Azure Portal > Entra ID > App Registrations
Create new registration (e.g., "Agent365-DevTools-Client")
Configure Delegated permissions (NOT Application permissions):
- Microsoft Graph API permissions as required
Grant admin consent for all permissions
Note your
```
Client ID
```
and
```
Tenant ID
```

Set environment variables:

powershell

undefined

使用CLI之前，请创建自定义Entra ID应用注册：

导航至Azure门户 > Entra ID > 应用注册
创建新注册（例如："Agent365-DevTools-Client"）
配置委托权限（而非应用权限）：
- 根据需求添加Microsoft Graph API权限
为所有权限授予管理员同意
记录你的
```
Client ID
```
和
```
Tenant ID
```

设置环境变量：

powershell

undefined

Windows PowerShell

$env:AGENT365_CLIENT_ID="your-client-id" $env:AGENT365_TENANT_ID="your-tenant-id"

Linux/macOS

export AGENT365_CLIENT_ID="your-client-id" export AGENT365_TENANT_ID="your-tenant-id"

undefined

export AGENT365_CLIENT_ID="your-client-id" export AGENT365_TENANT_ID="your-tenant-id"

undefined

Key Commands

核心命令

Config Command

配置命令

Configure your Agent 365 environment settings:

powershell

undefined

配置你的Agent 365环境设置：

powershell

undefined

Set Azure subscription

设置Azure订阅

a365 config set --subscription "your-subscription-id"

Set resource group

设置资源组

a365 config set --resource-group "agent365-rg"

Set Azure region

设置Azure区域

a365 config set --location "eastus"

View current configuration

查看当前配置

a365 config show

Reset configuration

重置配置

a365 config reset

undefined

a365 config reset

undefined

Setup Command

设置命令

Create Azure resources and register your agent blueprint:

powershell

undefined

创建Azure资源并注册你的代理蓝图：

powershell

undefined

Interactive setup (recommended for first-time setup)

交互式设置（首次设置推荐使用）

a365 setup

Automated setup with parameters

参数化自动设置

a365 setup --subscription "sub-id"
--resource-group "agent365-rg"
--location "eastus"
--app-name "my-agent365-app"
--manifest-path "./agent-manifest.json"

Setup with existing resources

使用现有资源进行设置

a365 setup --use-existing-resources --app-service-name "existing-app"

undefined

a365 setup --use-existing-resources --app-service-name "existing-app"

undefined

Develop Command

开发命令

Manage MCP tool servers for local development:

powershell

undefined

管理MCP工具服务器以进行本地开发：

powershell

undefined

Start MCP server for development

启动用于开发的MCP服务器

a365 develop start --server-path "./mcp-server" --port 5000

List running MCP servers

列出运行中的MCP服务器

a365 develop list

Stop MCP server

停止MCP服务器

a365 develop stop --server-id "server-123"

Test MCP server connection

测试MCP服务器连接

a365 develop test --server-url "http://localhost:5000"

undefined

a365 develop test --server-url "http://localhost:5000"

undefined

Develop-MCP Command

Develop-MCP命令

Manage MCP servers in Dataverse environments:

powershell

undefined

在Dataverse环境中管理MCP服务器：

powershell

undefined

Register MCP server in Dataverse

在Dataverse中注册MCP服务器

a365 develop-mcp register
--environment "your-env-url"
--server-name "MyMCPServer"
--server-url "https://mcp.example.com"

List MCP servers in environment

列出环境中的MCP服务器

a365 develop-mcp list --environment "your-env-url"

Remove MCP server

移除MCP服务器

a365 develop-mcp remove --environment "your-env-url" --server-id "server-id"

undefined

a365 develop-mcp remove --environment "your-env-url" --server-id "server-id"

undefined

Deploy Command

部署命令

Deploy your Agent 365 application to Azure:

powershell

undefined

将你的Agent 365应用部署到Azure：

powershell

undefined

Deploy application binaries

部署应用程序二进制文件

a365 deploy --project-path "./src/MyAgent365App"
--configuration "Release"

Deploy with specific runtime

使用特定运行时部署

a365 deploy --project-path "./src/MyAgent365App"
--runtime "win-x64"
--configuration "Release"

Deploy and update tool permissions

部署并更新工具权限

a365 deploy --project-path "./src/MyAgent365App"
--update-permissions

undefined

a365 deploy --project-path "./src/MyAgent365App"
--update-permissions

undefined

Publish Command

发布命令

Package your agent manifest for Microsoft 365 Admin Center:

powershell

undefined

打包代理清单以用于Microsoft 365管理中心：

powershell

undefined

Update manifest IDs and package

更新清单ID并打包

a365 publish --manifest-path "./agent-manifest.json"
--output-path "./dist"

Publish with custom app package name

使用自定义应用包名称发布

a365 publish --manifest-path "./agent-manifest.json"
--output-path "./dist"
--package-name "my-agent-package"

Validate manifest only (no packaging)

仅验证清单（不打包）

a365 publish --manifest-path "./agent-manifest.json"
--validate-only

undefined

a365 publish --manifest-path "./agent-manifest.json"
--validate-only

undefined

Query-Entra Command

Query-Entra命令

Query Microsoft Entra ID for agent information:

powershell

undefined

查询Microsoft Entra ID获取代理信息：

powershell

undefined

Query agent scopes and permissions

查询代理范围和权限

a365 query-entra --agent-id "agent-blueprint-id"

Check consent status

检查同意状态

a365 query-entra --agent-id "agent-blueprint-id"
--check-consent

List all agents in tenant

列出租户中的所有代理

a365 query-entra --list-all

Export agent configuration

导出代理配置

a365 query-entra --agent-id "agent-blueprint-id"
--export-config "./agent-config.json"

undefined

a365 query-entra --agent-id "agent-blueprint-id"
--export-config "./agent-config.json"

undefined

Cleanup Command

清理命令

Remove Agent 365 resources:

powershell

undefined

移除Agent 365资源：

powershell

undefined

Clean up all resources (interactive confirmation)

清理所有资源（需交互式确认）

a365 cleanup

Clean up specific resource group

清理特定资源组

a365 cleanup --resource-group "agent365-rg"

Force cleanup without confirmation

强制清理无需确认

a365 cleanup --force

Clean up only blueprint (keep Azure resources)

仅清理蓝图（保留Azure资源）

a365 cleanup --blueprint-only --agent-id "blueprint-id"

undefined

a365 cleanup --blueprint-only --agent-id "blueprint-id"

undefined

Configuration File

配置文件

The CLI stores configuration in a local file (typically

~/.agent365/config.json

):

json

{
  "azureSubscriptionId": "your-subscription-id",
  "resourceGroup": "agent365-rg",
  "location": "eastus",
  "appServiceName": "my-agent365-app",
  "appServicePlanName": "agent365-plan",
  "clientId": "your-client-id",
  "tenantId": "your-tenant-id"
}

CLI将配置存储在本地文件中（通常为

~/.agent365/config.json

）：

json

{
  "azureSubscriptionId": "your-subscription-id",
  "resourceGroup": "agent365-rg",
  "location": "eastus",
  "appServiceName": "my-agent365-app",
  "appServicePlanName": "agent365-plan",
  "clientId": "your-client-id",
  "tenantId": "your-tenant-id"
}

Agent Manifest Structure

代理清单结构

Example

agent-manifest.json

:

json

{
  "$schema": "https://developer.microsoft.com/json-schemas/agent365/v1.0/agent-manifest.schema.json",
  "id": "com.example.myagent",
  "version": "1.0.0",
  "name": {
    "short": "My Agent",
    "full": "My Agent 365 Application"
  },
  "description": {
    "short": "An intelligent agent",
    "full": "A comprehensive agent for Microsoft 365"
  },
  "developer": {
    "name": "Your Company",
    "websiteUrl": "https://example.com",
    "privacyUrl": "https://example.com/privacy",
    "termsOfUseUrl": "https://example.com/terms"
  },
  "icons": {
    "color": "color-icon.png",
    "outline": "outline-icon.png"
  },
  "capabilities": [
    {
      "name": "conversation",
      "messageHandlers": [
        {
          "type": "message",
          "value": "handleMessage"
        }
      ]
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "*.example.com"
  ]
}

示例

agent-manifest.json

：

json

{
  "$schema": "https://developer.microsoft.com/json-schemas/agent365/v1.0/agent-manifest.schema.json",
  "id": "com.example.myagent",
  "version": "1.0.0",
  "name": {
    "short": "My Agent",
    "full": "My Agent 365 Application"
  },
  "description": {
    "short": "An intelligent agent",
    "full": "A comprehensive agent for Microsoft 365"
  },
  "developer": {
    "name": "Your Company",
    "websiteUrl": "https://example.com",
    "privacyUrl": "https://example.com/privacy",
    "termsOfUseUrl": "https://example.com/terms"
  },
  "icons": {
    "color": "color-icon.png",
    "outline": "outline-icon.png"
  },
  "capabilities": [
    {
      "name": "conversation",
      "messageHandlers": [
        {
          "type": "message",
          "value": "handleMessage"
        }
      ]
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "*.example.com"
  ]
}

Common Development Workflow

常见开发工作流

1. Initial Setup

1. 初始设置

powershell

undefined

powershell

undefined

Install CLI

安装CLI

dotnet tool install -g Microsoft.Agents.A365.DevTools.Cli --prerelease

Configure environment

配置环境

a365 config set --subscription $env:AZURE_SUBSCRIPTION_ID a365 config set --resource-group "agent365-dev-rg" a365 config set --location "eastus"

Set up Azure resources and blueprint

设置Azure资源和蓝图

a365 setup --manifest-path "./agent-manifest.json"

undefined

a365 setup --manifest-path "./agent-manifest.json"

undefined

2. Local Development

2. 本地开发

powershell

undefined

powershell

undefined

Start MCP server for testing

启动用于测试的MCP服务器

a365 develop start --server-path "./mcp-server" --port 5000

Test your agent locally with the MCP server

使用MCP服务器在本地测试你的代理

(Use your development framework here)

（此处使用你的开发框架）

Stop MCP server when done

完成后停止MCP服务器

a365 develop stop --server-id "server-123"

undefined

a365 develop stop --server-id "server-123"

undefined

3. Deploy to Azure

3. 部署到Azure

powershell

undefined

powershell

undefined

Build and deploy application

构建并部署应用

a365 deploy --project-path "./src/MyAgent365App"
--configuration "Release"
--update-permissions

Verify deployment

验证部署

az webapp show --name my-agent365-app --resource-group agent365-dev-rg

undefined

az webapp show --name my-agent365-app --resource-group agent365-dev-rg

undefined

4. Publish for Distribution

4. 发布用于分发

powershell

undefined

powershell

undefined

Package agent for Microsoft 365 Admin Center

打包代理以用于Microsoft 365管理中心

a365 publish --manifest-path "./agent-manifest.json"
--output-path "./dist"

Upload the generated package to Microsoft 365 Admin Center

将生成的包上传至Microsoft 365管理中心

Then hire the agent through Teams

然后通过Teams启用该代理

undefined

undefined

5. Query and Verify

5. 查询与验证

powershell

undefined

powershell

undefined

Check agent permissions and consent

检查代理权限和同意状态

a365 query-entra --agent-id $env:AGENT_BLUEPRINT_ID --check-consent

Export configuration for documentation

导出配置用于文档记录

a365 query-entra --agent-id $env:AGENT_BLUEPRINT_ID
--export-config "./docs/agent-config.json"

undefined

a365 query-entra --agent-id $env:AGENT_BLUEPRINT_ID
--export-config "./docs/agent-config.json"

undefined

C# Integration Example

C#集成示例

If you're building an Agent 365 application in C#:

csharp

using Microsoft.Agents.Core;
using Microsoft.Agents.Protocols.Adapter;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace MyAgent365App
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            var host = Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    // Register Agent 365 services
                    services.AddAgent365Services(options =>
                    {
                        options.ClientId = Environment.GetEnvironmentVariable("AGENT365_CLIENT_ID");
                        options.TenantId = Environment.GetEnvironmentVariable("AGENT365_TENANT_ID");
                        options.ManifestPath = "./agent-manifest.json";
                    });

                    // Register your agent handler
                    services.AddSingleton<IAgentHandler, MyAgentHandler>();
                })
                .Build();

            await host.RunAsync();
        }
    }

    public class MyAgentHandler : IAgentHandler
    {
        public async Task<AgentResponse> HandleMessageAsync(
            AgentRequest request, 
            CancellationToken cancellationToken)
        {
            // Process agent request
            var response = new AgentResponse
            {
                Text = $"Received: {request.Text}",
                SuggestedActions = new[]
                {
                    new AgentAction { Title = "Learn More", Value = "learn_more" }
                }
            };

            return response;
        }
    }
}

Deploy this application:

powershell

undefined

如果你使用C#构建Agent 365应用：

csharp

using Microsoft.Agents.Core;
using Microsoft.Agents.Protocols.Adapter;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace MyAgent365App
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            var host = Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    // 注册Agent 365服务
                    services.AddAgent365Services(options =>
                    {
                        options.ClientId = Environment.GetEnvironmentVariable("AGENT365_CLIENT_ID");
                        options.TenantId = Environment.GetEnvironmentVariable("AGENT365_TENANT_ID");
                        options.ManifestPath = "./agent-manifest.json";
                    });

                    // 注册你的代理处理器
                    services.AddSingleton<IAgentHandler, MyAgentHandler>();
                })
                .Build();

            await host.RunAsync();
        }
    }

    public class MyAgentHandler : IAgentHandler
    {
        public async Task<AgentResponse> HandleMessageAsync(
            AgentRequest request, 
            CancellationToken cancellationToken)
        {
            // 处理代理请求
            var response = new AgentResponse
            {
                Text = $"Received: {request.Text}",
                SuggestedActions = new[]
                {
                    new AgentAction { Title = "Learn More", Value = "learn_more" }
                }
            };

            return response;
        }
    }
}

部署此应用：

powershell

undefined

Deploy the C# application

部署C#应用

a365 deploy --project-path "./MyAgent365App"
--configuration "Release"
--runtime "win-x64"

undefined

a365 deploy --project-path "./MyAgent365App"
--configuration "Release"
--runtime "win-x64"

undefined

Environment Variables

环境变量

Set these environment variables for CLI authentication and configuration:

powershell

undefined

设置以下环境变量用于CLI身份验证和配置：

powershell

undefined

Required for authentication

身份验证必填

AGENT365_CLIENT_ID="your-entra-app-client-id" AGENT365_TENANT_ID="your-entra-tenant-id"

Optional for automation

自动化可选

AZURE_SUBSCRIPTION_ID="your-azure-subscription-id" AGENT365_RESOURCE_GROUP="agent365-rg" AGENT365_LOCATION="eastus" AGENT_BLUEPRINT_ID="your-agent-blueprint-id"

undefined

AZURE_SUBSCRIPTION_ID="your-azure-subscription-id" AGENT365_RESOURCE_GROUP="agent365-rg" AGENT365_LOCATION="eastus" AGENT_BLUEPRINT_ID="your-agent-blueprint-id"

undefined

Troubleshooting

故障排查

Authentication Issues

身份验证问题

Problem: "Authentication failed" or "Insufficient permissions"

Solution:

powershell

undefined

问题：“身份验证失败”或“权限不足”

解决方案：

powershell

undefined

Verify Entra ID app registration has delegated permissions

验证Entra ID应用注册是否具备委托权限

a365 query-entra --agent-id $env:AGENT_BLUEPRINT_ID --check-consent

Re-login if token expired

如果令牌过期，重新登录

az login --tenant $env:AGENT365_TENANT_ID

Verify environment variables

验证环境变量

echo $env:AGENT365_CLIENT_ID echo $env:AGENT365_TENANT_ID

undefined

echo $env:AGENT365_CLIENT_ID echo $env:AGENT365_TENANT_ID

undefined

Deployment Failures

部署失败

Problem: "Deployment failed" or "Resource not found"

Solution:

powershell

undefined

问题：“部署失败”或“资源未找到”

解决方案：

powershell

undefined

Verify configuration

验证配置

a365 config show

Check Azure resources exist

检查Azure资源是否存在

az group show --name agent365-rg az webapp show --name my-agent365-app --resource-group agent365-rg

Re-run setup if resources missing

如果资源缺失，重新运行设置

a365 setup --use-existing-resources

undefined

a365 setup --use-existing-resources

undefined

MCP Server Connection Issues

MCP服务器连接问题

Problem: "Cannot connect to MCP server"

Solution:

powershell

undefined

问题：“无法连接到MCP服务器”

解决方案：

powershell

undefined

Test MCP server connectivity

测试MCP服务器连通性

a365 develop test --server-url "http://localhost:5000"

Check server logs

查看服务器日志

a365 develop list

Restart MCP server

重启MCP服务器

a365 develop stop --server-id "server-123" a365 develop start --server-path "./mcp-server" --port 5000

undefined

a365 develop stop --server-id "server-123" a365 develop start --server-path "./mcp-server" --port 5000

undefined

Manifest Validation Errors

清单验证错误

Problem: "Invalid manifest" during publish

Solution:

powershell

undefined

问题：发布时出现“无效清单”

解决方案：

powershell

undefined

Validate manifest without packaging

仅验证清单不打包

a365 publish --manifest-path "./agent-manifest.json" --validate-only

Check manifest schema

检查清单架构

Ensure all required fields are present and valid

确保所有必填字段存在且有效

Verify icon files exist in specified paths

验证指定路径下的图标文件是否存在

undefined

undefined

Cleanup Issues

清理问题

Problem: "Cannot delete resources" or "Resources still in use"

Solution:

powershell

undefined

问题：“无法删除资源”或“资源仍在使用中”

解决方案：

powershell

undefined

Force cleanup (use with caution)

强制清理（谨慎使用）

a365 cleanup --force

Manual cleanup via Azure CLI

通过Azure CLI手动清理

az group delete --name agent365-rg --yes --no-wait

Remove only blueprint

仅移除蓝图

a365 cleanup --blueprint-only --agent-id $env:AGENT_BLUEPRINT_ID

undefined

a365 cleanup --blueprint-only --agent-id $env:AGENT_BLUEPRINT_ID

undefined

Best Practices

最佳实践

Use Configuration File: Store common settings with
```
a365 config set
```
to avoid repetitive parameters
Environment Variables: Use environment variables for sensitive data (client IDs, tenant IDs)
Version Control: Include
```
agent-manifest.json
```
in version control, exclude
```
config.json
```
Automated Pipelines: Use
```
--force
```
and
```
--no-wait
```
flags for CI/CD automation
Resource Naming: Use consistent naming conventions for Azure resources
Regular Cleanup: Remove unused resources to avoid Azure costs
Permission Audits: Regularly check consent status with
```
query-entra
```
command

使用配置文件：通过
```
a365 config set
```
存储常用设置，避免重复输入参数
环境变量：使用环境变量存储敏感数据（客户端ID、租户ID）
版本控制：将
```
agent-manifest.json
```
纳入版本控制，排除
```
config.json
```
自动化流水线：在CI/CD自动化中使用
```
--force
```
和
```
--no-wait
```
标志
资源命名：为Azure资源使用一致的命名规范
定期清理：移除未使用的资源以避免Azure成本浪费
权限审计：定期使用
```
query-entra
```
命令检查同意状态

microsoft-agent365-devtools-cli

Original

Translation

Microsoft Agent 365 DevTools CLI

Microsoft Agent 365 DevTools CLI

What It Does

功能介绍

Installation

安装步骤

Prerequisites

前置条件

Install from NuGet

从NuGet安装

Verify Installation

验证安装

Entra ID App Registration Setup

Entra ID应用注册设置

Windows PowerShell

Windows PowerShell

Linux/macOS

Linux/macOS

Key Commands

核心命令

Config Command

配置命令

Set Azure subscription

设置Azure订阅

Set resource group

设置资源组

Set Azure region

设置Azure区域

View current configuration

查看当前配置

Reset configuration

重置配置

Setup Command

设置命令

Interactive setup (recommended for first-time setup)

交互式设置（首次设置推荐使用）

Automated setup with parameters

参数化自动设置

Setup with existing resources

使用现有资源进行设置

Develop Command

开发命令

Start MCP server for development

启动用于开发的MCP服务器

List running MCP servers

列出运行中的MCP服务器

Stop MCP server

停止MCP服务器

Test MCP server connection

测试MCP服务器连接

Develop-MCP Command

Develop-MCP命令

Register MCP server in Dataverse

在Dataverse中注册MCP服务器

List MCP servers in environment

列出环境中的MCP服务器

Remove MCP server

移除MCP服务器

Deploy Command

部署命令

Deploy application binaries

部署应用程序二进制文件

Deploy with specific runtime

使用特定运行时部署

Deploy and update tool permissions

部署并更新工具权限

Publish Command

发布命令

Update manifest IDs and package

更新清单ID并打包

Publish with custom app package name

使用自定义应用包名称发布

Validate manifest only (no packaging)

仅验证清单（不打包）

Query-Entra Command

Query-Entra命令

Query agent scopes and permissions