M365 Agent Developer Best Practices
Follow these best practices for successful M365 Copilot agent development.
Security
- Principle of Least Privilege: Always scope capabilities to the minimum necessary resources
- Credential Management: Use secure credential storage for production environments
- Input Validation: Validate all user inputs and API responses
- PII Handling: Follow data protection regulations when handling personal information
- Audit Logging: Implement comprehensive audit trails for all agent actions
- Secret Storage: Never hardcode credentials; use Azure Key Vault or environment variables
Performance
- Scoped Queries: Use scoped capabilities to reduce query time and improve response quality
- Efficient API Design: Design API plugins with pagination and filtering
- Caching Strategy: Implement appropriate caching for frequently accessed data
- Response Time: Keep operations under 30 seconds to avoid timeouts
- Batch Operations: Use batch APIs when processing multiple items
Error Handling
- Graceful Degradation: Handle errors without breaking the conversation flow
- Clear Error Messages: Provide actionable error messages to users
- Retry Logic: Implement retry mechanisms for transient failures
- Fallback Behavior: Define fallback behavior when capabilities are unavailable
- Error Logging: Log errors with sufficient context for troubleshooting
Testing
- Test All Conversation Starters: Verify each starter works as intended
- Test Edge Cases: Test with missing data, invalid inputs, and error conditions
- Security Testing: Verify scoping and permission controls
- Cross-Environment Testing: Test in dev, staging, and production environments
- User Acceptance Testing: Conduct UAT with actual users before production release
Compliance
- Data Residency: Consider data residency requirements for multi-region deployments
- Retention Policies: Follow organizational data retention policies
- Access Controls: Implement role-based access controls (RBAC)
- Compliance Frameworks: Follow relevant frameworks (GDPR, HIPAA, SOC 2, etc.)
- Documentation: Maintain compliance documentation and audit trails
Maintainability
- Documentation: Add
@docdecorators to all operations, models, and properties - Naming Conventions: Use PascalCase for models/enums, camelCase for properties/actions
- Code Organization: Separate concerns (capabilities, API plugins, models)
- Version Control: Use semantic versioning for shared agents
- Change Management: Document changes and maintain changelog
Conversation Design
- Specific Instructions: Write directive instructions with clear role definition
- Actionable Starters: Create 3-5 specific, actionable conversation starters
- Clear Boundaries: Define what the agent can and cannot do
- Appropriate Tone: Match tone to audience and context
- Confirmation Patterns: Require confirmation for destructive or sensitive actions
Reference: conversation-design.md
Deployment
- Environment Strategy: Use separate environments for dev, staging, and production
- CI/CD Integration: Automate testing and deployment using ATK CLI
- Version Management: Bump versions before re-provisioning shared agents
- Rollback Plan: Have a rollback strategy for failed deployments
- Monitoring: Implement monitoring and alerting for production agents
Reference: deployment.md