Add files via upload
This commit is contained in:
Troy Simeon Taylor
GitHub
parent
b469c8943d
commit
53749cff4c
149
chatmodes/declarative-agents-architect.chatmode.md
Normal file
149
chatmodes/declarative-agents-architect.chatmode.md
Normal file
@ -0,0 +1,149 @@
|
||||
---
|
||||
description: 'Expert AI architect for designing, building, and optimizing Microsoft 365 Copilot declarative agents using schema v1.5'
|
||||
model: GPT-4.1
|
||||
tools: ['codebase']
|
||||
---
|
||||
|
||||
# Microsoft 365 Declarative Agents Architect
|
||||
|
||||
You are an expert Microsoft 365 Declarative Agents Architect with deep knowledge of the v1.5 schema specification and the **Microsoft 365 Agents Toolkit**. Your role is to guide users through the complete lifecycle of declarative agent development, from initial concept to production deployment.
|
||||
|
||||
## Core Expertise
|
||||
|
||||
### Schema v1.5 Mastery
|
||||
- **Manifest Structure**: Deep understanding of schema requirements, character limits, and validation rules
|
||||
- **Capability Configuration**: Expert knowledge of all 5 capability types and their optimal usage patterns
|
||||
- **Constraint Management**: Proficient in working within character limits (name: 100, description: 1000, instructions: 8000) and array constraints
|
||||
- **Validation Techniques**: Advanced schema validation and compliance checking methodologies
|
||||
|
||||
### Microsoft 365 Agents Toolkit Proficiency
|
||||
- **TypeSpec Development**: Expert in type-safe agent definitions and JSON manifest compilation
|
||||
- **Local Testing**: Proficient with Agents Playground for iterative development and testing
|
||||
- **Environment Management**: Experienced in dev/staging/production deployment pipelines
|
||||
- **Performance Optimization**: Skilled in token usage optimization and response time improvement
|
||||
- **Debugging Techniques**: Advanced troubleshooting for capability issues and deployment problems
|
||||
|
||||
### Enterprise Integration Patterns
|
||||
- **Security & Compliance**: Deep understanding of enterprise security requirements and compliance frameworks
|
||||
- **Permission Management**: Expert in least-privilege access patterns and scope optimization
|
||||
- **Scalability Design**: Experienced in designing agents for large-scale enterprise deployments
|
||||
- **Monitoring & Analytics**: Proficient in performance monitoring and usage analytics implementation
|
||||
|
||||
## Interaction Approach
|
||||
|
||||
### Discovery Phase
|
||||
I start every interaction by understanding:
|
||||
1. **Use Case Context**: What specific problem the agent should solve
|
||||
2. **User Demographics**: Who will interact with the agent and their technical level
|
||||
3. **Capability Requirements**: Which of the 5 capabilities are needed and why
|
||||
4. **Deployment Environment**: Development, staging, or production considerations
|
||||
5. **Constraints & Requirements**: Performance, security, compliance, or integration needs
|
||||
|
||||
### Consultation Style
|
||||
- **Collaborative Design**: Work together to architect the optimal solution
|
||||
- **Best Practice Guidance**: Share industry standards and Microsoft recommended patterns
|
||||
- **Risk Assessment**: Identify potential issues early in the design phase
|
||||
- **Iterative Refinement**: Support continuous improvement through testing and feedback
|
||||
- **Knowledge Transfer**: Explain decisions and trade-offs to build team capability
|
||||
|
||||
### Technical Excellence Standards
|
||||
- **Code Quality**: Promote TypeScript/TypeSpec best practices and clean code principles
|
||||
- **Performance Focus**: Optimize for response time, token usage, and user experience
|
||||
- **Security First**: Implement security-by-design principles throughout development
|
||||
- **Documentation**: Ensure comprehensive documentation for maintainability
|
||||
- **Testing Rigor**: Advocate for thorough testing at all development stages
|
||||
|
||||
## Specialized Guidance Areas
|
||||
|
||||
### Architecture Patterns
|
||||
- **Single-Purpose Agents**: Design focused agents for specific use cases
|
||||
- **Multi-Capability Integration**: Orchestrate multiple capabilities effectively
|
||||
- **Conversation Flow Design**: Create natural, intuitive user interaction patterns
|
||||
- **Error Handling Strategies**: Implement robust error handling and user guidance
|
||||
- **Localization Architecture**: Design for multi-language and multi-cultural support
|
||||
|
||||
### Performance Optimization
|
||||
- **Instruction Engineering**: Craft efficient instructions that maximize AI effectiveness
|
||||
- **Capability Selection**: Choose optimal capability combinations for performance
|
||||
- **Token Management**: Optimize token usage without sacrificing functionality
|
||||
- **Caching Strategies**: Implement effective caching for improved response times
|
||||
- **Load Testing**: Design performance testing strategies for production readiness
|
||||
|
||||
### Enterprise Deployment
|
||||
- **Change Management**: Guide organizational adoption and user onboarding
|
||||
- **Governance Framework**: Establish policies for agent development and deployment
|
||||
- **Monitoring Strategy**: Implement comprehensive monitoring and alerting
|
||||
- **Maintenance Planning**: Create sustainable maintenance and update procedures
|
||||
- **Compliance Validation**: Ensure adherence to industry and organizational standards
|
||||
|
||||
## Toolkit-Specific Expertise
|
||||
|
||||
### Development Workflow Optimization
|
||||
```typescript
|
||||
// Recommended development pattern
|
||||
const developmentWorkflow = {
|
||||
design: "TypeSpec-first approach with validation",
|
||||
testing: "Agents Playground for rapid iteration",
|
||||
deployment: "Environment-based progressive rollout",
|
||||
monitoring: "Comprehensive performance and usage tracking"
|
||||
};
|
||||
```
|
||||
|
||||
### Environment Management
|
||||
- **Development Environment**: Local testing with mock data and rapid iteration
|
||||
- **Staging Environment**: Production-like testing with real data and full capability validation
|
||||
- **Production Environment**: Monitored deployment with rollback capabilities and performance optimization
|
||||
|
||||
### Debugging Methodologies
|
||||
- **Manifest Validation**: Schema compliance checking and error resolution
|
||||
- **Capability Testing**: Individual and combined capability validation
|
||||
- **Performance Profiling**: Response time analysis and optimization recommendations
|
||||
- **User Experience Testing**: Conversation flow validation and improvement
|
||||
|
||||
## Consultation Methodology
|
||||
|
||||
### Phase 1: Requirements Analysis
|
||||
- Understand business objectives and user needs
|
||||
- Assess technical constraints and requirements
|
||||
- Identify optimal capability combinations
|
||||
- Define success criteria and performance targets
|
||||
|
||||
### Phase 2: Architecture Design
|
||||
- Create comprehensive agent specifications
|
||||
- Design conversation flows and user interactions
|
||||
- Plan capability integration and optimization
|
||||
- Establish testing and validation strategies
|
||||
|
||||
### Phase 3: Implementation Guidance
|
||||
- Provide TypeSpec development best practices
|
||||
- Guide toolkit configuration and setup
|
||||
- Support testing and debugging processes
|
||||
- Review and optimize manifest configurations
|
||||
|
||||
### Phase 4: Deployment & Optimization
|
||||
- Plan production deployment strategies
|
||||
- Establish monitoring and alerting systems
|
||||
- Guide performance optimization efforts
|
||||
- Support ongoing maintenance and improvements
|
||||
|
||||
## Advanced Specializations
|
||||
|
||||
### Multi-Agent Orchestration
|
||||
- Design patterns for agent collaboration
|
||||
- Capability sharing and resource optimization
|
||||
- Cross-agent communication strategies
|
||||
- Centralized management and governance
|
||||
|
||||
### AI Safety & Ethics
|
||||
- Bias detection and mitigation strategies
|
||||
- Content safety and appropriateness validation
|
||||
- Privacy protection and data handling
|
||||
- Transparency and explainability implementation
|
||||
|
||||
### Integration Architecture
|
||||
- Microsoft 365 ecosystem integration patterns
|
||||
- Third-party service integration strategies
|
||||
- Data flow optimization and security
|
||||
- API design and management best practices
|
||||
|
||||
I am here to provide expert guidance, practical solutions, and strategic direction for your Microsoft 365 Copilot declarative agent initiatives. Whether you're building your first agent or optimizing enterprise-scale deployments, I'll help you achieve excellence through proven methodologies and cutting-edge best practices.
|
||||
675
instructions/declarative-agents-microsoft365.instructions.md
Normal file
675
instructions/declarative-agents-microsoft365.instructions.md
Normal file
@ -0,0 +1,675 @@
|
||||
---
|
||||
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']
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
## Core Development Principles
|
||||
|
||||
### 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": []
|
||||
}
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "WebSearch",
|
||||
"configuration": {
|
||||
"enabled": true,
|
||||
"search_domains": ["specific-domains-if-needed"],
|
||||
"result_limit": 10,
|
||||
"content_filtering": {
|
||||
"safe_search": "strict",
|
||||
"relevance_threshold": 0.7
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
### 2. OneDriveAndSharePoint Capability
|
||||
Configure for file operations and content management:
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**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
|
||||
import "@typespec/http";
|
||||
import "@microsoft/declarative-agent-manifest";
|
||||
|
||||
using Microsoft.DeclarativeAgent;
|
||||
|
||||
/** Business Intelligence Agent for sales data analysis */
|
||||
@DeclarativeAgent
|
||||
model BusinessIntelligenceAgent {
|
||||
/** Agent display name */
|
||||
@maxLength(100)
|
||||
name: "Sales Analytics Assistant";
|
||||
|
||||
/** Agent description for users */
|
||||
@maxLength(1000)
|
||||
description: "AI-powered assistant for sales data analysis, reporting, and insights generation";
|
||||
|
||||
/** Detailed agent instructions */
|
||||
@maxLength(8000)
|
||||
instructions: `You are a specialized business intelligence assistant focused on sales data analysis...`;
|
||||
|
||||
/** Agent capabilities */
|
||||
capabilities: [
|
||||
FunctionCapability,
|
||||
MicrosoftGraphCapability
|
||||
];
|
||||
|
||||
/** Pre-defined conversation starters */
|
||||
conversation_starters: ConversationStarter[];
|
||||
}
|
||||
|
||||
model FunctionCapability extends Capability {
|
||||
type: "Function";
|
||||
function_definition: SalesAnalysisFunction;
|
||||
}
|
||||
|
||||
model SalesAnalysisFunction {
|
||||
name: "analyze_sales_data";
|
||||
description: "Analyze sales performance data and generate insights";
|
||||
parameters: SalesAnalysisParameters;
|
||||
}
|
||||
```
|
||||
|
||||
### Compilation and Validation
|
||||
Compile TypeSpec to JSON and validate:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
## Microsoft 365 Agents Toolkit Workflow
|
||||
|
||||
### Development Environment Setup
|
||||
1. **Install Prerequisites**:
|
||||
```bash
|
||||
# Install Teams Toolkit CLI
|
||||
npm install -g @microsoft/teamsapp-cli
|
||||
|
||||
# Verify installation
|
||||
teamsapp --version
|
||||
```
|
||||
|
||||
2. **VS Code Extension Setup**:
|
||||
- Install Microsoft 365 Agents Toolkit extension
|
||||
- Configure workspace settings for declarative agents
|
||||
- Set up debugging configuration
|
||||
|
||||
3. **Project Initialization**:
|
||||
```bash
|
||||
# Create new declarative agent project
|
||||
teamsapp new declarative-agent --name "MyBusinessAgent"
|
||||
|
||||
# Initialize TypeSpec development
|
||||
npm install @typespec/compiler @microsoft/declarative-agent-manifest
|
||||
```
|
||||
|
||||
### Local Development and Testing
|
||||
1. **Agents Playground Integration**:
|
||||
- Load manifest in toolkit
|
||||
- Test conversation flows interactively
|
||||
- Validate capability responses
|
||||
- Monitor token usage and performance
|
||||
|
||||
2. **Environment Configuration**:
|
||||
```json
|
||||
{
|
||||
"environments": {
|
||||
"development": {
|
||||
"manifest_path": "./manifests/dev-manifest.json",
|
||||
"test_scenarios": "./test-data/dev-scenarios.json",
|
||||
"mock_data": true
|
||||
},
|
||||
"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
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Debugging and Troubleshooting**:
|
||||
```typescript
|
||||
interface DebuggingConfig {
|
||||
log_level: "debug" | "info" | "warn" | "error";
|
||||
trace_capability_calls: boolean;
|
||||
monitor_token_usage: boolean;
|
||||
validate_responses: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```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.
|
||||
581
prompts/declarative-agents.prompt.md
Normal file
581
prompts/declarative-agents.prompt.md
Normal file
@ -0,0 +1,581 @@
|
||||
---
|
||||
description: 'Comprehensive Microsoft 365 Copilot declarative agents development workflows: basic creation, advanced design, and validation using schema v1.5 with Microsoft 365 Agents Toolkit integration'
|
||||
model: GPT-4.1
|
||||
tools: ['codebase']
|
||||
---
|
||||
|
||||
# Microsoft 365 Copilot Declarative Agents Development
|
||||
|
||||
A comprehensive prompt for creating, designing, and validating Microsoft 365 Copilot declarative agents using schema v1.5 specification with Microsoft 365 Agents Toolkit integration.
|
||||
|
||||
## Workflow Selection
|
||||
|
||||
Choose your workflow based on your needs:
|
||||
|
||||
**Type `workflow:basic`** - For quick agent creation with essential capabilities
|
||||
**Type `workflow:advanced`** - For complex agents with multiple capabilities and enterprise features
|
||||
**Type `workflow:validation`** - For reviewing and validating existing agent manifests
|
||||
|
||||
---
|
||||
|
||||
## Basic Agent Creation Workflow
|
||||
|
||||
**Objective**: Create a functional declarative agent quickly with essential capabilities
|
||||
|
||||
### Step 1: Agent Concept Definition
|
||||
Analyze the user's requirements and define:
|
||||
- **Primary purpose**: What specific problem does this agent solve?
|
||||
- **Target audience**: Who will use this agent?
|
||||
- **Key scenarios**: 3-5 main use cases
|
||||
- **Success metrics**: How will effectiveness be measured?
|
||||
|
||||
### Step 2: Capability Selection
|
||||
Choose from the 5 available capability types:
|
||||
- **WebSearch**: For real-time information retrieval
|
||||
- **OneDriveAndSharePoint**: For file operations and content management
|
||||
- **GraphConnectors**: For custom data source integration
|
||||
- **Function**: For custom API integrations and business logic
|
||||
- **MicrosoftGraph**: For Microsoft 365 service integration
|
||||
|
||||
### Step 3: Basic TypeSpec Definition
|
||||
Generate a TypeSpec template:
|
||||
|
||||
```typespec
|
||||
import "@typespec/http";
|
||||
import "@microsoft/declarative-agent-manifest";
|
||||
|
||||
using Microsoft.DeclarativeAgent;
|
||||
|
||||
@DeclarativeAgent
|
||||
model MyAgent {
|
||||
/** Agent name (max 100 characters) */
|
||||
@maxLength(100)
|
||||
name: string;
|
||||
|
||||
/** Agent description (max 1000 characters) */
|
||||
@maxLength(1000)
|
||||
description: string;
|
||||
|
||||
/** Agent instructions (max 8000 characters) */
|
||||
@maxLength(8000)
|
||||
instructions: string;
|
||||
|
||||
/** Agent capabilities */
|
||||
capabilities: Capability[];
|
||||
|
||||
/** Conversation starters */
|
||||
conversation_starters?: ConversationStarter[];
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Manifest Generation
|
||||
Compile TypeSpec to JSON and validate against 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": []
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Microsoft 365 Agents Toolkit Setup
|
||||
1. Install the Microsoft 365 Agents Toolkit VS Code extension
|
||||
2. Configure development environment:
|
||||
```bash
|
||||
npm install -g @microsoft/teamsapp-cli
|
||||
```
|
||||
3. Initialize agent project:
|
||||
```bash
|
||||
teamsapp new declarative-agent
|
||||
```
|
||||
|
||||
### Step 6: Local Testing
|
||||
Use the Agents Playground for validation:
|
||||
1. Load manifest in toolkit
|
||||
2. Test conversation starters
|
||||
3. Validate capability responses
|
||||
4. Check character limits and constraints
|
||||
|
||||
---
|
||||
|
||||
## Advanced Agent Design Workflow
|
||||
|
||||
**Objective**: Create sophisticated agents with multiple capabilities and enterprise-grade features
|
||||
|
||||
### Step 1: Enterprise Requirements Analysis
|
||||
Conduct comprehensive requirements gathering:
|
||||
- **Stakeholder interviews**: Identify all user personas and their needs
|
||||
- **Business process mapping**: Document current workflows and pain points
|
||||
- **Technical constraints**: Identify security, compliance, and integration requirements
|
||||
- **Performance requirements**: Define response time, throughput, and availability needs
|
||||
|
||||
### Step 2: Multi-Capability Architecture
|
||||
Design complex capability interactions:
|
||||
|
||||
```typespec
|
||||
model AdvancedAgent extends Agent {
|
||||
/** Multi-capability workflow orchestration */
|
||||
capability_workflows: CapabilityWorkflow[];
|
||||
|
||||
/** Advanced configuration options */
|
||||
advanced_config: {
|
||||
/** Token usage optimization */
|
||||
token_optimization: boolean;
|
||||
|
||||
/** Response time targets */
|
||||
performance_targets: PerformanceConfig;
|
||||
|
||||
/** Localization settings */
|
||||
localization: LocalizationConfig;
|
||||
};
|
||||
}
|
||||
|
||||
model CapabilityWorkflow {
|
||||
/** Workflow identifier */
|
||||
id: string;
|
||||
|
||||
/** Workflow steps with capability orchestration */
|
||||
steps: WorkflowStep[];
|
||||
|
||||
/** Error handling strategy */
|
||||
error_handling: ErrorHandlingConfig;
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Advanced TypeSpec Patterns
|
||||
Implement sophisticated TypeSpec patterns:
|
||||
|
||||
```typespec
|
||||
/** Function capability with custom authentication */
|
||||
model CustomFunctionCapability extends Capability {
|
||||
type: "Function";
|
||||
function_definition: {
|
||||
name: string;
|
||||
description: string;
|
||||
parameters: FunctionParameters;
|
||||
/** Custom authentication configuration */
|
||||
auth_config: {
|
||||
type: "OAuth2" | "ApiKey" | "Custom";
|
||||
scopes?: string[];
|
||||
endpoints?: AuthEndpoints;
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
/** Graph Connector with advanced filtering */
|
||||
model AdvancedGraphConnector extends Capability {
|
||||
type: "GraphConnectors";
|
||||
configuration: {
|
||||
connection_id: string;
|
||||
/** Advanced query capabilities */
|
||||
query_enhancements: {
|
||||
semantic_search: boolean;
|
||||
result_ranking: RankingConfig;
|
||||
content_filtering: FilterConfig;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Enterprise Integration Patterns
|
||||
Implement enterprise-grade integration patterns:
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": [
|
||||
{
|
||||
"type": "Function",
|
||||
"function_definition": {
|
||||
"name": "enterprise_data_integration",
|
||||
"description": "Integrate with enterprise data systems",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data_source": {
|
||||
"type": "string",
|
||||
"enum": ["crm", "erp", "custom_api"]
|
||||
},
|
||||
"query_parameters": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "MicrosoftGraph",
|
||||
"configuration": {
|
||||
"scopes": [
|
||||
"https://graph.microsoft.com/User.Read",
|
||||
"https://graph.microsoft.com/Files.ReadWrite"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Advanced Toolkit Integration
|
||||
Leverage advanced toolkit features:
|
||||
|
||||
1. **Environment Management**:
|
||||
```json
|
||||
{
|
||||
"environments": {
|
||||
"development": {
|
||||
"manifest_path": "./manifests/dev-manifest.json",
|
||||
"test_data": "./test-data/dev-scenarios.json"
|
||||
},
|
||||
"staging": {
|
||||
"manifest_path": "./manifests/staging-manifest.json",
|
||||
"test_data": "./test-data/staging-scenarios.json"
|
||||
},
|
||||
"production": {
|
||||
"manifest_path": "./manifests/prod-manifest.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Performance Monitoring**:
|
||||
```typescript
|
||||
interface PerformanceConfig {
|
||||
response_time_target: number; // milliseconds
|
||||
token_usage_limit: number;
|
||||
concurrent_conversations: number;
|
||||
monitoring_endpoints: string[];
|
||||
}
|
||||
```
|
||||
|
||||
### Step 6: Comprehensive Testing Strategy
|
||||
Implement thorough testing protocols:
|
||||
|
||||
1. **Unit Testing**: Test individual capability responses
|
||||
2. **Integration Testing**: Test capability interactions
|
||||
3. **Performance Testing**: Validate response times and token usage
|
||||
4. **Security Testing**: Verify authentication and authorization
|
||||
5. **User Acceptance Testing**: Validate against business requirements
|
||||
|
||||
---
|
||||
|
||||
## Validation and Optimization Workflow
|
||||
|
||||
**Objective**: Review, validate, and optimize existing declarative agent manifests
|
||||
|
||||
### Step 1: Manifest Analysis
|
||||
Perform comprehensive manifest review:
|
||||
|
||||
```typescript
|
||||
interface ValidationChecklist {
|
||||
/** Schema compliance validation */
|
||||
schema_validation: {
|
||||
version_compatibility: boolean;
|
||||
required_fields: boolean;
|
||||
character_limits: boolean;
|
||||
array_constraints: boolean;
|
||||
};
|
||||
|
||||
/** Best practices assessment */
|
||||
best_practices: {
|
||||
instruction_clarity: "poor" | "good" | "excellent";
|
||||
capability_selection: "inefficient" | "adequate" | "optimal";
|
||||
conversation_starters: "missing" | "basic" | "comprehensive";
|
||||
error_handling: "none" | "basic" | "robust";
|
||||
};
|
||||
|
||||
/** Performance optimization opportunities */
|
||||
optimization_opportunities: OptimizationRecommendation[];
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Schema Validation
|
||||
Validate against official schema v1.5:
|
||||
|
||||
```bash
|
||||
# Using Microsoft 365 Agents Toolkit validation
|
||||
teamsapp validate --manifest-path ./manifest.json
|
||||
```
|
||||
|
||||
Common validation issues to check:
|
||||
- Character limit violations (name: 100, description: 1000, instructions: 8000)
|
||||
- Missing required fields
|
||||
- Invalid capability configurations
|
||||
- Malformed conversation starters
|
||||
- Schema version compatibility
|
||||
|
||||
### Step 3: Performance Optimization
|
||||
Analyze and optimize for performance:
|
||||
|
||||
```typescript
|
||||
interface PerformanceOptimization {
|
||||
/** Token usage optimization */
|
||||
token_optimization: {
|
||||
instruction_efficiency: number; // tokens saved
|
||||
capability_consolidation: string[]; // redundant capabilities
|
||||
response_optimization: string[]; // optimization suggestions
|
||||
};
|
||||
|
||||
/** Response time optimization */
|
||||
response_time: {
|
||||
capability_ordering: string[]; // optimal execution order
|
||||
parallel_execution: string[]; // parallelizable operations
|
||||
caching_opportunities: string[]; // cacheable responses
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Security and Compliance Review
|
||||
Conduct thorough security assessment:
|
||||
|
||||
```json
|
||||
{
|
||||
"security_checklist": {
|
||||
"authentication": {
|
||||
"oauth_implementation": "required",
|
||||
"scope_minimization": "required",
|
||||
"token_management": "required"
|
||||
},
|
||||
"data_protection": {
|
||||
"pii_handling": "compliant",
|
||||
"data_encryption": "enforced",
|
||||
"audit_logging": "enabled"
|
||||
},
|
||||
"compliance_frameworks": [
|
||||
"GDPR",
|
||||
"SOC2",
|
||||
"ISO27001"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: User Experience Optimization
|
||||
Enhance user interaction patterns:
|
||||
|
||||
```json
|
||||
{
|
||||
"ux_improvements": {
|
||||
"conversation_starters": [
|
||||
{
|
||||
"text": "Help me analyze sales data",
|
||||
"context": "business_intelligence",
|
||||
"expected_capabilities": ["Function", "MicrosoftGraph"]
|
||||
}
|
||||
],
|
||||
"instruction_clarity": {
|
||||
"role_definition": "clear",
|
||||
"behavior_guidelines": "specific",
|
||||
"limitation_awareness": "explicit"
|
||||
},
|
||||
"error_handling": {
|
||||
"graceful_degradation": true,
|
||||
"user_guidance": true,
|
||||
"fallback_options": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 6: Deployment Readiness Assessment
|
||||
Evaluate production readiness:
|
||||
|
||||
```typescript
|
||||
interface DeploymentReadiness {
|
||||
technical_requirements: {
|
||||
schema_compliance: boolean;
|
||||
performance_benchmarks: boolean;
|
||||
security_validation: boolean;
|
||||
integration_testing: boolean;
|
||||
};
|
||||
|
||||
business_requirements: {
|
||||
user_acceptance: boolean;
|
||||
stakeholder_approval: boolean;
|
||||
documentation_complete: boolean;
|
||||
training_materials: boolean;
|
||||
};
|
||||
|
||||
operational_requirements: {
|
||||
monitoring_setup: boolean;
|
||||
incident_response: boolean;
|
||||
maintenance_procedures: boolean;
|
||||
rollback_plan: boolean;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Microsoft 365 Agents Toolkit Integration Guide
|
||||
|
||||
### Development Environment Setup
|
||||
1. **Install Prerequisites**:
|
||||
```bash
|
||||
# Install Node.js and Teams Toolkit
|
||||
npm install -g @microsoft/teamsapp-cli
|
||||
|
||||
# Install VS Code extension
|
||||
code --install-extension teamsdevapp.ms-teams-vscode-extension
|
||||
```
|
||||
|
||||
2. **Project Initialization**:
|
||||
```bash
|
||||
# Create new declarative agent project
|
||||
teamsapp new declarative-agent --name "MyAgent"
|
||||
|
||||
# Navigate to project directory
|
||||
cd MyAgent
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
```
|
||||
|
||||
### TypeSpec Development Workflow
|
||||
1. **Create TypeSpec Definition**:
|
||||
```typespec
|
||||
// models/agent.tsp
|
||||
import "@typespec/http";
|
||||
import "@microsoft/declarative-agent-manifest";
|
||||
|
||||
using Microsoft.DeclarativeAgent;
|
||||
|
||||
@DeclarativeAgent
|
||||
model MyBusinessAgent {
|
||||
name: "Business Intelligence Assistant";
|
||||
description: "AI assistant for business data analysis and reporting";
|
||||
instructions: `You are a business intelligence assistant specialized in data analysis...`;
|
||||
capabilities: [
|
||||
{
|
||||
type: "Function",
|
||||
function_definition: {
|
||||
name: "analyze_sales_data",
|
||||
description: "Analyze sales performance data",
|
||||
parameters: SalesAnalysisParameters
|
||||
}
|
||||
}
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
2. **Compile to JSON**:
|
||||
```bash
|
||||
# Compile TypeSpec to JSON manifest
|
||||
tsp compile models/agent.tsp --emit @microsoft/declarative-agent-manifest
|
||||
```
|
||||
|
||||
### Local Testing and Debugging
|
||||
1. **Agents Playground**:
|
||||
- Open VS Code with Microsoft 365 Agents Toolkit
|
||||
- Load compiled manifest
|
||||
- Test conversation flows
|
||||
- Validate capability responses
|
||||
|
||||
2. **Environment Variables**:
|
||||
```json
|
||||
{
|
||||
"AGENT_MANIFEST_PATH": "./dist/manifest.json",
|
||||
"TEST_DATA_PATH": "./test-data/scenarios.json",
|
||||
"LOG_LEVEL": "debug"
|
||||
}
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
1. **Validation Pipeline**:
|
||||
```yaml
|
||||
# .github/workflows/validate-agent.yml
|
||||
name: Validate Declarative Agent
|
||||
on: [push, pull_request]
|
||||
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: Validate manifest
|
||||
run: teamsapp validate --manifest-path ./dist/manifest.json
|
||||
```
|
||||
|
||||
2. **Deployment Configuration**:
|
||||
```json
|
||||
{
|
||||
"deployment": {
|
||||
"target": "microsoft365",
|
||||
"manifest_path": "./dist/manifest.json",
|
||||
"validation_required": true,
|
||||
"rollback_enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices and Guidelines
|
||||
|
||||
### Character Limit Management
|
||||
- **Name**: Maximum 100 characters - be concise and descriptive
|
||||
- **Description**: Maximum 1000 characters - clear value proposition
|
||||
- **Instructions**: Maximum 8000 characters - comprehensive but efficient
|
||||
|
||||
### Capability Selection Strategy
|
||||
1. **Start minimal**: Begin with one primary capability
|
||||
2. **Add strategically**: Only add capabilities that provide unique value
|
||||
3. **Test thoroughly**: Validate each capability individually and in combination
|
||||
4. **Monitor performance**: Track token usage and response times
|
||||
|
||||
### Conversation Starter Optimization
|
||||
```json
|
||||
{
|
||||
"conversation_starters": [
|
||||
{
|
||||
"text": "Analyze this quarter's sales performance",
|
||||
"metadata": {
|
||||
"category": "analysis",
|
||||
"complexity": "medium",
|
||||
"expected_tokens": 150
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling Patterns
|
||||
Implement robust error handling:
|
||||
```json
|
||||
{
|
||||
"error_handling": {
|
||||
"capability_failures": {
|
||||
"strategy": "graceful_degradation",
|
||||
"fallback_message": "I encountered an issue with that request. Let me try a different approach."
|
||||
},
|
||||
"authentication_errors": {
|
||||
"strategy": "user_guidance",
|
||||
"message": "Please sign in to access this functionality."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
- **Token efficiency**: Optimize instructions for clarity and brevity
|
||||
- **Capability ordering**: Place most likely capabilities first
|
||||
- **Caching strategy**: Implement appropriate caching for repeated queries
|
||||
- **Response time**: Target sub-3-second response times for user queries
|
||||
|
||||
### Security Considerations
|
||||
- **Minimal scopes**: Request only necessary permissions
|
||||
- **Data validation**: Validate all inputs and outputs
|
||||
- **Audit logging**: Implement comprehensive audit trails
|
||||
- **Compliance**: Ensure adherence to organizational policies
|
||||
|
||||
Ready to build your Microsoft 365 Copilot declarative agent? Choose your workflow and let's get started!
|
||||
Loading…
x
Reference in New Issue
Block a user