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（Declarative Agent），透過整合 Model Context Protocol (MCP) 伺服器來存取外部系統與資料。

## 需求

使用 Microsoft 365 Agents Toolkit 產生以下專案結構：

### 專案設定
1. **透過 Agents Toolkit 建立宣告式 Agent 骨架**
2. **新增指向 MCP 伺服器的 MCP Action**
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"
    }
  }
}
```

### 新增 Adaptive Cards（選擇性）
關於新增視覺化卡片範本，請參閱 `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 中完成 Agent 的 **Provision (佈署準備)**
2. **啟動偵錯**以旁載 (sideload) 至 Teams
3. 前往 https://m365.cloud.microsoft/chat 在 Microsoft 365 Copilot 中進行測試
4. 在跳出提示時完成身份驗證
5. 使用自然語言向 Agent 發問

### 驗證
- 驗證 ai-plugin.json 中的工具匯入
- 檢查身份驗證設定
- 測試每個公開的函式
- 驗證回應資料的對應

## 最佳實踐

### 工具設計
- **專一的函式**：每個工具應該專注做好一件事
- **清晰的描述**：協助模型理解何時該使用各個工具
- **最小化範圍**：僅匯入 Agent 所需的工具
- **具描述性的名稱**：使用以動作為導向的函式名稱

### 安全性
- 在正式環境情境中**使用 OAuth 2.0**
- 將機密資訊**儲存在環境變數中**
- 在 MCP 伺服器端**驗證輸入資料**
- 將權限範圍 (Scope) **限制在所需的最小權限**
- 在 OAuth 註冊中**使用參考 ID (Reference ID)**

### 指示 (Instructions)
- 對 Agent 的用途與能力做**具體明確的說明**
- 針對成功與錯誤情境**定義明確的行為邏輯**
- 適當時在指示中**明確引用工具**
- 為使用者**建立合理預期**，說明 Agent 能做與不能做的事

### 效能
- 適當時在 MCP 伺服器端**快取回應**
- 盡可能採用**批次作業**
- 針對長時間執行的作業**設定逾時機制**
- 針對大型資料集進行**結果分頁**

## 常見 MCP 伺服器範例

### GitHub MCP 伺服器
```
URL: https://api.githubcopilot.com/mcp/
Tools: search_repositories, search_users, get_repository
Auth: OAuth 2.0
```

### Jira MCP 伺服器
```
URL: https://your-domain.atlassian.net/mcp/
Tools: search_issues, create_issue, update_issue
Auth: OAuth 2.0
```

### 自訂服務
```
URL: https://api.your-service.com/mcp/
Tools: 由您的服務公開的自訂工具
Auth: OAuth 2.0 或 SSO
```

## 工作流程

詢問使用者：
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 範本
- Provision 佈署與測試說明

## 疑難排解

### MCP 伺服器無回應
- 確認伺服器 URL 是否正確
- 檢查網路連線狀態
- 驗證 MCP 伺服器是否已實作必要的端點

### 身份驗證失敗
- 確認 OAuth 憑證是否正確
- 檢查參考 ID (Reference ID) 是否與註冊資訊相符
- 確認權限範圍 (Scope) 請求是否正確
- 獨立測試 OAuth 流程

### 工具未顯示
- 確保 mcp.json 指向正確的伺服器
- 驗證匯入過程中是否已選取工具
- 檢查 ai-plugin.json 是否包含正確的函式定義
- 若伺服器有所變更，請從 MCP 重新擷取 Action

### Agent 無法理解查詢
- 檢視 declarativeAgent.json 中的 instructions 指示
- 檢查函式描述是否足夠清晰
- 驗證 response_semantics 是否有擷取出正確的資料
- 使用更具體明確的查詢語句進行測試