Add files via upload
This commit is contained in:
Troy Simeon Taylor
GitHub
parent
1f5529a82f
commit
b154e685da
@ -1,675 +1,316 @@
|
||||
---
|
||||
description: 'Best practices and guidelines for developing declarative agents for Microsoft 365 Copilot following schema v1.5 specifications with Microsoft 365 Agents Toolkit integration'
|
||||
model: GPT-4.1
|
||||
tools: ['codebase']
|
||||
description: Comprehensive development guidelines for Microsoft 365 Copilot declarative agents with schema v1.5, TypeSpec integration, and Microsoft 365 Agents Toolkit workflows
|
||||
applyTo: "**.json, **.ts, **.tsp, **manifest.json, **agent.json, **declarative-agent.json"
|
||||
---
|
||||
|
||||
# Microsoft 365 Declarative Agents Development Guidelines
|
||||
|
||||
Comprehensive instructions for developing high-quality declarative agents for Microsoft 365 Copilot using schema v1.5 with Microsoft 365 Agents Toolkit integration.
|
||||
## Overview
|
||||
|
||||
## Core Development Principles
|
||||
Microsoft 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.
|
||||
|
||||
### Schema v1.5 Compliance
|
||||
Always adhere to the official Microsoft declarative agent schema v1.5:
|
||||
```json
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/microsoft/copilot-studio-schemas/main/schemas/v1.5/declarative-copilot.schema.json",
|
||||
"version": "v1.0",
|
||||
"name": "[Agent Name]",
|
||||
"description": "[Agent Description]",
|
||||
"instructions": "[Detailed Instructions]",
|
||||
"capabilities": [],
|
||||
"conversation_starters": []
|
||||
}
|
||||
```
|
||||
## Schema Specification v1.5
|
||||
|
||||
### Character Limit Constraints
|
||||
Strictly enforce character limits:
|
||||
- **name**: Maximum 100 characters
|
||||
- **description**: Maximum 1000 characters
|
||||
- **instructions**: Maximum 8000 characters
|
||||
- **conversation_starters.text**: Maximum 100 characters each
|
||||
|
||||
### Microsoft 365 Agents Toolkit Integration
|
||||
Leverage the Microsoft 365 Agents Toolkit (teamsdevapp.ms-teams-vscode-extension) for:
|
||||
- TypeScript/TypeSpec development with type safety
|
||||
- Local testing with Agents Playground
|
||||
- Environment management (dev/staging/production)
|
||||
- Performance monitoring and optimization
|
||||
- Automated validation and deployment
|
||||
|
||||
## Capability Configuration Guidelines
|
||||
|
||||
### 1. WebSearch Capability
|
||||
Use for real-time information retrieval and current data access:
|
||||
### Core Properties
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "WebSearch",
|
||||
"configuration": {
|
||||
"enabled": true,
|
||||
"search_domains": ["specific-domains-if-needed"],
|
||||
"result_limit": 10,
|
||||
"content_filtering": {
|
||||
"safe_search": "strict",
|
||||
"relevance_threshold": 0.7
|
||||
}
|
||||
}
|
||||
"$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)"]
|
||||
}
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Enable only when real-time data is essential
|
||||
- Configure domain restrictions for enterprise security
|
||||
- Set appropriate result limits to manage token usage
|
||||
- Use content filtering for compliance requirements
|
||||
### Character Limits & Constraints
|
||||
- **Name**: Maximum 100 characters, required
|
||||
- **Description**: Maximum 1000 characters, required
|
||||
- **Instructions**: Maximum 8000 characters, required
|
||||
- **Capabilities**: Maximum 5 items, minimum 1 item
|
||||
- **Conversation Starters**: Maximum 4 items, optional
|
||||
|
||||
### 2. OneDriveAndSharePoint Capability
|
||||
Configure for file operations and content management:
|
||||
## Available Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "OneDriveAndSharePoint",
|
||||
"configuration": {
|
||||
"scopes": [
|
||||
"https://graph.microsoft.com/Files.Read",
|
||||
"https://graph.microsoft.com/Files.ReadWrite"
|
||||
],
|
||||
"file_types": [".docx", ".xlsx", ".pptx", ".pdf"],
|
||||
"size_limits": {
|
||||
"max_file_size": "10MB",
|
||||
"max_concurrent_files": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
### Core Capabilities
|
||||
1. **WebSearch**: Internet search and real-time information access
|
||||
2. **OneDriveAndSharePoint**: File access, document search, content management
|
||||
3. **GraphConnectors**: Enterprise data integration from third-party systems
|
||||
4. **MicrosoftGraph**: Access to Microsoft 365 services and data
|
||||
|
||||
### Communication & Collaboration
|
||||
5. **TeamsAndOutlook**: Teams chat, meetings, email integration
|
||||
6. **CopilotForMicrosoft365**: Advanced Copilot features and workflows
|
||||
|
||||
### Business Applications
|
||||
7. **PowerPlatform**: Power Apps, Power Automate, Power BI integration
|
||||
8. **BusinessDataProcessing**: Advanced data analysis and processing
|
||||
9. **WordAndExcel**: Document creation, editing, analysis
|
||||
10. **EnterpriseApplications**: Third-party business system integration
|
||||
11. **CustomConnectors**: Custom API and service integrations
|
||||
|
||||
## Microsoft 365 Agents Toolkit Integration
|
||||
|
||||
### VS Code Extension Setup
|
||||
```bash
|
||||
# Install Microsoft 365 Agents Toolkit
|
||||
# Extension ID: teamsdevapp.ms-teams-vscode-extension
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Request minimal necessary scopes
|
||||
- Specify supported file types explicitly
|
||||
- Set reasonable size limits for performance
|
||||
- Implement proper error handling for file operations
|
||||
|
||||
### 3. GraphConnectors Capability
|
||||
Integrate custom data sources through Graph Connectors:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "GraphConnectors",
|
||||
"configuration": {
|
||||
"connection_id": "your-connector-id",
|
||||
"entity_types": ["CustomDocument", "KnowledgeArticle"],
|
||||
"query_capabilities": {
|
||||
"semantic_search": true,
|
||||
"faceted_search": true,
|
||||
"result_ranking": "relevance"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Ensure connector is properly configured and indexed
|
||||
- Define specific entity types for targeted search
|
||||
- Enable semantic search for better user experience
|
||||
- Configure result ranking based on business needs
|
||||
|
||||
### 4. Function Capability
|
||||
Implement custom business logic and API integrations:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "Function",
|
||||
"function_definition": {
|
||||
"name": "analyze_sales_data",
|
||||
"description": "Analyze sales performance metrics and generate insights",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"time_period": {
|
||||
"type": "string",
|
||||
"description": "Analysis time period (e.g., 'last_quarter', 'ytd')",
|
||||
"enum": ["last_month", "last_quarter", "ytd", "custom"]
|
||||
},
|
||||
"metrics": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"enum": ["revenue", "units_sold", "conversion_rate", "customer_acquisition"]
|
||||
},
|
||||
"description": "Specific metrics to analyze"
|
||||
}
|
||||
},
|
||||
"required": ["time_period", "metrics"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Use clear, descriptive function names
|
||||
- Provide comprehensive parameter descriptions
|
||||
- Define appropriate parameter types and constraints
|
||||
- Include required field specifications
|
||||
- Implement robust error handling in function implementation
|
||||
|
||||
### 5. MicrosoftGraph Capability
|
||||
Access Microsoft 365 services and data:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "MicrosoftGraph",
|
||||
"configuration": {
|
||||
"scopes": [
|
||||
"https://graph.microsoft.com/User.Read",
|
||||
"https://graph.microsoft.com/Calendars.ReadWrite",
|
||||
"https://graph.microsoft.com/Mail.Read"
|
||||
],
|
||||
"delegated_permissions": true,
|
||||
"api_version": "v1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
- Request only necessary scopes for functionality
|
||||
- Use delegated permissions for user context
|
||||
- Specify stable API versions (v1.0) for production
|
||||
- Handle authentication errors gracefully
|
||||
|
||||
## TypeSpec Development Best Practices
|
||||
|
||||
### Type-Safe Agent Definitions
|
||||
Use TypeSpec for type-safe agent development:
|
||||
### TypeSpec Development Workflow
|
||||
|
||||
#### 1. Modern Agent Definition
|
||||
```typespec
|
||||
import "@typespec/http";
|
||||
import "@microsoft/declarative-agent-manifest";
|
||||
import "@typespec/json-schema";
|
||||
|
||||
using Microsoft.DeclarativeAgent;
|
||||
using TypeSpec.JsonSchema;
|
||||
|
||||
/** Business Intelligence Agent for sales data analysis */
|
||||
@DeclarativeAgent
|
||||
model BusinessIntelligenceAgent {
|
||||
/** Agent display name */
|
||||
@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)
|
||||
name: "Sales Analytics Assistant";
|
||||
@minLength(1)
|
||||
name: string;
|
||||
|
||||
/** Agent description for users */
|
||||
/** Agent description (max 1000 characters) */
|
||||
@maxLength(1000)
|
||||
description: "AI-powered assistant for sales data analysis, reporting, and insights generation";
|
||||
@minLength(1)
|
||||
description: string;
|
||||
|
||||
/** Detailed agent instructions */
|
||||
/** Agent instructions (max 8000 characters) */
|
||||
@maxLength(8000)
|
||||
instructions: `You are a specialized business intelligence assistant focused on sales data analysis...`;
|
||||
@minLength(1)
|
||||
instructions: string;
|
||||
|
||||
/** Agent capabilities */
|
||||
capabilities: [
|
||||
FunctionCapability,
|
||||
MicrosoftGraphCapability
|
||||
];
|
||||
/** Agent capabilities (1-5 items) */
|
||||
@minItems(1)
|
||||
@maxItems(5)
|
||||
capabilities: AgentCapability[];
|
||||
|
||||
/** Pre-defined conversation starters */
|
||||
conversation_starters: ConversationStarter[];
|
||||
/** Conversation starters (max 4 items) */
|
||||
@maxItems(4)
|
||||
conversation_starters?: ConversationStarter[];
|
||||
}
|
||||
|
||||
model FunctionCapability extends Capability {
|
||||
type: "Function";
|
||||
function_definition: SalesAnalysisFunction;
|
||||
/** Available agent capabilities */
|
||||
union AgentCapability {
|
||||
"WebSearch",
|
||||
"OneDriveAndSharePoint",
|
||||
"GraphConnectors",
|
||||
"MicrosoftGraph",
|
||||
"TeamsAndOutlook",
|
||||
"PowerPlatform",
|
||||
"BusinessDataProcessing",
|
||||
"WordAndExcel",
|
||||
"CopilotForMicrosoft365",
|
||||
"EnterpriseApplications",
|
||||
"CustomConnectors"
|
||||
}
|
||||
|
||||
model SalesAnalysisFunction {
|
||||
name: "analyze_sales_data";
|
||||
description: "Analyze sales performance data and generate insights";
|
||||
parameters: SalesAnalysisParameters;
|
||||
/** Conversation starter definition */
|
||||
model ConversationStarter {
|
||||
/** Starter text (max 100 characters) */
|
||||
@maxLength(100)
|
||||
@minLength(1)
|
||||
text: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Compilation and Validation
|
||||
Compile TypeSpec to JSON and validate:
|
||||
|
||||
#### 2. Compilation to JSON
|
||||
```bash
|
||||
# Compile TypeSpec to JSON manifest
|
||||
tsp compile models/agent.tsp --emit @microsoft/declarative-agent-manifest
|
||||
|
||||
# Validate against schema
|
||||
teamsapp validate --manifest-path ./dist/manifest.json
|
||||
tsp compile agent.tsp --emit=@typespec/json-schema
|
||||
```
|
||||
|
||||
## Agent Instruction Engineering
|
||||
|
||||
### Instruction Structure Template
|
||||
Follow this structure for comprehensive agent instructions:
|
||||
|
||||
```markdown
|
||||
## Role Definition
|
||||
You are [specific role] specialized in [domain expertise].
|
||||
|
||||
## Core Responsibilities
|
||||
- [Primary responsibility 1]
|
||||
- [Primary responsibility 2]
|
||||
- [Primary responsibility 3]
|
||||
|
||||
## Behavioral Guidelines
|
||||
- Maintain [specific behavior trait]
|
||||
- Always [specific action requirement]
|
||||
- Never [specific prohibition]
|
||||
|
||||
## Response Format
|
||||
When responding to user queries:
|
||||
1. [Step 1 requirement]
|
||||
2. [Step 2 requirement]
|
||||
3. [Step 3 requirement]
|
||||
|
||||
## Capability Usage
|
||||
- Use WebSearch for [specific scenarios]
|
||||
- Use Function capabilities for [specific scenarios]
|
||||
- Use MicrosoftGraph for [specific scenarios]
|
||||
|
||||
## Error Handling
|
||||
If you encounter issues:
|
||||
- [Error scenario 1]: [Response strategy]
|
||||
- [Error scenario 2]: [Response strategy]
|
||||
|
||||
## Limitations
|
||||
- I cannot [specific limitation 1]
|
||||
- I do not have access to [specific limitation 2]
|
||||
```
|
||||
|
||||
### Token Efficiency Optimization
|
||||
Optimize instructions for token efficiency:
|
||||
|
||||
1. **Use concise language**: Avoid redundant phrases
|
||||
2. **Prioritize information**: Place most important guidance first
|
||||
3. **Use structured formatting**: Bullet points and numbered lists
|
||||
4. **Avoid repetition**: Each instruction should provide unique value
|
||||
5. **Test token usage**: Monitor actual token consumption in testing
|
||||
|
||||
## Conversation Starter Best Practices
|
||||
|
||||
### Effective Conversation Starters
|
||||
Design conversation starters that demonstrate agent capabilities:
|
||||
### Environment Configuration
|
||||
|
||||
#### Development Environment
|
||||
```json
|
||||
{
|
||||
"conversation_starters": [
|
||||
{
|
||||
"text": "Analyze last quarter's sales performance by region"
|
||||
},
|
||||
{
|
||||
"text": "Generate a monthly revenue report with trend analysis"
|
||||
},
|
||||
{
|
||||
"text": "Compare this year's sales metrics to last year"
|
||||
},
|
||||
{
|
||||
"text": "Identify top-performing products and growth opportunities"
|
||||
}
|
||||
]
|
||||
"name": "${DEV_AGENT_NAME}",
|
||||
"description": "Development version: ${AGENT_DESCRIPTION}",
|
||||
"instructions": "${AGENT_INSTRUCTIONS}",
|
||||
"capabilities": ["${REQUIRED_CAPABILITIES}"]
|
||||
}
|
||||
```
|
||||
|
||||
**Guidelines:**
|
||||
- **Specific and actionable**: Each starter should trigger a specific workflow
|
||||
- **Capability demonstration**: Show what the agent can do
|
||||
- **User language**: Use terminology familiar to target users
|
||||
- **Varied complexity**: Include simple and complex examples
|
||||
- **Business value**: Focus on outcomes users care about
|
||||
#### Production Environment
|
||||
```json
|
||||
{
|
||||
"name": "${PROD_AGENT_NAME}",
|
||||
"description": "${AGENT_DESCRIPTION}",
|
||||
"instructions": "${AGENT_INSTRUCTIONS}",
|
||||
"capabilities": ["${PRODUCTION_CAPABILITIES}"]
|
||||
}
|
||||
```
|
||||
|
||||
## Microsoft 365 Agents Toolkit Workflow
|
||||
## Development Best Practices
|
||||
|
||||
### Development Environment Setup
|
||||
1. **Install Prerequisites**:
|
||||
```bash
|
||||
# Install Teams Toolkit CLI
|
||||
npm install -g @microsoft/teamsapp-cli
|
||||
### 1. Schema Validation
|
||||
```typescript
|
||||
// Validate against v1.5 schema
|
||||
const schema = await fetch('https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json');
|
||||
const validator = new JSONSchema(schema);
|
||||
const isValid = validator.validate(agentManifest);
|
||||
```
|
||||
|
||||
# Verify installation
|
||||
teamsapp --version
|
||||
```
|
||||
### 2. Character Limit Management
|
||||
```typescript
|
||||
// Validation helper functions
|
||||
function validateName(name: string): boolean {
|
||||
return name.length > 0 && name.length <= 100;
|
||||
}
|
||||
|
||||
2. **VS Code Extension Setup**:
|
||||
- Install Microsoft 365 Agents Toolkit extension
|
||||
- Configure workspace settings for declarative agents
|
||||
- Set up debugging configuration
|
||||
function validateDescription(description: string): boolean {
|
||||
return description.length > 0 && description.length <= 1000;
|
||||
}
|
||||
|
||||
3. **Project Initialization**:
|
||||
```bash
|
||||
# Create new declarative agent project
|
||||
teamsapp new declarative-agent --name "MyBusinessAgent"
|
||||
function validateInstructions(instructions: string): boolean {
|
||||
return instructions.length > 0 && instructions.length <= 8000;
|
||||
}
|
||||
```
|
||||
|
||||
# Initialize TypeSpec development
|
||||
npm install @typespec/compiler @microsoft/declarative-agent-manifest
|
||||
```
|
||||
### 3. Capability Selection Strategy
|
||||
- **Start Simple**: Begin with 1-2 core capabilities
|
||||
- **Incremental Addition**: Add capabilities based on user feedback
|
||||
- **Performance Testing**: Test each capability combination thoroughly
|
||||
- **Enterprise Readiness**: Consider compliance and security implications
|
||||
|
||||
### Local Development and Testing
|
||||
1. **Agents Playground Integration**:
|
||||
- Load manifest in toolkit
|
||||
- Test conversation flows interactively
|
||||
- Validate capability responses
|
||||
- Monitor token usage and performance
|
||||
## Agents Playground Testing
|
||||
|
||||
2. **Environment Configuration**:
|
||||
```json
|
||||
{
|
||||
"environments": {
|
||||
"development": {
|
||||
"manifest_path": "./manifests/dev-manifest.json",
|
||||
"test_scenarios": "./test-data/dev-scenarios.json",
|
||||
"mock_data": true
|
||||
### Local Testing Setup
|
||||
```bash
|
||||
# Start Agents Playground
|
||||
npm install -g @microsoft/agents-playground
|
||||
agents-playground start --manifest=./agent.json
|
||||
```
|
||||
|
||||
### Testing Scenarios
|
||||
1. **Capability Validation**: Test each declared capability
|
||||
2. **Conversation Flow**: Validate conversation starters
|
||||
3. **Error Handling**: Test invalid inputs and edge cases
|
||||
4. **Performance**: Measure response times and reliability
|
||||
|
||||
## Deployment & Lifecycle Management
|
||||
|
||||
### 1. Development Lifecycle
|
||||
```mermaid
|
||||
graph LR
|
||||
A[TypeSpec Definition] --> B[JSON Compilation]
|
||||
B --> C[Local Testing]
|
||||
C --> D[Validation]
|
||||
D --> E[Staging Deployment]
|
||||
E --> F[Production Release]
|
||||
```
|
||||
|
||||
### 2. Version Management
|
||||
```json
|
||||
{
|
||||
"name": "MyAgent v1.2.0",
|
||||
"description": "Production agent with enhanced capabilities",
|
||||
"version": "v1.5",
|
||||
"metadata": {
|
||||
"version": "1.2.0",
|
||||
"build": "20241208.1",
|
||||
"environment": "production"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Environment Promotion
|
||||
- **Development**: Full debugging, verbose logging
|
||||
- **Staging**: Production-like testing, performance monitoring
|
||||
- **Production**: Optimized performance, minimal logging
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Behavior Overrides
|
||||
```json
|
||||
{
|
||||
"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 Support
|
||||
```json
|
||||
{
|
||||
"name": {
|
||||
"en-US": "Financial Assistant",
|
||||
"es-ES": "Asistente Financiero",
|
||||
"fr-FR": "Assistant Financier"
|
||||
},
|
||||
"staging": {
|
||||
"manifest_path": "./manifests/staging-manifest.json",
|
||||
"test_scenarios": "./test-data/staging-scenarios.json",
|
||||
"integration_testing": true
|
||||
},
|
||||
"production": {
|
||||
"manifest_path": "./manifests/prod-manifest.json",
|
||||
"monitoring_enabled": true,
|
||||
"performance_tracking": true
|
||||
"description": {
|
||||
"en-US": "Provides financial analysis and insights",
|
||||
"es-ES": "Proporciona análisis e insights financieros",
|
||||
"fr-FR": "Fournit des analyses et insights financiers"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
3. **Debugging and Troubleshooting**:
|
||||
```typescript
|
||||
interface DebuggingConfig {
|
||||
log_level: "debug" | "info" | "warn" | "error";
|
||||
trace_capability_calls: boolean;
|
||||
monitor_token_usage: boolean;
|
||||
validate_responses: boolean;
|
||||
}
|
||||
```
|
||||
## Monitoring & Analytics
|
||||
|
||||
### Performance Optimization
|
||||
1. **Token Usage Monitoring**:
|
||||
```typescript
|
||||
interface TokenUsageMetrics {
|
||||
instruction_tokens: number;
|
||||
capability_tokens: number;
|
||||
response_tokens: number;
|
||||
total_tokens: number;
|
||||
optimization_suggestions: string[];
|
||||
}
|
||||
```
|
||||
|
||||
2. **Response Time Optimization**:
|
||||
- Capability ordering optimization
|
||||
- Parallel capability execution where possible
|
||||
- Caching strategies for repeated queries
|
||||
- Connection pooling for external APIs
|
||||
|
||||
3. **Memory Management**:
|
||||
- Conversation context optimization
|
||||
- State management best practices
|
||||
- Resource cleanup procedures
|
||||
|
||||
## Security and Compliance Guidelines
|
||||
|
||||
### Authentication and Authorization
|
||||
1. **OAuth 2.0 Implementation**:
|
||||
```json
|
||||
{
|
||||
"authentication": {
|
||||
"type": "OAuth2",
|
||||
"provider": "Microsoft",
|
||||
"scopes": [
|
||||
"https://graph.microsoft.com/User.Read",
|
||||
"https://graph.microsoft.com/Files.Read"
|
||||
],
|
||||
"token_management": {
|
||||
"refresh_strategy": "automatic",
|
||||
"expiration_handling": "graceful_degradation"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Scope Minimization**:
|
||||
- Request only necessary permissions
|
||||
- Document scope justification
|
||||
- Implement permission checking
|
||||
- Handle scope denial gracefully
|
||||
|
||||
### Data Protection
|
||||
1. **PII Handling**:
|
||||
```typescript
|
||||
interface PIIHandlingConfig {
|
||||
detection_enabled: boolean;
|
||||
redaction_strategy: "mask" | "remove" | "encrypt";
|
||||
audit_logging: boolean;
|
||||
retention_policy: string;
|
||||
}
|
||||
```
|
||||
|
||||
2. **Data Encryption**:
|
||||
- Encrypt data in transit (TLS 1.3)
|
||||
- Encrypt sensitive data at rest
|
||||
- Implement key rotation policies
|
||||
- Use Azure Key Vault for secrets
|
||||
|
||||
### Compliance Framework
|
||||
1. **Audit Logging**:
|
||||
```json
|
||||
{
|
||||
"audit_config": {
|
||||
"log_user_interactions": true,
|
||||
"log_capability_usage": true,
|
||||
"log_data_access": true,
|
||||
"retention_period": "7_years",
|
||||
"compliance_frameworks": ["SOC2", "GDPR", "ISO27001"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Compliance Validation**:
|
||||
- Regular security assessments
|
||||
- Compliance monitoring
|
||||
- Incident response procedures
|
||||
- Data breach notification protocols
|
||||
|
||||
## Testing and Validation Procedures
|
||||
|
||||
### Unit Testing
|
||||
Test individual components:
|
||||
### Performance Metrics
|
||||
- Response time per capability
|
||||
- User engagement with conversation starters
|
||||
- Error rates and failure patterns
|
||||
- Capability utilization statistics
|
||||
|
||||
### Logging Strategy
|
||||
```typescript
|
||||
describe('Sales Analysis Agent', () => {
|
||||
test('validates manifest schema compliance', () => {
|
||||
const manifest = loadManifest('./dist/manifest.json');
|
||||
expect(validateSchema(manifest)).toBe(true);
|
||||
});
|
||||
|
||||
test('respects character limits', () => {
|
||||
const manifest = loadManifest('./dist/manifest.json');
|
||||
expect(manifest.name.length).toBeLessThanOrEqual(100);
|
||||
expect(manifest.description.length).toBeLessThanOrEqual(1000);
|
||||
expect(manifest.instructions.length).toBeLessThanOrEqual(8000);
|
||||
});
|
||||
|
||||
test('validates capability configurations', () => {
|
||||
const manifest = loadManifest('./dist/manifest.json');
|
||||
manifest.capabilities.forEach(capability => {
|
||||
expect(validateCapabilityConfig(capability)).toBe(true);
|
||||
});
|
||||
});
|
||||
});
|
||||
// Structured logging for agent interactions
|
||||
const log = {
|
||||
timestamp: new Date().toISOString(),
|
||||
agentName: "MyAgent",
|
||||
version: "1.2.0",
|
||||
userId: "user123",
|
||||
capability: "WebSearch",
|
||||
responseTime: 1250,
|
||||
success: true
|
||||
};
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
Test capability interactions:
|
||||
## Security & Compliance
|
||||
|
||||
```typescript
|
||||
describe('Capability Integration', () => {
|
||||
test('function capability responds correctly', async () => {
|
||||
const response = await testCapability('Function', {
|
||||
function_name: 'analyze_sales_data',
|
||||
parameters: { time_period: 'last_quarter', metrics: ['revenue'] }
|
||||
});
|
||||
expect(response.success).toBe(true);
|
||||
expect(response.data).toBeDefined();
|
||||
});
|
||||
### Data Privacy
|
||||
- Implement proper data handling for sensitive information
|
||||
- Ensure compliance with GDPR, CCPA, and organizational policies
|
||||
- Use appropriate access controls for enterprise capabilities
|
||||
|
||||
test('graph capability handles authentication', async () => {
|
||||
const response = await testCapability('MicrosoftGraph', {
|
||||
endpoint: '/me',
|
||||
method: 'GET'
|
||||
});
|
||||
expect(response.authenticated).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
### Security Considerations
|
||||
- Validate all inputs and outputs
|
||||
- Implement rate limiting and abuse prevention
|
||||
- Monitor for suspicious activity patterns
|
||||
- Regular security audits and updates
|
||||
|
||||
### Performance Testing
|
||||
Validate performance requirements:
|
||||
## Troubleshooting
|
||||
|
||||
```typescript
|
||||
describe('Performance Requirements', () => {
|
||||
test('response time under 3 seconds', async () => {
|
||||
const startTime = Date.now();
|
||||
const response = await sendMessage('Analyze sales data');
|
||||
const responseTime = Date.now() - startTime;
|
||||
expect(responseTime).toBeLessThan(3000);
|
||||
});
|
||||
### Common Issues
|
||||
1. **Schema Validation Errors**: Check character limits and required fields
|
||||
2. **Capability Conflicts**: Verify capability combinations are supported
|
||||
3. **Performance Issues**: Monitor response times and optimize instructions
|
||||
4. **Deployment Failures**: Validate environment configuration and permissions
|
||||
|
||||
test('token usage within limits', async () => {
|
||||
const response = await sendMessage('Generate quarterly report');
|
||||
expect(response.token_usage.total).toBeLessThan(4000);
|
||||
});
|
||||
});
|
||||
```
|
||||
### Debug Tools
|
||||
- TypeSpec compiler diagnostics
|
||||
- Agents Playground debugging
|
||||
- Microsoft 365 Agents Toolkit logs
|
||||
- Schema validation utilities
|
||||
|
||||
## Production Deployment Guidelines
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
- [ ] Schema validation passes
|
||||
- [ ] Character limits respected
|
||||
- [ ] All capabilities tested individually
|
||||
- [ ] Integration testing completed
|
||||
- [ ] Performance benchmarks met
|
||||
- [ ] Security review completed
|
||||
- [ ] Compliance validation finished
|
||||
- [ ] Documentation complete
|
||||
- [ ] Monitoring configured
|
||||
- [ ] Rollback plan prepared
|
||||
|
||||
### Deployment Pipeline
|
||||
```yaml
|
||||
# .github/workflows/deploy-agent.yml
|
||||
name: Deploy Declarative Agent
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
jobs:
|
||||
validate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: '18'
|
||||
- name: Install dependencies
|
||||
run: npm install
|
||||
- name: Compile TypeSpec
|
||||
run: tsp compile models/agent.tsp
|
||||
- name: Validate manifest
|
||||
run: teamsapp validate --manifest-path ./dist/manifest.json
|
||||
- name: Run tests
|
||||
run: npm test
|
||||
deploy:
|
||||
needs: validate
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Deploy to staging
|
||||
run: teamsapp deploy --env staging
|
||||
- name: Run integration tests
|
||||
run: npm run test:integration
|
||||
- name: Deploy to production
|
||||
run: teamsapp deploy --env production
|
||||
```
|
||||
|
||||
### Monitoring and Maintenance
|
||||
1. **Performance Monitoring**:
|
||||
```json
|
||||
{
|
||||
"monitoring": {
|
||||
"response_time_tracking": true,
|
||||
"token_usage_monitoring": true,
|
||||
"error_rate_tracking": true,
|
||||
"user_satisfaction_metrics": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Incident Response**:
|
||||
- Automated alerting for failures
|
||||
- Escalation procedures
|
||||
- Rollback capabilities
|
||||
- Post-incident reviews
|
||||
|
||||
3. **Continuous Improvement**:
|
||||
- Regular performance reviews
|
||||
- User feedback integration
|
||||
- Capability optimization
|
||||
- Security updates
|
||||
|
||||
## Common Patterns and Anti-Patterns
|
||||
|
||||
### Design Patterns ✅
|
||||
|
||||
1. **Single Responsibility Pattern**:
|
||||
```json
|
||||
{
|
||||
"name": "Sales Analytics Assistant",
|
||||
"focus": "sales_data_analysis",
|
||||
"capabilities": ["Function", "MicrosoftGraph"]
|
||||
}
|
||||
```
|
||||
|
||||
2. **Graceful Degradation Pattern**:
|
||||
```typescript
|
||||
if (primaryCapabilityFails) {
|
||||
return fallbackResponse();
|
||||
}
|
||||
```
|
||||
|
||||
3. **Progressive Enhancement Pattern**:
|
||||
```json
|
||||
{
|
||||
"basic_functionality": ["simple_queries"],
|
||||
"enhanced_functionality": ["complex_analysis", "visualizations"]
|
||||
}
|
||||
```
|
||||
|
||||
### Anti-Patterns ❌
|
||||
|
||||
1. **Kitchen Sink Anti-Pattern**:
|
||||
```json
|
||||
// Don't do this - too many unrelated capabilities
|
||||
{
|
||||
"capabilities": [
|
||||
"WebSearch", "OneDriveAndSharePoint", "GraphConnectors",
|
||||
"Function", "MicrosoftGraph"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
2. **Overly Generic Instructions**:
|
||||
```text
|
||||
// Don't do this - too vague
|
||||
"You are a helpful assistant that can do many things."
|
||||
```
|
||||
|
||||
3. **Character Limit Violations**:
|
||||
```json
|
||||
// Don't do this - exceeds limits
|
||||
{
|
||||
"name": "Super Long Agent Name That Exceeds The Maximum Character Limit Of One Hundred Characters And Should Be Shortened",
|
||||
"description": "[description over 1000 characters]"
|
||||
}
|
||||
```
|
||||
|
||||
Follow these comprehensive guidelines to create high-quality, performant, and secure declarative agents for Microsoft 365 Copilot that provide exceptional user experiences.
|
||||
This comprehensive guide ensures robust, scalable, and maintainable Microsoft 365 Copilot declarative agents with full TypeSpec and Microsoft 365 Agents Toolkit integration.
|
||||
Loading…
x
Reference in New Issue
Block a user