581 lines
16 KiB
Markdown
581 lines
16 KiB
Markdown
---
|
|
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! |