Back to Details

mcp-create-declarative-agent

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
prompt
---
mode: 'agent'
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
description: 'Create a declarative agent for Microsoft 365 Copilot by integrating an MCP server with authentication, tool selection, and configuration'
model: 'gpt-4.1'
tags: [mcp, m365-copilot, declarative-agent, model-context-protocol, api-plugin]
---
prompt
---
mode: 'agent'
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
description: '通过集成带身份验证、工具选择和配置功能的MCP服务器，为Microsoft 365 Copilot创建Declarative Agent'
model: 'gpt-4.1'
tags: [mcp, m365-copilot, declarative-agent, model-context-protocol, api-plugin]
---

Create MCP-based Declarative Agent for Microsoft 365 Copilot

为Microsoft 365 Copilot创建基于MCP的Declarative Agent

Create a complete declarative agent for Microsoft 365 Copilot that integrates with a Model Context Protocol (MCP) server to access external systems and data.
创建一个完整的Microsoft 365 Copilot Declarative Agent，该Agent与Model Context Protocol (MCP)服务器集成，以访问外部系统和数据。

Requirements

需求

Generate the following project structure using Microsoft 365 Agents Toolkit:
使用Microsoft 365 Agents Toolkit生成以下项目结构：

Project Setup

项目设置

  1. Scaffold declarative agent via Agents Toolkit
  2. Add MCP action pointing to MCP server
  3. Select tools to import from MCP server
  4. Configure authentication (OAuth 2.0 or SSO)
  5. Review generated files (manifest.json, ai-plugin.json, declarativeAgent.json)
  1. 通过Agents Toolkit搭建Declarative Agent脚手架
  2. 添加指向MCP服务器的MCP动作
  3. 选择从MCP服务器导入的工具
  4. 配置身份验证（OAuth 2.0或SSO）
  5. 审查生成的文件（manifest.json、ai-plugin.json、declarativeAgent.json）

Key Files Generated

生成的关键文件

appPackage/manifest.json - Teams app manifest with plugin reference:
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 definition:
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 plugin 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 server configuration:
json
{
  "serverUrl": "https://api.service.com/mcp/",
  "pluginFilePath": "appPackage/ai-plugin.json"
}
appPackage/manifest.json - 包含插件引用的Teams应用清单：
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插件清单：
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 Server Integration

MCP服务器集成

Supported MCP Endpoints

支持的MCP端点

The MCP server must provide:
  • Server metadata endpoint
  • Tools listing endpoint (exposes available functions)
  • Tool execution endpoint (handles function calls)
MCP服务器必须提供：
  • 服务器元数据端点
  • 工具列表端点（暴露可用函数）
  • 工具执行端点（处理函数调用）

Tool Selection

工具选择

When importing from MCP:
  1. Fetch available tools from server
  2. Select specific tools to include (for security/simplicity)
  3. Tool definitions are auto-generated in ai-plugin.json
从MCP导入时：
  1. 从服务器获取可用工具
  2. 选择要包含的特定工具（出于安全/简化考虑）
  3. 工具定义会自动生成到ai-plugin.json中

Authentication Types

身份验证类型

OAuth 2.0 (Static Registration)
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"
}
Single Sign-On (SSO)
json
"auth": {
  "type": "SSO"
}
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

响应语义

Define Data Mapping

定义数据映射

Use 
response_semantics
to extract relevant fields from API responses:
json
"capabilities": {
  "response_semantics": {
    "data_path": "$.results",
    "properties": {
      "title": "$.name",
      "subtitle": "$.description",
      "url": "$.link"
    }
  }
}
使用
response_semantics
从API响应中提取相关字段：
json
"capabilities": {
  "response_semantics": {
    "data_path": "$.results",
    "properties": {
      "title": "$.name",
      "subtitle": "$.description",
      "url": "$.link"
    }
  }
}

Add Adaptive Cards (Optional)

添加自适应卡片（可选）

See the 
mcp-create-adaptive-cards
prompt for adding visual card templates.
如需添加可视化卡片模板，请查看
mcp-create-adaptive-cards
提示。

Environment Configuration

环境配置

Create 
.env.local
or 
.env.dev
for credentials:
env
OAUTH_REFERENCE_ID=your-oauth-reference-id
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
创建
.env.local
或
.env.dev
文件存储凭据：
env
OAUTH_REFERENCE_ID=your-oauth-reference-id
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret

Testing & Deployment

测试与部署

Local Testing

本地测试

  1. Provision agent in Agents Toolkit
  2. Start debugging to sideload in Teams
  3. Test in Microsoft 365 Copilot at https://m365.cloud.microsoft/chat
  4. Authenticate when prompted
  5. Query the agent using natural language
  1. 在Agents Toolkit中预配Agent
  2. 启动调试以在Teams中侧载
  3. 在https://m365.cloud.microsoft/chat的Microsoft 365 Copilot中进行测试
  4. 出现提示时进行身份验证
  5. 使用自然语言向Agent发起查询

Validation

验证

  • Verify tool imports in ai-plugin.json
  • Check authentication configuration
  • Test each exposed function
  • Validate response data mapping
  • 验证ai-plugin.json中的工具导入
  • 检查身份验证配置
  • 测试每个暴露的函数
  • 验证响应数据映射

