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
|
||||||
|
// 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);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Character Limit Management
|
||||||
|
```typescript
|
||||||
|
// Validation helper functions
|
||||||
|
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;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
|
## Agents Playground Testing
|
||||||
|
|
||||||
|
### Local Testing Setup
|
||||||
```bash
|
```bash
|
||||||
# Install Teams Toolkit CLI
|
# Start Agents Playground
|
||||||
npm install -g @microsoft/teamsapp-cli
|
npm install -g @microsoft/agents-playground
|
||||||
|
agents-playground start --manifest=./agent.json
|
||||||
# Verify installation
|
|
||||||
teamsapp --version
|
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **VS Code Extension Setup**:
|
### Testing Scenarios
|
||||||
- Install Microsoft 365 Agents Toolkit extension
|
1. **Capability Validation**: Test each declared capability
|
||||||
- Configure workspace settings for declarative agents
|
2. **Conversation Flow**: Validate conversation starters
|
||||||
- Set up debugging configuration
|
3. **Error Handling**: Test invalid inputs and edge cases
|
||||||
|
4. **Performance**: Measure response times and reliability
|
||||||
|
|
||||||
3. **Project Initialization**:
|
## Deployment & Lifecycle Management
|
||||||
```bash
|
|
||||||
# Create new declarative agent project
|
|
||||||
teamsapp new declarative-agent --name "MyBusinessAgent"
|
|
||||||
|
|
||||||
# Initialize TypeSpec development
|
### 1. Development Lifecycle
|
||||||
npm install @typespec/compiler @microsoft/declarative-agent-manifest
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
A[TypeSpec Definition] --> B[JSON Compilation]
|
||||||
|
B --> C[Local Testing]
|
||||||
|
C --> D[Validation]
|
||||||
|
D --> E[Staging Deployment]
|
||||||
|
E --> F[Production Release]
|
||||||
```
|
```
|
||||||
|
|
||||||
### Local Development and Testing
|
### 2. Version Management
|
||||||
1. **Agents Playground Integration**:
|
|
||||||
- Load manifest in toolkit
|
|
||||||
- Test conversation flows interactively
|
|
||||||
- Validate capability responses
|
|
||||||
- Monitor token usage and performance
|
|
||||||
|
|
||||||
2. **Environment Configuration**:
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"environments": {
|
"name": "MyAgent v1.2.0",
|
||||||
"development": {
|
"description": "Production agent with enhanced capabilities",
|
||||||
"manifest_path": "./manifests/dev-manifest.json",
|
"version": "v1.5",
|
||||||
"test_scenarios": "./test-data/dev-scenarios.json",
|
"metadata": {
|
||||||
"mock_data": true
|
"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
|
||||||
|
|
||||||
|
### Performance Metrics
|
||||||
|
- Response time per capability
|
||||||
|
- User engagement with conversation starters
|
||||||
|
- Error rates and failure patterns
|
||||||
|
- Capability utilization statistics
|
||||||
|
|
||||||
|
### Logging Strategy
|
||||||
```typescript
|
```typescript
|
||||||
interface DebuggingConfig {
|
// Structured logging for agent interactions
|
||||||
log_level: "debug" | "info" | "warn" | "error";
|
const log = {
|
||||||
trace_capability_calls: boolean;
|
timestamp: new Date().toISOString(),
|
||||||
monitor_token_usage: boolean;
|
agentName: "MyAgent",
|
||||||
validate_responses: boolean;
|
version: "1.2.0",
|
||||||
}
|
userId: "user123",
|
||||||
|
capability: "WebSearch",
|
||||||
|
responseTime: 1250,
|
||||||
|
success: true
|
||||||
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
### Performance Optimization
|
## Security & Compliance
|
||||||
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**:
|
### Data Privacy
|
||||||
- Capability ordering optimization
|
- Implement proper data handling for sensitive information
|
||||||
- Parallel capability execution where possible
|
- Ensure compliance with GDPR, CCPA, and organizational policies
|
||||||
- Caching strategies for repeated queries
|
- Use appropriate access controls for enterprise capabilities
|
||||||
- Connection pooling for external APIs
|
|
||||||
|
|
||||||
3. **Memory Management**:
|
### Security Considerations
|
||||||
- Conversation context optimization
|
- Validate all inputs and outputs
|
||||||
- State management best practices
|
- Implement rate limiting and abuse prevention
|
||||||
- Resource cleanup procedures
|
- Monitor for suspicious activity patterns
|
||||||
|
- Regular security audits and updates
|
||||||
|
|
||||||
## Security and Compliance Guidelines
|
## Troubleshooting
|
||||||
|
|
||||||
### Authentication and Authorization
|
### Common Issues
|
||||||
1. **OAuth 2.0 Implementation**:
|
1. **Schema Validation Errors**: Check character limits and required fields
|
||||||
```json
|
2. **Capability Conflicts**: Verify capability combinations are supported
|
||||||
{
|
3. **Performance Issues**: Monitor response times and optimize instructions
|
||||||
"authentication": {
|
4. **Deployment Failures**: Validate environment configuration and permissions
|
||||||
"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**:
|
### Debug Tools
|
||||||
- Request only necessary permissions
|
- TypeSpec compiler diagnostics
|
||||||
- Document scope justification
|
- Agents Playground debugging
|
||||||
- Implement permission checking
|
- Microsoft 365 Agents Toolkit logs
|
||||||
- Handle scope denial gracefully
|
- Schema validation utilities
|
||||||
|
|
||||||
### Data Protection
|
This comprehensive guide ensures robust, scalable, and maintainable Microsoft 365 Copilot declarative agents with full TypeSpec and Microsoft 365 Agents Toolkit integration.
|
||||||
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:
|
|
||||||
|
|
||||||
```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);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Integration Testing
|
|
||||||
Test capability interactions:
|
|
||||||
|
|
||||||
```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();
|
|
||||||
});
|
|
||||||
|
|
||||||
test('graph capability handles authentication', async () => {
|
|
||||||
const response = await testCapability('MicrosoftGraph', {
|
|
||||||
endpoint: '/me',
|
|
||||||
method: 'GET'
|
|
||||||
});
|
|
||||||
expect(response.authenticated).toBe(true);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### Performance Testing
|
|
||||||
Validate performance requirements:
|
|
||||||
|
|
||||||
```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);
|
|
||||||
});
|
|
||||||
|
|
||||||
test('token usage within limits', async () => {
|
|
||||||
const response = await sendMessage('Generate quarterly report');
|
|
||||||
expect(response.token_usage.total).toBeLessThan(4000);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
Loading…
x
Reference in New Issue
Block a user