mcp-create-declarative-agent

---
mode: 'agent'
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
description: '通过集成 MCP 服务端（含身份验证、工具选择与相关配置），为 Microsoft 365 Copilot 创建声明式 Agent'
model: 'gpt-4.1'
tags: [mcp, m365-copilot, declarative-agent, model-context-protocol, api-plugin]
---

# 为 Microsoft 365 Copilot 创建基于 MCP 的声明式 Agent

为 Microsoft 365 Copilot 创建一个完整的声明式 Agent，通过与 Model Context Protocol (MCP) 服务端集成，使其能够访问外部系统与数据。

## 需求说明

使用 Microsoft 365 Agents Toolkit 生成以下项目结构：

### 项目搭建
1. 通过 Agents Toolkit **脚手架生成声明式 Agent**
2. **添加 MCP 操作（Action）** 并指向 MCP 服务端
3. 从 MCP 服务端中**选择要导入的工具**
4. **配置身份验证**（OAuth 2.0 或 SSO）
5. **检查生成的文件**（manifest.json、ai-plugin.json、declarativeAgent.json）

### 生成的核心文件

**appPackage/manifest.json** - 包含插件引用的 Teams 应用 Manifest 清单文件：
```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
  "manifestVersion": "devPreview",
  "version": "1.0.0",
  "id": "...",
  "developer": {
    "name": "...",
    "websiteUrl": "...",
    "privacyUrl": "...",
    "termsOfUseUrl": "..."
  },
  "name": {
    "short": "Agent Name",
    "full": "Full Agent Name"
  },
  "description": {
    "short": "Short description",
    "full": "Full description"
  },
  "copilotAgents": {
    "declarativeAgents": [
      {
        "id": "declarativeAgent",
        "file": "declarativeAgent.json"
      }
    ]
  }
}
```

**appPackage/declarativeAgent.json** - Agent 定义文件：
```json
{
  "$schema": "https://aka.ms/json-schemas/copilot/declarative-agent/v1.0/schema.json",
  "version": "v1.0",
  "name": "Agent Name",
  "description": "Agent description",
  "instructions": "You are an assistant that helps with [specific domain]. Use the available tools to [capabilities].",
  "capabilities": [
    {
      "name": "WebSearch",
      "websites": [
        {
          "url": "https://learn.microsoft.com"
        }
      ]
    },
    {
      "name": "MCP",
      "file": "ai-plugin.json"
    }
  ]
}
```

**appPackage/ai-plugin.json** - MCP 插件 Manifest 清单文件：
```json
{
  "schema_version": "v2.1",
  "name_for_human": "Service Name",
  "description_for_human": "Description for users",
  "description_for_model": "Description for AI model",
  "contact_email": "support@company.com",
  "namespace": "serviceName",
  "capabilities": {
    "conversation_starters": [
      {
        "text": "Example query 1"
      }
    ]
  },
  "functions": [
    {
      "name": "functionName",
      "description": "Function description",
      "capabilities": {
        "response_semantics": {
          "data_path": "$",
          "properties": {
            "title": "$.title",
            "subtitle": "$.description"
          }
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "MCP",
      "spec": {
        "url": "https://api.service.com/mcp/"
      },
      "run_for_functions": ["functionName"],
      "auth": {
        "type": "OAuthPluginVault",
        "reference_id": "${{OAUTH_REFERENCE_ID}}"
      }
    }
  ]
}
```

**/.vscode/mcp.json** - MCP 服务端配置文件：
```json
{
  "serverUrl": "https://api.service.com/mcp/",
  "pluginFilePath": "appPackage/ai-plugin.json"
}
```

## MCP 服务端集成

### 支持的 MCP 端点
MCP 服务端必须提供：
- **服务端元数据（Server metadata）** 端点
- **工具列表（Tools listing）** 端点（暴露可用函数）
- **工具执行（Tool execution）** 端点（处理函数调用）

### 工具选择
从 MCP 导入工具时：
1. 从服务端获取可用工具列表
2. 选择要包含的具体工具（出于安全性与简洁性考虑）
3. 工具定义会自动生成在 ai-plugin.json 中

### 身份验证类型

**OAuth 2.0（静态注册）**
```json
"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "${{OAUTH_REFERENCE_ID}}",
  "authorization_url": "https://auth.service.com/authorize",
  "client_id": "${{CLIENT_ID}}",
  "client_secret": "${{CLIENT_SECRET}}",
  "scope": "read write"
}
```