Best Practices

最佳实践

Tool Design

工具设计

  • Focused functions: Each tool should do one thing well
  • Clear descriptions: Help the model understand when to use each tool
  • Minimal scoping: Only import tools the agent needs
  • Descriptive names: Use action-oriented function names
  • 聚焦功能：每个工具应专注完成一件事
  • 清晰描述：帮助模型理解何时使用每个工具
  • 最小范围：仅导入Agent所需的工具
  • 描述性名称：使用面向动作的函数名称

Security

安全

  • Use OAuth 2.0 for production scenarios
  • Store secrets in environment variables
  • Validate inputs on the MCP server side
  • Limit scopes to minimum required permissions
  • Use reference IDs for OAuth registration
  • 生产场景使用OAuth 2.0
  • 将密钥存储在环境变量中
  • 在MCP服务器端验证输入
  • 将权限范围限制为最低必要权限
  • 使用引用ID进行OAuth注册

Instructions

指令

  • Be specific about the agent's purpose and capabilities
  • Define behavior for both successful and error scenarios
  • Reference tools explicitly in instructions when applicable
  • Set expectations for users about what the agent can/cannot do
  • 明确具体：说明Agent的用途和能力
  • 定义行为：涵盖成功和错误场景的行为
  • 必要时在指令中明确引用工具
  • 为用户设定预期：说明Agent能做什么和不能做什么

Performance

性能

  • Cache responses when appropriate on MCP server
  • Batch operations where possible
  • Set timeouts for long-running operations
  • Paginate results for large datasets
  • 在MCP服务器上适当缓存响应
  • 尽可能批量操作
  • 为长时间运行的操作设置超时
  • 对大型数据集进行分页

Common MCP Server Examples

常见MCP服务器示例

GitHub MCP Server

GitHub MCP服务器

URL: https://api.githubcopilot.com/mcp/
Tools: search_repositories, search_users, get_repository
Auth: OAuth 2.0
URL: https://api.githubcopilot.com/mcp/
Tools: search_repositories, search_users, get_repository
Auth: OAuth 2.0

Jira MCP Server

Jira MCP服务器

URL: https://your-domain.atlassian.net/mcp/
Tools: search_issues, create_issue, update_issue
Auth: OAuth 2.0
URL: https://your-domain.atlassian.net/mcp/
Tools: search_issues, create_issue, update_issue
Auth: OAuth 2.0

Custom Service

自定义服务

URL: https://api.your-service.com/mcp/
Tools: Custom tools exposed by your service
Auth: OAuth 2.0 or SSO
URL: https://api.your-service.com/mcp/
Tools: 自定义服务暴露的工具
Auth: OAuth 2.0或SSO

Workflow

工作流程

Ask the user:
  1. What MCP server are you integrating with (URL)?
  2. What tools should be exposed to Copilot?
  3. What authentication method does the server support?
  4. What should the agent's primary purpose be?
  5. Do you need response semantics or Adaptive Cards?
Then generate:
  • Complete appPackage/ structure (manifest.json, declarativeAgent.json, ai-plugin.json)
  • mcp.json configuration
  • .env.local template
  • Provisioning and testing instructions
询问用户：
  1. 你要集成的MCP服务器是什么（URL）？
  2. 要向Copilot暴露哪些工具？
  3. 服务器支持哪种身份验证方法？
  4. Agent的主要用途是什么？
  5. 是否需要响应语义或自适应卡片？
然后生成：
  • 完整的appPackage/结构（manifest.json、declarativeAgent.json、ai-plugin.json）
  • mcp.json配置
  • .env.local模板
  • 预配和测试说明

Troubleshooting

故障排除

MCP Server Not Responding

MCP服务器无响应

  • Verify server URL is correct
  • Check network connectivity
  • Validate MCP server implements required endpoints
  • 验证服务器URL是否正确
  • 检查网络连接
  • 验证MCP服务器是否实现了所需的端点

Authentication Fails

身份验证失败

  • Verify OAuth credentials are correct
  • Check reference ID matches registration
  • Confirm scopes are requested properly
  • Test OAuth flow independently
  • 验证OAuth凭据是否正确
  • 检查引用ID是否与注册匹配
  • 确认权限范围请求正确
  • 独立测试OAuth流程

Tools Not Appearing

工具未显示

  • Ensure mcp.json points to correct server
  • Verify tools were selected during import
  • Check ai-plugin.json has correct function definitions
  • Re-fetch actions from MCP if server changed
  • 确保mcp.json指向正确的服务器
  • 验证导入期间是否选择了工具
  • 检查ai-plugin.json是否有正确的函数定义
  • 如果服务器有更改，重新从MCP获取动作

Agent Not Understanding Queries

Agent无法理解查询

  • Review instructions in declarativeAgent.json
  • Check function descriptions are clear
  • Verify response_semantics extract correct data
  • Test with more specific queries
undefined
  • 查看declarativeAgent.json中的指令
  • 检查函数描述是否清晰
  • 验证response_semantics是否提取了正确的数据
  • 使用更具体的查询进行测试
undefined