{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"declarative-agents-microsoft365","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: Comprehensive development guidelines for Microsoft 365 Copilot declarative agents with schema v1.5, TypeSpec integration, and Microsoft 365 Agents Toolkit workflows\napplyTo: \"**.json, **.ts, **.tsp, **manifest.json, **agent.json, **declarative-agent.json\"\n---\n\n# Microsoft 365 Declarative Agents Development Guidelines\n\n## Overview\n\nMicrosoft 365 Copilot declarative agents are powerful custom AI assistants that extend Microsoft 365 Copilot with specialized capabilities, enterprise data access, and custom behaviors. These guidelines provide comprehensive development practices for creating production-ready agents using the latest v1.5 JSON schema specification with full Microsoft 365 Agents Toolkit integration.\n\n## Schema Specification v1.5\n\n### Core Properties\n\n```json\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json\",\n  \"version\": \"v1.5\",\n  \"name\": \"string (max 100 characters)\",\n  \"description\": \"string (max 1000 characters)\", \n  \"instructions\": \"string (max 8000 characters)\",\n  \"capabilities\": [\"array (max 5 items)\"],\n  \"conversation_starters\": [\"array (max 4 items, optional)\"]\n}\n```\n\n### Character Limits \u0026 Constraints\n- **Name**: Maximum 100 characters, required\n- **Description**: Maximum 1000 characters, required  \n- **Instructions**: Maximum 8000 characters, required\n- **Capabilities**: Maximum 5 items, minimum 1 item\n- **Conversation Starters**: Maximum 4 items, optional\n\n## Available Capabilities\n\n### Core Capabilities\n1. **WebSearch**: Internet search and real-time information access\n2. **OneDriveAndSharePoint**: File access, document search, content management\n3. **GraphConnectors**: Enterprise data integration from third-party systems\n4. **MicrosoftGraph**: Access to Microsoft 365 services and data\n\n### Communication \u0026 Collaboration\n5. **TeamsAndOutlook**: Teams chat, meetings, email integration\n6. **CopilotForMicrosoft365**: Advanced Copilot features and workflows\n\n### Business Applications\n7. **PowerPlatform**: Power Apps, Power Automate, Power BI integration\n8. **BusinessDataProcessing**: Advanced data analysis and processing\n9. **WordAndExcel**: Document creation, editing, analysis\n10. **EnterpriseApplications**: Third-party business system integration\n11. **CustomConnectors**: Custom API and service integrations\n\n## Microsoft 365 Agents Toolkit Integration\n\n### VS Code Extension Setup\n```bash\n# Install Microsoft 365 Agents Toolkit\n# Extension ID: teamsdevapp.ms-teams-vscode-extension\n```\n\n### TypeSpec Development Workflow\n\n#### 1. Modern Agent Definition\n```typespec\nimport \"@typespec/json-schema\";\n\nusing TypeSpec.JsonSchema;\n\n@jsonSchema(\"/schemas/declarative-agent/v1.5/schema.json\")\nnamespace DeclarativeAgent;\n\n/** Microsoft 365 Declarative Agent */\nmodel Agent {\n  /** Schema version */\n  @minLength(1)\n  $schema: \"https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json\";\n  \n  /** Agent version */\n  version: \"v1.5\";\n  \n  /** Agent name (max 100 characters) */\n  @maxLength(100)\n  @minLength(1)\n  name: string;\n  \n  /** Agent description (max 1000 characters) */\n  @maxLength(1000)\n  @minLength(1)  \n  description: string;\n  \n  /** Agent instructions (max 8000 characters) */\n  @maxLength(8000)\n  @minLength(1)\n  instructions: string;\n  \n  /** Agent capabilities (1-5 items) */\n  @minItems(1)\n  @maxItems(5)\n  capabilities: AgentCapability[];\n  \n  /** Conversation starters (max 4 items) */\n  @maxItems(4)\n  conversation_starters?: ConversationStarter[];\n}\n\n/** Available agent capabilities */\nunion AgentCapability {\n  \"WebSearch\",\n  \"OneDriveAndSharePoint\", \n  \"GraphConnectors\",\n  \"MicrosoftGraph\",\n  \"TeamsAndOutlook\",\n  \"PowerPlatform\",\n  \"BusinessDataProcessing\",\n  \"WordAndExcel\",\n  \"CopilotForMicrosoft365\",\n  \"EnterpriseApplications\",\n  \"CustomConnectors\"\n}\n\n/** Conversation starter definition */\nmodel ConversationStarter {\n  /** Starter text (max 100 characters) */\n  @maxLength(100)\n  @minLength(1)\n  text: string;\n}\n```\n\n#### 2. Compilation to JSON\n```bash\n# Compile TypeSpec to JSON manifest\ntsp compile agent.tsp --emit=@typespec/json-schema\n```\n\n### Environment Configuration\n\n#### Development Environment\n```json\n{\n  \"name\": \"${DEV_AGENT_NAME}\",\n  \"description\": \"Development version: ${AGENT_DESCRIPTION}\",\n  \"instructions\": \"${AGENT_INSTRUCTIONS}\",\n  \"capabilities\": [\"${REQUIRED_CAPABILITIES}\"]\n}\n```\n\n#### Production Environment\n```json\n{\n  \"name\": \"${PROD_AGENT_NAME}\",\n  \"description\": \"${AGENT_DESCRIPTION}\",\n  \"instructions\": \"${AGENT_INSTRUCTIONS}\",\n  \"capabilities\": [\"${PRODUCTION_CAPABILITIES}\"]\n}\n```\n\n## Development Best Practices\n\n### 1. Schema Validation\n```typescript\n// Validate against v1.5 schema\nconst schema = await fetch('https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json');\nconst validator = new JSONSchema(schema);\nconst isValid = validator.validate(agentManifest);\n```\n\n### 2. Character Limit Management\n```typescript\n// Validation helper functions\nfunction validateName(name: string): boolean {\n  return name.length \u003e 0 \u0026\u0026 name.length \u003c= 100;\n}\n\nfunction validateDescription(description: string): boolean {\n  return description.length \u003e 0 \u0026\u0026 description.length \u003c= 1000;\n}\n\nfunction validateInstructions(instructions: string): boolean {\n  return instructions.length \u003e 0 \u0026\u0026 instructions.length \u003c= 8000;\n}\n```\n\n### 3. Capability Selection Strategy\n- **Start Simple**: Begin with 1-2 core capabilities\n- **Incremental Addition**: Add capabilities based on user feedback\n- **Performance Testing**: Test each capability combination thoroughly\n- **Enterprise Readiness**: Consider compliance and security implications\n\n## Agents Playground Testing\n\n### Local Testing Setup\n```bash\n# Start Agents Playground\nnpm install -g @microsoft/agents-playground\nagents-playground start --manifest=./agent.json\n```\n\n### Testing Scenarios\n1. **Capability Validation**: Test each declared capability\n2. **Conversation Flow**: Validate conversation starters\n3. **Error Handling**: Test invalid inputs and edge cases\n4. **Performance**: Measure response times and reliability\n\n## Deployment \u0026 Lifecycle Management\n\n### 1. Development Lifecycle\n```mermaid\ngraph LR\n    A[TypeSpec Definition] --\u003e B[JSON Compilation]\n    B --\u003e C[Local Testing]\n    C --\u003e D[Validation]\n    D --\u003e E[Staging Deployment]\n    E --\u003e F[Production Release]\n```\n\n### 2. Version Management\n```json\n{\n  \"name\": \"MyAgent v1.2.0\",\n  \"description\": \"Production agent with enhanced capabilities\",\n  \"version\": \"v1.5\",\n  \"metadata\": {\n    \"version\": \"1.2.0\",\n    \"build\": \"20241208.1\",\n    \"environment\": \"production\"\n  }\n}\n```\n\n### 3. Environment Promotion\n- **Development**: Full debugging, verbose logging\n- **Staging**: Production-like testing, performance monitoring  \n- **Production**: Optimized performance, minimal logging\n\n## Advanced Features\n\n### Behavior Overrides\n```json\n{\n  \"instructions\": \"You are a specialized financial analyst agent. Always provide disclaimers for financial advice.\",\n  \"behavior_overrides\": {\n    \"response_tone\": \"professional\",\n    \"max_response_length\": 2000,\n    \"citation_requirements\": true\n  }\n}\n```\n\n### Localization Support\n```json\n{\n  \"name\": {\n    \"en-US\": \"Financial Assistant\",\n    \"es-ES\": \"Asistente Financiero\",\n    \"fr-FR\": \"Assistant Financier\"\n  },\n  \"description\": {\n    \"en-US\": \"Provides financial analysis and insights\",\n    \"es-ES\": \"Proporciona análisis e insights financieros\",\n    \"fr-FR\": \"Fournit des analyses et insights financiers\"\n  }\n}\n```\n\n## Monitoring \u0026 Analytics\n\n### Performance Metrics\n- Response time per capability\n- User engagement with conversation starters\n- Error rates and failure patterns\n- Capability utilization statistics\n\n### Logging Strategy\n```typescript\n// Structured logging for agent interactions\nconst log = {\n  timestamp: new Date().toISOString(),\n  agentName: \"MyAgent\",\n  version: \"1.2.0\",\n  userId: \"user123\",\n  capability: \"WebSearch\",\n  responseTime: 1250,\n  success: true\n};\n```\n\n## Security \u0026 Compliance\n\n### Data Privacy\n- Implement proper data handling for sensitive information\n- Ensure compliance with GDPR, CCPA, and organizational policies\n- Use appropriate access controls for enterprise capabilities\n\n### Security Considerations  \n- Validate all inputs and outputs\n- Implement rate limiting and abuse prevention\n- Monitor for suspicious activity patterns\n- Regular security audits and updates\n\n## Troubleshooting\n\n### Common Issues\n1. **Schema Validation Errors**: Check character limits and required fields\n2. **Capability Conflicts**: Verify capability combinations are supported\n3. **Performance Issues**: Monitor response times and optimize instructions\n4. **Deployment Failures**: Validate environment configuration and permissions\n\n### Debug Tools\n- TypeSpec compiler diagnostics\n- Agents Playground debugging\n- Microsoft 365 Agents Toolkit logs\n- Schema validation utilities\n\nThis comprehensive guide ensures robust, scalable, and maintainable Microsoft 365 Copilot declarative agents with full TypeSpec and Microsoft 365 Agents Toolkit integration.","description":"Comprehensive development guidelines for Microsoft 365 Copilot declarative agents with schema v1.5, TypeSpec integration, and Microsoft 365 Agents Toolkit workflows","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/declarative-agents-microsoft365.instructions.md"},"manifest":{}},"content_hash":[107,204,156,94,236,183,185,144,199,73,93,46,180,39,136,147,134,106,34,230,221,61,172,183,101,84,74,49,65,173,30,73],"trust_level":"unsigned","yanked":false}