**单点登录（SSO）**
```json
"auth": {
  "type": "SSO"
}
```

## 响应语义（Response Semantics）

### 定义数据映射
使用 `response_semantics` 从 API 响应中提取关键字段：

```json
"capabilities": {
  "response_semantics": {
    "data_path": "$.results",
    "properties": {
      "title": "$.name",
      "subtitle": "$.description",
      "url": "$.link"
    }
  }
}
```

### 添加自适应卡片（可选）
参考 `mcp-create-adaptive-cards` Prompt 来添加可视化卡片模板。

## 环境配置

创建 `.env.local` 或 `.env.dev` 保存凭据密钥：

```env
OAUTH_REFERENCE_ID=your-oauth-reference-id
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
```

## 测试与部署

### 本地测试
1. 在 Agents Toolkit 中**准备（Provision）** Agent
2. **启动调试**将其预装（Sideload）到 Teams
3. 在 Microsoft 365 Copilot (https://m365.cloud.microsoft/chat) 中进行测试
4. 根据提示完成身份验证
5. 使用自然语言向 Agent 发起提问

### 验证步骤
- 检查 ai-plugin.json 中的工具导入是否正确
- 检查身份验证配置
- 测试每个暴露的函数
- 验证响应数据的映射结果

## 最佳实践

### 工具设计
- **功能单一聚焦**：每个工具只做好一件事
- **描述清晰明确**：帮助模型准确理解何时使用该工具
- **最小化作用域**：仅导入 Agent 确实需要的工具
- **名称具象化**：使用动词导向的函数命名

### 安全性
- 生产环境场景推荐**使用 OAuth 2.0**
- 将敏感信息**存入环境变量**
- 在 MCP 服务端做好**输入校验**
- 严格**限制 Scope 权限**至最低所需级别
- 在 OAuth 注册中**使用 Reference ID**

### Prompt / 指令编写
- **明确定义** Agent 的定位与能力边界
- **规范行为逻辑**：清晰定义成功与异常情况下的处理机制
- **显式引用工具**：在指令中适时指明对应工具
- **合理引导预期**：让用户明确该 Agent 能做什么、不能做什么

### 性能优化
- 在 MCP 服务端对合适的数据**做响应缓存**
- 尽可能采用**批量操作**
- 为耗时较长的操作**设置超时时间**
- 大数据集查询**引入分页机制**

## 常用 MCP 服务端示例

### GitHub MCP 服务端
```
URL: https://api.githubcopilot.com/mcp/
工具: search_repositories, search_users, get_repository
身份验证: OAuth 2.0
```

### Jira MCP 服务端
```
URL: https://your-domain.atlassian.net/mcp/
工具: search_issues, create_issue, update_issue
身份验证: OAuth 2.0
```

### 自定义服务
```
URL: https://api.your-service.com/mcp/
工具: 自定义服务暴露的工具
身份验证: OAuth 2.0 或 SSO
```

## 执行流程 (Workflow)

询问用户以下问题：
1. 您打算集成哪个 MCP 服务端（URL 是什么）？
2. 需要向 Copilot 暴露哪些工具？
3. 该服务端支持哪种身份验证方式？
4. 该 Agent 的核心用途是什么？
5. 是否需要响应语义（Response Semantics）或自适应卡片（Adaptive Cards）？

然后生成：
- 完整的 appPackage/ 目录结构（manifest.json、declarativeAgent.json、ai-plugin.json）
- mcp.json 配置文件
- .env.local 模板
- 资源准备与测试指南

## 常见问题排查 (Troubleshooting)

### MCP 服务端无响应
- 确认服务端 URL 是否正确
- 检查网络连通性
- 验证 MCP 服务端是否实现了所需的端点

### 身份验证失败
- 检查 OAuth 密钥是否正确
- 确认 reference ID 与注册信息保持一致
- 确认请求的 Scope 范围无误
- 独立测试 OAuth 授权流程

### 工具未显示
- 确保 mcp.json 指向正确的服务端
- 确认导入过程中勾选了对应工具
- 检查 ai-plugin.json 中的函数定义是否正确
- 如果服务端有变动，尝试从 MCP 重新拉取 Actions

### Agent 无法理解查询
- 检查 declarativeAgent.json 中的 instructions 指令
- 确认函数 descriptions 是否描述清晰
- 检查 response_semantics 数据提取逻辑是否准确
- 尝试使用更为具体的问法进行测试