Add files via upload

This commit is contained in:
Troy Simeon Taylor 2025-09-11 08:58:49 -04:00 committed by GitHub
parent b154e685da
commit de0be46dee
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -1,581 +1,93 @@
---
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!
---
description: Complete development kit for Microsoft 365 Copilot declarative agents with three comprehensive workflows (basic, advanced, validation), TypeSpec support, and Microsoft 365 Agents Toolkit integration
---
# Microsoft 365 Declarative Agents Development Kit
I'll help you create and develop Microsoft 365 Copilot declarative agents using the latest v1.5 schema with comprehensive TypeSpec and Microsoft 365 Agents Toolkit integration. Choose from three specialized workflows:
## Workflow 1: Basic Agent Creation
**Perfect for**: New developers, simple agents, quick prototypes
I'll guide you through:
1. **Agent Planning**: Define purpose, target users, and core capabilities
2. **Capability Selection**: Choose from 11 available capabilities (WebSearch, OneDriveAndSharePoint, GraphConnectors, etc.)
3. **Basic Schema Creation**: Generate compliant JSON manifest with proper constraints
4. **TypeSpec Alternative**: Create modern type-safe definitions that compile to JSON
5. **Testing Setup**: Configure Agents Playground for local testing
6. **Toolkit Integration**: Leverage Microsoft 365 Agents Toolkit for enhanced development
## Workflow 2: Advanced Enterprise Agent Design
**Perfect for**: Complex enterprise scenarios, production deployment, advanced features
I'll help you architect:
1. **Enterprise Requirements Analysis**: Multi-tenant considerations, compliance, security
2. **Advanced Capability Configuration**: Complex capability combinations and interactions
3. **Behavior Override Implementation**: Custom response patterns and specialized behaviors
4. **Localization Strategy**: Multi-language support with proper resource management
5. **Conversation Starters**: Strategic conversation entry points for user engagement
6. **Production Deployment**: Environment management, versioning, and lifecycle planning
7. **Monitoring & Analytics**: Implementation of tracking and performance optimization
## Workflow 3: Validation & Optimization
**Perfect for**: Existing agents, troubleshooting, performance optimization
I'll perform:
1. **Schema Compliance Validation**: Full v1.5 specification adherence checking
2. **Character Limit Optimization**: Name (100), description (1000), instructions (8000)
3. **Capability Audit**: Verify proper capability configuration and usage
4. **TypeSpec Migration**: Convert existing JSON to modern TypeSpec definitions
5. **Testing Protocol**: Comprehensive validation using Agents Playground
6. **Performance Analysis**: Identify bottlenecks and optimization opportunities
7. **Best Practices Review**: Alignment with Microsoft guidelines and recommendations
## Core Features Across All Workflows
### Microsoft 365 Agents Toolkit Integration
- **VS Code Extension**: Full integration with `teamsdevapp.ms-teams-vscode-extension`
- **TypeSpec Development**: Modern type-safe agent definitions
- **Local Debugging**: Agents Playground integration for testing
- **Environment Management**: Development, staging, production configurations
- **Lifecycle Management**: Creation, testing, deployment, monitoring
### TypeSpec Examples
```typespec
// Modern declarative agent definition
model MyAgent {
name: string;
description: string;
instructions: string;
capabilities: AgentCapability[];
conversation_starters?: ConversationStarter[];
}
```
### JSON Schema v1.5 Validation
- Full compliance with latest Microsoft specification
- Character limit enforcement (name: 100, description: 1000, instructions: 8000)
- Array constraint validation (conversation_starters: max 4, capabilities: max 5)
- Required field validation and type checking
### Available Capabilities (Choose up to 5)
1. **WebSearch**: Internet search functionality
2. **OneDriveAndSharePoint**: File and content access
3. **GraphConnectors**: Enterprise data integration
4. **MicrosoftGraph**: Microsoft 365 service integration
5. **TeamsAndOutlook**: Communication platform access
6. **PowerPlatform**: Power Apps and Power Automate integration
7. **BusinessDataProcessing**: Enterprise data analysis
8. **WordAndExcel**: Document and spreadsheet manipulation
9. **CopilotForMicrosoft365**: Advanced Copilot features
10. **EnterpriseApplications**: Third-party system integration
11. **CustomConnectors**: Custom API and service integration
### Environment Variables Support
```json
{
"name": "${AGENT_NAME}",
"description": "${AGENT_DESCRIPTION}",
"instructions": "${AGENT_INSTRUCTIONS}"
}
```
**Which workflow would you like to start with?** Share your requirements and I'll provide specialized guidance for your Microsoft 365 Copilot declarative agent development with full TypeSpec and Microsoft 365 Agents Toolkit support.