awesome-copilot/prompts/declarative-agents.prompt.md

description	model	tools
Comprehensive Microsoft 365 Copilot declarative agents development workflows: basic creation, advanced design, and validation using schema v1.5 with Microsoft 365 Agents Toolkit integration	GPT-4.1	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:

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:

{
  "$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:

   npm install -g @microsoft/teamsapp-cli
   

3. Initialize agent project:

   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:

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:

/** 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:

{
  "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:

   {
     "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:

   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:

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:

# 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:

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:

{
  "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:

{
  "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:

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:

   # 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:

   # 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:

   // 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:

   # 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:

   {
     "AGENT_MANIFEST_PATH": "./dist/manifest.json",
     "TEST_DATA_PATH": "./test-data/scenarios.json",
     "LOG_LEVEL": "debug"
   }
   

Production Deployment

1. Validation Pipeline:

   # .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:

   {
     "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

{
  "conversation_starters": [
    {
      "text": "Analyze this quarter's sales performance",
      "metadata": {
        "category": "analysis",
        "complexity": "medium",
        "expected_tokens": 150
      }
    }
  ]
}

Error Handling Patterns

Implement robust error handling:

{
  "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!