Microsoft 365 声明式 Agent 开发完全指南：基于 Schema v1.5、TypeSpec 与 Agents Toolkit 的三工作流实战

Microsoft 365 声明式 Agent 开发完全指南基于 Schema v1.5、TypeSpec 与 Agents Toolkit 的三工作流实战【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot导读本指南以 awesome-copilot 仓库中的 declarative-agents 技能 为核心骨架系统讲解 Microsoft 365 Copilot 声明式 AgentDeclarative Agent的完整开发流程从基础创建、企业级设计到验证优化的三大工作流再到 v1.5 JSON Schema 的字段约束、11 种可用能力Capability、TypeSpec 类型安全定义、Microsoft 365 Agents Toolkit 集成与 Agents Playground 本地测试。读完本文你将掌握如何独立产出合规的 agent 清单文件manifest、用 TypeSpec 编译出 JSON 定义、配置开发/生产环境变量并对既有 Agent 做 Schema 合规校验与性能优化。一、声明式 Agent 是什么三种工作流的总览Microsoft 365 Copilot 声明式 Agent 是扩展 Microsoft 365 Copilot 的自定义 AI 助手通过声明式的 JSON 清单描述它是什么、能做什么、怎么回复无需编写传统 bot 逻辑。在本仓库中该能力被封装为 skills/declarative-agents/SKILL.md 与配套的 declarative-agents-microsoft365 开发指南并遵循最新的v1.5 Schema 规范。配套的 Declarative Agents Architect Agent 将完整开发周期划分为三个典型工作流对应不同阶段的开发者工作流 1基础 Agent 创建Basic Agent Creation适用人群新手开发者、简单 Agent、快速原型验证。该工作流覆盖Agent 规划定义用途、目标用户与核心能力能力选择从 11 种可用能力中挑选WebSearch、OneDriveAndSharePoint、GraphConnectors 等基础 Schema 创建生成合规的 JSON 清单并满足字段约束TypeSpec 替代方案创建可编译为 JSON 的现代类型安全定义测试环境搭建配置 Agents Playground 进行本地测试工具包集成借助 Microsoft 365 Agents Toolkit 增强开发体验。工作流 2企业级高级 Agent 设计Advanced Enterprise Agent Design适用人群复杂企业场景、生产部署、高级功能需求。该工作流聚焦企业需求分析多租户考量、合规性、安全性高级能力配置复杂能力组合与交互设计行为覆盖实现自定义回复模式与专业化行为本地化策略多语言支持与资源管理对话引导Conversation Starters设计策略性对话入口提升用户参与度生产部署环境管理、版本化与生命周期规划监控与分析埋点实现与性能优化。工作流 3验证与优化Validation Optimization适用人群已有 Agent、问题排查、性能优化。该工作流执行Schema 合规验证全面检查 v1.5 规范符合度字符数限制优化name100、description1000、instructions8000能力审计验证能力配置与使用是否正确TypeSpec 迁移将现有 JSON 转换为 TypeSpec 定义测试协议使用 Agents Playground 进行全面验证性能分析识别瓶颈与优化机会最佳实践评审对照 Microsoft 指南与建议逐项检查。二、JSON Schema v1.5字段约束与核心属性无论选择哪条工作流Agent 的最终落地都依赖一份符合 v1.5 规范的 JSON 清单。根据 开发指南核心属性如下{ $schema: https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json, version: v1.5, name: string (max 100 characters), description: string (max 1000 characters), instructions: string (max 8000 characters), capabilities: [array (max 5 items)], conversation_starters: [array (max 4 items, optional)] }字符限制与数组约束字段约束必填name最多 100 字符是description最多 1000 字符是instructions最多 8000 字符是capabilities最少 1 项、最多 5 项是conversation_starters最多 4 项否这些约束同样体现在 TypeSpec 定义中见 TypeSpec 指南并通过maxLength、minLength、minItems、maxItems装饰器在编译期强制校验。三、11 种可用能力Capability详解与选型策略SKILL 文档明确列出 11 种能力每次最多选择 5 种。选型策略应遵循最小够用原则避免过度授权。核心能力Core CapabilitiesWebSearch互联网搜索与实时信息获取OneDriveAndSharePoint文件访问、文档搜索、内容管理GraphConnectors从第三方系统集成企业数据Copilot Connector 内容MicrosoftGraph访问 Microsoft 365 服务与数据。沟通与协作Communication CollaborationTeamsAndOutlookTeams 聊天、会议、邮件集成CopilotForMicrosoft365高级 Copilot 特性与工作流。业务应用Business ApplicationsPowerPlatformPower Apps、Power Automate、Power BI 集成BusinessDataProcessing高级数据分析与处理WordAndExcel文档创建、编辑、分析EnterpriseApplications第三方业务系统集成CustomConnectors自定义 API 与服务集成。能力作用域Scoping最佳实践TypeSpec 开发指南 特别强调始终尽可能将能力限定到具体资源即对能力进行作用域限制。例如// Web Search限定到指定站点 op webSearch is AgentCapabilities.WebSearchSites [ { url: https://learn.microsoft.com }, { url: https://docs.microsoft.com } ]; // OneDrive and SharePoint限定到指定站点 op oneDriveAndSharePoint is AgentCapabilities.OneDriveAndSharePoint ItemsByUrl [ { url: https://contoso.sharepoint.com/sites/Engineering } ] ; // Email限定到指定文件夹可指定共享邮箱 op email is AgentCapabilities.Email Folders [ { folderId: Inbox }, { folderId: SentItems } ], SharedMailbox supportcontoso.com // 可选 ; // Dataverse限定到指定表 op dataverse is AgentCapabilities.Dataverse KnowledgeSources [ { hostName: contoso.crm.dynamics.com; tables: [ { tableName: account }, { tableName: contact } ]; } ] ;选型策略要点先以 1-2 个核心能力起步根据用户反馈增量添加对每种能力组合做充分测试企业级场景需评估合规与安全影响详见 Architect Agent。四、TypeSpec 开发从声明式定义到 JSON 清单TypeSpec 提供类型安全、可编译的现代开发方式。SKILL 文档给出简洁的模型示例// Modern declarative agent definition model MyAgent { name: string; description: string; instructions: string; capabilities: AgentCapability[]; conversation_starters?: ConversationStarter[]; }而 开发指南 提供了完整的、带约束装饰器的 TypeSpec 定义import typespec/json-schema; using TypeSpec.JsonSchema; jsonSchema(/schemas/declarative-agent/v1.5/schema.json) namespace DeclarativeAgent; /** Microsoft 365 Declarative Agent */ model Agent { /** Schema version */ minLength(1) $schema: https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json; /** Agent version */ version: v1.5; /** Agent name (max 100 characters) */ maxLength(100) minLength(1) name: string; /** Agent description (max 1000 characters) */ maxLength(1000) minLength(1) description: string; /** Agent instructions (max 8000 characters) */ maxLength(8000) minLength(1) instructions: string; /** Agent capabilities (1-5 items) */ minItems(1) maxItems(5) capabilities: AgentCapability[]; /** Conversation starters (max 4 items) */ maxItems(4) conversation_starters?: ConversationStarter[]; } /** Available agent capabilities */ union AgentCapability { WebSearch, OneDriveAndSharePoint, GraphConnectors, MicrosoftGraph, TeamsAndOutlook, PowerPlatform, BusinessDataProcessing, WordAndExcel, CopilotForMicrosoft365, EnterpriseApplications, CustomConnectors } /** Conversation starter definition */ model ConversationStarter { /** Starter text (max 100 characters) */ maxLength(100) minLength(1) text: string; }编译为 JSON 清单tsp compile agent.tsp --emittypespec/json-schemaTypeSpec 声明式开发的最佳实践仓库中的 typespec-create-agent 技能 与 TypeSpec 开发指南 提供了更贴近实际使用的agent/instructions/conversationStarter装饰器风格import typespec/http; import typespec/openapi3; import microsoft/typespec-m365-copilot; using TypeSpec.Http; using TypeSpec.M365.Copilot.Agents; agent({ name: [Agent Name], description: [Agent Description] }) instructions( [Detailed instructions about agent behavior, role, and guidelines] ) conversationStarter(#{ title: [Starter Title 1], text: [Example query 1] }) conversationStarter(#{ title: [Starter Title 2], text: [Example query 2] }) namespace [AgentName] { // Add capabilities as operations here op capabilityName is AgentCapabilities.[CapabilityType][Parameters]; }编写要点命名使用描述角色与职能的名称如 Customer Support Assistant、Research Helper避免 Helper、Bot 这类泛化命名指令Instructions以第二人称You are...撰写明确专业领域、职责清单、行为准则同时写明不应做什么控制在 8000 字符内多行文本使用三引号字符串对话引导Conversation Starters提供 2-4 条每条包含标题与示例查询标题用动作导向如 Check Status查询示例要真实具体且尽量展示不同能力能力只声明 Agent 真正需要的能力并尽量做作用域限定URL、文件夹、表名等以提升性能与安全。五、Microsoft 365 Agents Toolkit 集成与环境管理VS Code 扩展安装使用 Agents Toolkit 前需安装 VS Code 扩展扩展 ID 为teamsdevapp.ms-teams-vscode-extension见 SKILL 文档 与 开发指南。环境变量支持SKILL 文档强调环境变量机制允许同一份清单在不同环境中复用{ name: ${AGENT_NAME}, description: ${AGENT_DESCRIPTION}, instructions: ${AGENT_INSTRUCTIONS} }开发指南进一步给出开发/生产两套环境配置模式// 开发环境 { name: ${DEV_AGENT_NAME}, description: Development version: ${AGENT_DESCRIPTION}, instructions: ${AGENT_INSTRUCTIONS}, capabilities: [${REQUIRED_CAPABILITIES}] }// 生产环境 { name: ${PROD_AGENT_NAME}, description: ${AGENT_DESCRIPTION}, instructions: ${AGENT_INSTRUCTIONS}, capabilities: [${PRODUCTION_CAPABILITIES}] }环境晋升策略开发环境Development完整调试能力、详细日志预发环境Staging生产级测试、性能监控生产环境Production性能优化、最小化日志。六、Agents Playground 本地测试启动本地测试环境npm install -g microsoft/agents-playground agents-playground start --manifest./agent.json测试场景能力验证逐一测试声明的每种能力对话流验证校验对话引导conversation starters是否按预期触发错误处理测试无效输入与边界情况性能测量记录响应时间与可靠性。验证辅助函数开发指南还提供了字符限制的校验辅助函数可用于 CI 或构建期检查function validateName(name: string): boolean { return name.length 0 name.length 100; } function validateDescription(description: string): boolean { return description.length 0 description.length 1000; } function validateInstructions(instructions: string): boolean { return instructions.length 0 instructions.length 8000; }七、高级特性行为覆盖、本地化与版本管理行为覆盖Behavior Overrides通过指令与行为覆盖字段塑造专业化的回复风格{ instructions: You are a specialized financial analyst agent. Always provide disclaimers for financial advice., behavior_overrides: { response_tone: professional, max_response_length: 2000, citation_requirements: true } }本地化Localization{ name: { en-US: Financial Assistant, es-ES: Asistente Financiero, fr-FR: Assistant Financier }, description: { en-US: Provides financial analysis and insights, es-ES: Proporciona análisis e insights financieros, fr-FR: Fournit des analyses et insights financiers } }版本管理与元数据{ name: MyAgent v1.2.0, description: Production agent with enhanced capabilities, version: v1.5, metadata: { version: 1.2.0, build: 20241208.1, environment: production } }开发生命周期八、MCP 服务器集成为声明式 Agent 接入外部系统若 Agent 需要访问外部系统可走 mcp-create-declarative-agent 技能 描述的 MCP 集成路线通过 Agents Toolkit 脚手架声明式 Agent添加指向 MCP 服务器的 action导入工具并配置认证。其典型生成文件包括appPackage/manifest.jsonTeams 应用清单通过copilotAgents.declarativeAgents引用声明式 Agent 文件appPackage/declarativeAgent.jsonAgent 定义其中capabilities可声明WebSearch可带websites作用域与MCP类型能力指向ai-plugin.jsonappPackage/ai-plugin.jsonMCP 插件清单schema_version: v2.1声明函数列表、runtimestype 为MCP含服务 URL与auth配置/.vscode/mcp.jsonMCP 服务器配置serverUrl与插件文件路径。认证支持两种模式// OAuth 2.0静态注册 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 auth: { type: SSO }凭据通过.env.local/.env.dev管理如OAUTH_REFERENCE_ID、CLIENT_ID、CLIENT_SECRET生产场景应优先 OAuth 2.0 并以最小权限范围授权。九、监控、安全与合规监控指标每种能力的响应时间对话引导的用户参与度错误率与失败模式能力利用率统计。结构化日志示例const log { timestamp: new Date().toISOString(), agentName: MyAgent, version: 1.2.0, userId: user123, capability: WebSearch, responseTime: 1250, success: true };安全与合规要点敏感信息处理得当符合 GDPR、CCPA 及组织策略对企业能力使用适当的访问控制校验所有输入与输出实施限流与滥用防护监控可疑活动模式定期安全审计与更新。常见问题排查Schema 校验错误检查字符限制与必填字段能力冲突确认能力组合受支持性能问题监控响应时间并优化指令部署失败校验环境配置与权限。常用调试工具TypeSpec 编译器诊断、Agents Playground 调试、Agents Toolkit 日志、Schema 校验工具。十、快速上手路径结合本仓库资源推荐的上手路径如下明确 Agent 的目标用户与核心能力参考 Architect Agent 的需求分析方法按 SKILL 工作流 1 完成基础规划与能力选择11 选最多 5用 TypeSpec 模板 生成main.tsp编译产出 JSON 清单按 开发指南 校验字符限制与数组约束使用 Agents Playground 本地测试能力、对话流、错误处理、性能通过 Agents Toolkit 配置开发/预发/生产环境并部署如需外部系统按 MCP 集成技能 接入并配置认证。以上每条路径都可在本仓库的对应文档与技能中找到可直接复用的模板与示例是你在 Microsoft 365 Copilot 上交付生产级声明式 Agent 的完整参考。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考