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'
|
description: Comprehensive development guidelines for Microsoft 365 Copilot declarative agents with schema v1.5, TypeSpec integration, and Microsoft 365 Agents Toolkit workflows
|
||||||
model: GPT-4.1
|
applyTo: "**.json, **.ts, **.tsp, **manifest.json, **agent.json, **declarative-agent.json"
|
||||||
tools: ['codebase']
|
|
||||||
---
|
---
|
||||||
|
|
||||||
# Microsoft 365 Declarative Agents Development Guidelines
|
# 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
|
## Schema Specification v1.5
|
||||||
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": []
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Character Limit Constraints
|
### Core Properties
|
||||||
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:
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"type": "WebSearch",
|
"$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json",
|
||||||
"configuration": {
|
"version": "v1.5",
|
||||||
"enabled": true,
|
"name": "string (max 100 characters)",
|
||||||
"search_domains": ["specific-domains-if-needed"],
|
"description": "string (max 1000 characters)",
|
||||||
"result_limit": 10,
|
"instructions": "string (max 8000 characters)",
|
||||||
"content_filtering": {
|
"capabilities": ["array (max 5 items)"],
|
||||||
"safe_search": "strict",
|
"conversation_starters": ["array (max 4 items, optional)"]
|
||||||
"relevance_threshold": 0.7
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Best Practices:**
|
### Character Limits & Constraints
|
||||||
- Enable only when real-time data is essential
|
- **Name**: Maximum 100 characters, required
|
||||||
- Configure domain restrictions for enterprise security
|
- **Description**: Maximum 1000 characters, required
|
||||||
- Set appropriate result limits to manage token usage
|
- **Instructions**: Maximum 8000 characters, required
|
||||||
- Use content filtering for compliance requirements
|
- **Capabilities**: Maximum 5 items, minimum 1 item
|
||||||
|
- **Conversation Starters**: Maximum 4 items, optional
|
||||||
|
|
||||||
### 2. OneDriveAndSharePoint Capability
|
## Available Capabilities
|
||||||
Configure for file operations and content management:
|
|
||||||
|
|
||||||
```json
|
### Core Capabilities
|
||||||
{
|
1. **WebSearch**: Internet search and real-time information access
|
||||||
"type": "OneDriveAndSharePoint",
|
2. **OneDriveAndSharePoint**: File access, document search, content management
|
||||||
"configuration": {
|
3. **GraphConnectors**: Enterprise data integration from third-party systems
|
||||||
"scopes": [
|
4. **MicrosoftGraph**: Access to Microsoft 365 services and data
|
||||||
"https://graph.microsoft.com/Files.Read",
|
|
||||||
"https://graph.microsoft.com/Files.ReadWrite"
|
### Communication & Collaboration
|
||||||
],
|
5. **TeamsAndOutlook**: Teams chat, meetings, email integration
|
||||||
"file_types": [".docx", ".xlsx", ".pptx", ".pdf"],
|
6. **CopilotForMicrosoft365**: Advanced Copilot features and workflows
|
||||||
"size_limits": {
|
|
||||||
"max_file_size": "10MB",
|
### Business Applications
|
||||||
"max_concurrent_files": 5
|
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:**
|
### TypeSpec Development Workflow
|
||||||
- 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:
|
|
||||||
|
|
||||||
|
#### 1. Modern Agent Definition
|
||||||
```typespec
|
```typespec
|
||||||
import "@typespec/http";
|
import "@typespec/json-schema";
|
||||||
import "@microsoft/declarative-agent-manifest";
|
|
||||||
|
|
||||||
using Microsoft.DeclarativeAgent;
|
using TypeSpec.JsonSchema;
|
||||||
|
|
||||||
/** Business Intelligence Agent for sales data analysis */
|
@jsonSchema("/schemas/declarative-agent/v1.5/schema.json")
|
||||||
@DeclarativeAgent
|
namespace DeclarativeAgent;
|
||||||
model BusinessIntelligenceAgent {
|
|
||||||
/** Agent display name */
|
/** 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)
|
@maxLength(100)
|
||||||
name: "Sales Analytics Assistant";
|
@minLength(1)
|
||||||
|
name: string;
|
||||||
|
|
||||||
/** Agent description for users */
|
/** Agent description (max 1000 characters) */
|
||||||
@maxLength(1000)
|
@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)
|
@maxLength(8000)
|
||||||
instructions: `You are a specialized business intelligence assistant focused on sales data analysis...`;
|
@minLength(1)
|
||||||
|
instructions: string;
|
||||||
|
|
||||||
/** Agent capabilities */
|
/** Agent capabilities (1-5 items) */
|
||||||
capabilities: [
|
@minItems(1)
|
||||||
FunctionCapability,
|
@maxItems(5)
|
||||||
MicrosoftGraphCapability
|
capabilities: AgentCapability[];
|
||||||
];
|
|
||||||
|
|
||||||
/** Pre-defined conversation starters */
|
/** Conversation starters (max 4 items) */
|
||||||
conversation_starters: ConversationStarter[];
|
@maxItems(4)
|
||||||
|
conversation_starters?: ConversationStarter[];
|
||||||
}
|
}
|
||||||
|
|
||||||
model FunctionCapability extends Capability {
|
/** Available agent capabilities */
|
||||||
type: "Function";
|
union AgentCapability {
|
||||||
function_definition: SalesAnalysisFunction;
|
"WebSearch",
|
||||||
|
"OneDriveAndSharePoint",
|
||||||
|
"GraphConnectors",
|
||||||
|
"MicrosoftGraph",
|
||||||
|
"TeamsAndOutlook",
|
||||||
|
"PowerPlatform",
|
||||||
|
"BusinessDataProcessing",
|
||||||
|
"WordAndExcel",
|
||||||
|
"CopilotForMicrosoft365",
|
||||||
|
"EnterpriseApplications",
|
||||||
|
"CustomConnectors"
|
||||||
}
|
}
|
||||||
|
|
||||||
model SalesAnalysisFunction {
|
/** Conversation starter definition */
|
||||||
name: "analyze_sales_data";
|
model ConversationStarter {
|
||||||
description: "Analyze sales performance data and generate insights";
|
/** Starter text (max 100 characters) */
|
||||||
parameters: SalesAnalysisParameters;
|
@maxLength(100)
|
||||||
|
@minLength(1)
|
||||||
|
text: string;
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Compilation and Validation
|
#### 2. Compilation to JSON
|
||||||
Compile TypeSpec to JSON and validate:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Compile TypeSpec to JSON manifest
|
# Compile TypeSpec to JSON manifest
|
||||||
tsp compile models/agent.tsp --emit @microsoft/declarative-agent-manifest
|
tsp compile agent.tsp --emit=@typespec/json-schema
|
||||||
|
|
||||||
# Validate against schema
|
|
||||||
teamsapp validate --manifest-path ./dist/manifest.json
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Agent Instruction Engineering
|
### Environment Configuration
|
||||||
|
|
||||||
### 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:
|
|
||||||
|
|
||||||
|
#### Development Environment
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"conversation_starters": [
|
"name": "${DEV_AGENT_NAME}",
|
||||||
{
|
"description": "Development version: ${AGENT_DESCRIPTION}",
|
||||||
"text": "Analyze last quarter's sales performance by region"
|
"instructions": "${AGENT_INSTRUCTIONS}",
|
||||||
},
|
"capabilities": ["${REQUIRED_CAPABILITIES}"]
|
||||||
{
|
|
||||||
"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"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Guidelines:**
|
#### Production Environment
|
||||||
- **Specific and actionable**: Each starter should trigger a specific workflow
|
```json
|
||||||
- **Capability demonstration**: Show what the agent can do
|
{
|
||||||
- **User language**: Use terminology familiar to target users
|
"name": "${PROD_AGENT_NAME}",
|
||||||
- **Varied complexity**: Include simple and complex examples
|
"description": "${AGENT_DESCRIPTION}",
|
||||||
- **Business value**: Focus on outcomes users care about
|
"instructions": "${AGENT_INSTRUCTIONS}",
|
||||||
|
"capabilities": ["${PRODUCTION_CAPABILITIES}"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
## Microsoft 365 Agents Toolkit Workflow
|
## Development Best Practices
|
||||||
|
|
||||||
### Development Environment Setup
|
### 1. Schema Validation
|
||||||
1. **Install Prerequisites**:
|
```typescript
|
||||||
```bash
|
// Validate against v1.5 schema
|
||||||
# Install Teams Toolkit CLI
|
const schema = await fetch('https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json');
|
||||||
npm install -g @microsoft/teamsapp-cli
|
const validator = new JSONSchema(schema);
|
||||||
|
const isValid = validator.validate(agentManifest);
|
||||||
|
```
|
||||||
|
|
||||||
# Verify installation
|
### 2. Character Limit Management
|
||||||
teamsapp --version
|
```typescript
|
||||||
```
|
// Validation helper functions
|
||||||
|
function validateName(name: string): boolean {
|
||||||
|
return name.length > 0 && name.length <= 100;
|
||||||
|
}
|
||||||
|
|
||||||
2. **VS Code Extension Setup**:
|
function validateDescription(description: string): boolean {
|
||||||
- Install Microsoft 365 Agents Toolkit extension
|
return description.length > 0 && description.length <= 1000;
|
||||||
- Configure workspace settings for declarative agents
|
}
|
||||||
- Set up debugging configuration
|
|
||||||
|
|
||||||
3. **Project Initialization**:
|
function validateInstructions(instructions: string): boolean {
|
||||||
```bash
|
return instructions.length > 0 && instructions.length <= 8000;
|
||||||
# Create new declarative agent project
|
}
|
||||||
teamsapp new declarative-agent --name "MyBusinessAgent"
|
```
|
||||||
|
|
||||||
# Initialize TypeSpec development
|
### 3. Capability Selection Strategy
|
||||||
npm install @typespec/compiler @microsoft/declarative-agent-manifest
|
- **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
|
## Agents Playground Testing
|
||||||
1. **Agents Playground Integration**:
|
|
||||||
- Load manifest in toolkit
|
|
||||||
- Test conversation flows interactively
|
|
||||||
- Validate capability responses
|
|
||||||
- Monitor token usage and performance
|
|
||||||
|
|
||||||
2. **Environment Configuration**:
|
### Local Testing Setup
|
||||||
```json
|
```bash
|
||||||
{
|
# Start Agents Playground
|
||||||
"environments": {
|
npm install -g @microsoft/agents-playground
|
||||||
"development": {
|
agents-playground start --manifest=./agent.json
|
||||||
"manifest_path": "./manifests/dev-manifest.json",
|
```
|
||||||
"test_scenarios": "./test-data/dev-scenarios.json",
|
|
||||||
"mock_data": true
|
### 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": {
|
"description": {
|
||||||
"manifest_path": "./manifests/staging-manifest.json",
|
"en-US": "Provides financial analysis and insights",
|
||||||
"test_scenarios": "./test-data/staging-scenarios.json",
|
"es-ES": "Proporciona análisis e insights financieros",
|
||||||
"integration_testing": true
|
"fr-FR": "Fournit des analyses et insights financiers"
|
||||||
},
|
|
||||||
"production": {
|
|
||||||
"manifest_path": "./manifests/prod-manifest.json",
|
|
||||||
"monitoring_enabled": true,
|
|
||||||
"performance_tracking": true
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
```
|
||||||
```
|
|
||||||
|
|
||||||
3. **Debugging and Troubleshooting**:
|
## Monitoring & Analytics
|
||||||
```typescript
|
|
||||||
interface DebuggingConfig {
|
|
||||||
log_level: "debug" | "info" | "warn" | "error";
|
|
||||||
trace_capability_calls: boolean;
|
|
||||||
monitor_token_usage: boolean;
|
|
||||||
validate_responses: boolean;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Performance Optimization
|
### Performance Metrics
|
||||||
1. **Token Usage Monitoring**:
|
- Response time per capability
|
||||||
```typescript
|
- User engagement with conversation starters
|
||||||
interface TokenUsageMetrics {
|
- Error rates and failure patterns
|
||||||
instruction_tokens: number;
|
- Capability utilization statistics
|
||||||
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:
|
|
||||||
|
|
||||||
|
### Logging Strategy
|
||||||
```typescript
|
```typescript
|
||||||
describe('Sales Analysis Agent', () => {
|
// Structured logging for agent interactions
|
||||||
test('validates manifest schema compliance', () => {
|
const log = {
|
||||||
const manifest = loadManifest('./dist/manifest.json');
|
timestamp: new Date().toISOString(),
|
||||||
expect(validateSchema(manifest)).toBe(true);
|
agentName: "MyAgent",
|
||||||
});
|
version: "1.2.0",
|
||||||
|
userId: "user123",
|
||||||
test('respects character limits', () => {
|
capability: "WebSearch",
|
||||||
const manifest = loadManifest('./dist/manifest.json');
|
responseTime: 1250,
|
||||||
expect(manifest.name.length).toBeLessThanOrEqual(100);
|
success: true
|
||||||
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);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Integration Testing
|
## Security & Compliance
|
||||||
Test capability interactions:
|
|
||||||
|
|
||||||
```typescript
|
### Data Privacy
|
||||||
describe('Capability Integration', () => {
|
- Implement proper data handling for sensitive information
|
||||||
test('function capability responds correctly', async () => {
|
- Ensure compliance with GDPR, CCPA, and organizational policies
|
||||||
const response = await testCapability('Function', {
|
- Use appropriate access controls for enterprise capabilities
|
||||||
function_name: 'analyze_sales_data',
|
|
||||||
parameters: { time_period: 'last_quarter', metrics: ['revenue'] }
|
|
||||||
});
|
|
||||||
expect(response.success).toBe(true);
|
|
||||||
expect(response.data).toBeDefined();
|
|
||||||
});
|
|
||||||
|
|
||||||
test('graph capability handles authentication', async () => {
|
### Security Considerations
|
||||||
const response = await testCapability('MicrosoftGraph', {
|
- Validate all inputs and outputs
|
||||||
endpoint: '/me',
|
- Implement rate limiting and abuse prevention
|
||||||
method: 'GET'
|
- Monitor for suspicious activity patterns
|
||||||
});
|
- Regular security audits and updates
|
||||||
expect(response.authenticated).toBe(true);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Performance Testing
|
## Troubleshooting
|
||||||
Validate performance requirements:
|
|
||||||
|
|
||||||
```typescript
|
### Common Issues
|
||||||
describe('Performance Requirements', () => {
|
1. **Schema Validation Errors**: Check character limits and required fields
|
||||||
test('response time under 3 seconds', async () => {
|
2. **Capability Conflicts**: Verify capability combinations are supported
|
||||||
const startTime = Date.now();
|
3. **Performance Issues**: Monitor response times and optimize instructions
|
||||||
const response = await sendMessage('Analyze sales data');
|
4. **Deployment Failures**: Validate environment configuration and permissions
|
||||||
const responseTime = Date.now() - startTime;
|
|
||||||
expect(responseTime).toBeLessThan(3000);
|
|
||||||
});
|
|
||||||
|
|
||||||
test('token usage within limits', async () => {
|
### Debug Tools
|
||||||
const response = await sendMessage('Generate quarterly report');
|
- TypeSpec compiler diagnostics
|
||||||
expect(response.token_usage.total).toBeLessThan(4000);
|
- Agents Playground debugging
|
||||||
});
|
- Microsoft 365 Agents Toolkit logs
|
||||||
});
|
- Schema validation utilities
|
||||||
```
|
|
||||||
|
|
||||||
## Production Deployment Guidelines
|
This comprehensive guide ensures robust, scalable, and maintainable Microsoft 365 Copilot declarative agents with full TypeSpec and Microsoft 365 Agents Toolkit integration.
|
||||||
|
|
||||||
### 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.
|
|
||||||
Loading…
x
Reference in New Issue
Block a user