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