mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-23 20:05:12 +00:00
Merge branch 'main' into patch-1
This commit is contained in:
Matt Soucoup
GitHub
118
prompts/devops-rollout-plan.prompt.md
Normal file
118
prompts/devops-rollout-plan.prompt.md
Normal file
@@ -0,0 +1,118 @@
|
||||
---
|
||||
agent: 'agent'
|
||||
description: 'Generate comprehensive rollout plans with preflight checks, step-by-step deployment, verification signals, rollback procedures, and communication plans for infrastructure and application changes'
|
||||
tools: ['codebase', 'terminalCommand', 'search', 'githubRepo']
|
||||
---
|
||||
|
||||
# DevOps Rollout Plan Generator
|
||||
|
||||
Your goal is to create a comprehensive, production-ready rollout plan for infrastructure or application changes.
|
||||
|
||||
## Input Requirements
|
||||
|
||||
Gather these details before generating the plan:
|
||||
|
||||
### Change Description
|
||||
- What's changing (infrastructure, application, configuration)
|
||||
- Version or state transition (from/to)
|
||||
- Problem solved or feature added
|
||||
|
||||
### Environment Details
|
||||
- Target environment (dev, staging, production, all)
|
||||
- Infrastructure type (Kubernetes, VMs, serverless, containers)
|
||||
- Affected services and dependencies
|
||||
- Current capacity and scale
|
||||
|
||||
### Constraints & Requirements
|
||||
- Acceptable downtime window
|
||||
- Change window restrictions
|
||||
- Approval requirements
|
||||
- Regulatory or compliance considerations
|
||||
|
||||
### Risk Assessment
|
||||
- Blast radius of change
|
||||
- Data migrations or schema changes
|
||||
- Rollback complexity and safety
|
||||
- Known risks
|
||||
|
||||
## Output Format
|
||||
|
||||
Generate a structured rollout plan with these sections:
|
||||
|
||||
### 1. Executive Summary
|
||||
- What, why, when, duration
|
||||
- Risk level and rollback time
|
||||
- Affected systems and user impact
|
||||
- Expected downtime
|
||||
|
||||
### 2. Prerequisites & Approvals
|
||||
- Required approvals (technical lead, security, compliance, business)
|
||||
- Required resources (capacity, backups, monitoring, rollback automation)
|
||||
- Pre-deployment backups
|
||||
|
||||
### 3. Preflight Checks
|
||||
- Infrastructure health validation
|
||||
- Application health baseline
|
||||
- Dependency availability
|
||||
- Monitoring baseline metrics
|
||||
- Go/no-go decision checklist
|
||||
|
||||
### 4. Step-by-Step Rollout Procedure
|
||||
**Phases**: Pre-deployment, deployment, progressive verification
|
||||
- Specific commands for each step
|
||||
- Validation after each step
|
||||
- Duration estimates
|
||||
|
||||
### 5. Verification Signals
|
||||
**Immediate** (0-2 min): Deployment success, pods/containers started, health checks passing
|
||||
**Short-term** (2-5 min): Application responding, error rates acceptable, latency normal
|
||||
**Medium-term** (5-15 min): Sustained metrics, stable connections, integrations working
|
||||
**Long-term** (15+ min): No degradation, capacity healthy, business metrics normal
|
||||
|
||||
### 6. Rollback Procedure
|
||||
**Decision Criteria**: When to initiate rollback
|
||||
**Rollback Steps**: Automated, infrastructure revert, or full restore
|
||||
**Post-Rollback Verification**: Confirm system health restored
|
||||
**Communication**: Stakeholder notification
|
||||
|
||||
### 7. Communication Plan
|
||||
- Pre-deployment (T-24h): Schedule and impact notice
|
||||
- Deployment start: Commencement notice
|
||||
- Progress updates: Status every X minutes
|
||||
- Completion: Success confirmation
|
||||
- Rollback (if needed): Issue notification
|
||||
|
||||
**Stakeholder Matrix**: Who to notify, when, via what method, with what content
|
||||
|
||||
### 8. Post-Deployment Tasks
|
||||
- Immediate (1h): Verify criteria met, review logs
|
||||
- Short-term (24h): Monitor metrics, review errors
|
||||
- Medium-term (1 week): Post-deployment review, lessons learned
|
||||
|
||||
### 9. Contingency Plans
|
||||
Scenarios: Partial failure, performance degradation, data inconsistency, dependency failure
|
||||
For each: Symptoms, response, timeline
|
||||
|
||||
### 10. Contact Information
|
||||
- Primary and secondary on-call
|
||||
- Escalation path
|
||||
- Emergency contacts (infrastructure, security, database, networking)
|
||||
|
||||
## Plan Customization
|
||||
|
||||
Adapt based on:
|
||||
- **Infrastructure Type**: Kubernetes, VMs, serverless, databases
|
||||
- **Risk Level**: Low (simplified), medium (standard), high (additional gates)
|
||||
- **Change Type**: Code deployment, infrastructure, configuration, data migration
|
||||
- **Environment**: Production (full plan), staging (simplified), development (minimal)
|
||||
|
||||
## Remember
|
||||
|
||||
- Always have a tested rollback plan
|
||||
- Communicate early and often
|
||||
- Monitor metrics, not just logs
|
||||
- Document everything
|
||||
- Learn from each deployment
|
||||
- Never deploy on Friday afternoon (unless critical)
|
||||
- Never skip verification steps
|
||||
- Never assume "it should work"
|
||||
@@ -1,115 +1,114 @@
|
||||
---
|
||||
name: ".NET Upgrade Analysis Prompts"
|
||||
description: "Ready-to-use prompts for comprehensive .NET framework upgrade analysis and execution"
|
||||
prompts:
|
||||
---
|
||||
# Project Discovery & Assessment
|
||||
- name: "Project Classification Analysis"
|
||||
prompt: "Identify all projects in the solution and classify them by type (`.NET Framework`, `.NET Core`, `.NET Standard`). Analyze each `.csproj` for its current `TargetFramework` and SDK usage."
|
||||
|
||||
|
||||
- name: "Dependency Compatibility Review"
|
||||
prompt: "Review external and internal dependencies for framework compatibility. Determine the upgrade complexity based on dependency graph depth."
|
||||
|
||||
|
||||
- name: "Legacy Package Detection"
|
||||
prompt: "Identify legacy `packages.config` projects needing migration to `PackageReference` format."
|
||||
|
||||
# Upgrade Strategy & Sequencing
|
||||
- name: "Project Upgrade Ordering"
|
||||
prompt: "Recommend a project upgrade order from least to most dependent components. Suggest how to isolate class library upgrades before API or Azure Function migrations."
|
||||
|
||||
|
||||
- name: "Incremental Strategy Planning"
|
||||
prompt: "Propose an incremental upgrade strategy with rollback checkpoints. Evaluate the use of **Upgrade Assistant** or **manual upgrades** based on project structure."
|
||||
|
||||
|
||||
- name: "Progress Tracking Setup"
|
||||
prompt: "Generate an upgrade checklist for tracking build, test, and deployment readiness across all projects."
|
||||
|
||||
# Framework Targeting & Code Adjustments
|
||||
- name: "Target Framework Selection"
|
||||
prompt: "Suggest the correct `TargetFramework` for each project (e.g., `net8.0`). Review and update deprecated SDK or build configurations."
|
||||
|
||||
|
||||
- name: "Code Modernization Analysis"
|
||||
prompt: "Identify code patterns needing modernization (e.g., `WebHostBuilder` → `HostBuilder`). Suggest replacements for deprecated .NET APIs and third-party libraries."
|
||||
|
||||
|
||||
- name: "Async Pattern Conversion"
|
||||
prompt: "Recommend conversion of synchronous calls to async where appropriate for improved performance and scalability."
|
||||
|
||||
# NuGet & Dependency Management
|
||||
- name: "Package Compatibility Analysis"
|
||||
prompt: "Analyze outdated or incompatible NuGet packages and suggest compatible versions. Identify third-party libraries that lack .NET 8 support and provide migration paths."
|
||||
|
||||
|
||||
- name: "Shared Dependency Strategy"
|
||||
prompt: "Recommend strategies for handling shared dependency upgrades across projects. Evaluate usage of legacy packages and suggest alternatives in Microsoft-supported namespaces."
|
||||
|
||||
|
||||
- name: "Transitive Dependency Review"
|
||||
prompt: "Review transitive dependencies and potential version conflicts after upgrade. Suggest resolution strategies for dependency conflicts."
|
||||
|
||||
# CI/CD & Build Pipeline Updates
|
||||
- name: "Pipeline Configuration Analysis"
|
||||
prompt: "Analyze YAML build definitions for SDK version pinning and recommend updates. Suggest modifications for `UseDotNet@2` and `NuGetToolInstaller` tasks."
|
||||
|
||||
|
||||
- name: "Build Pipeline Modernization"
|
||||
prompt: "Generate updated build pipeline snippets for .NET 8 migration. Recommend validation builds on feature branches before merging to main."
|
||||
|
||||
|
||||
- name: "CI Automation Enhancement"
|
||||
prompt: "Identify opportunities to automate test and build verification in CI pipelines. Suggest strategies for continuous integration validation."
|
||||
|
||||
# Testing & Validation
|
||||
- name: "Build Validation Strategy"
|
||||
prompt: "Propose validation checks to ensure the upgraded solution builds and runs successfully. Recommend automated test execution for unit and integration suites post-upgrade."
|
||||
|
||||
|
||||
- name: "Service Integration Verification"
|
||||
prompt: "Generate validation steps to verify logging, telemetry, and service connectivity. Suggest strategies for verifying backward compatibility and runtime behavior."
|
||||
|
||||
|
||||
- name: "Deployment Readiness Check"
|
||||
prompt: "Recommend UAT deployment verification steps before production rollout. Create comprehensive testing scenarios for upgraded components."
|
||||
|
||||
# Breaking Change Analysis
|
||||
- name: "API Deprecation Detection"
|
||||
prompt: "Identify deprecated APIs or removed namespaces between target versions. Suggest automated scanning using `.NET Upgrade Assistant` and API Analyzer."
|
||||
|
||||
|
||||
- name: "API Replacement Strategy"
|
||||
prompt: "Recommend replacement APIs or libraries for known breaking areas. Review configuration changes such as `Startup.cs` → `Program.cs` refactoring."
|
||||
|
||||
|
||||
- name: "Regression Testing Focus"
|
||||
prompt: "Suggest regression testing scenarios focused on upgraded API endpoints or services. Create test plans for critical functionality validation."
|
||||
|
||||
# Version Control & Commit Strategy
|
||||
- name: "Branching Strategy Planning"
|
||||
prompt: "Recommend branching strategy for safe upgrade with rollback capability. Generate commit templates for partial and complete project upgrades."
|
||||
|
||||
|
||||
- name: "PR Structure Optimization"
|
||||
prompt: "Suggest best practices for creating structured PRs (`Upgrade to .NET [Version]`). Identify tagging strategies for PRs involving breaking changes."
|
||||
|
||||
|
||||
- name: "Code Review Guidelines"
|
||||
prompt: "Recommend peer review focus areas (build, test, and dependency validation). Create checklists for effective upgrade reviews."
|
||||
|
||||
# Documentation & Communication
|
||||
- name: "Upgrade Documentation Strategy"
|
||||
prompt: "Suggest how to document each project's framework change in the PR. Propose automated release note generation summarizing upgrades and test results."
|
||||
|
||||
|
||||
- name: "Stakeholder Communication"
|
||||
prompt: "Recommend communicating version upgrades and migration timelines to consumers. Generate documentation templates for dependency updates and validation results."
|
||||
|
||||
|
||||
- name: "Progress Tracking Systems"
|
||||
prompt: "Suggest maintaining an upgrade summary dashboard or markdown checklist. Create templates for tracking upgrade progress across multiple projects."
|
||||
|
||||
# Tools & Automation
|
||||
- name: "Upgrade Tool Selection"
|
||||
prompt: "Recommend when and how to use: `.NET Upgrade Assistant`, `dotnet list package --outdated`, `dotnet migrate`, and `graph.json` dependency visualization."
|
||||
|
||||
|
||||
- name: "Analysis Script Generation"
|
||||
prompt: "Generate scripts or prompts for analyzing dependency graphs before upgrading. Propose AI-assisted prompts for Copilot to identify upgrade issues automatically."
|
||||
|
||||
|
||||
- name: "Multi-Repository Validation"
|
||||
prompt: "Suggest how to validate automation output across multiple repositories. Create standardized validation workflows for enterprise-scale upgrades."
|
||||
|
||||
# Final Validation & Delivery
|
||||
- name: "Final Solution Validation"
|
||||
prompt: "Generate validation steps to confirm the final upgraded solution passes all validation checks. Suggest production deployment verification steps post-upgrade."
|
||||
|
||||
|
||||
- name: "Deployment Readiness Confirmation"
|
||||
prompt: "Recommend generating final test results and build artifacts. Create a checklist summarizing completion across projects (builds/tests/deployment)."
|
||||
|
||||
|
||||
- name: "Release Documentation"
|
||||
prompt: "Generate a release note summarizing framework changes and CI/CD updates. Create comprehensive upgrade summary documentation."
|
||||
|
||||
|
||||
527
prompts/mcp-create-adaptive-cards.prompt.md
Normal file
527
prompts/mcp-create-adaptive-cards.prompt.md
Normal file
@@ -0,0 +1,527 @@
|
||||
````prompt
|
||||
---
|
||||
mode: 'agent'
|
||||
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
|
||||
description: 'Add Adaptive Card response templates to MCP-based API plugins for visual data presentation in Microsoft 365 Copilot'
|
||||
model: 'gpt-4.1'
|
||||
tags: [mcp, adaptive-cards, m365-copilot, api-plugin, response-templates]
|
||||
---
|
||||
|
||||
# Create Adaptive Cards for MCP Plugins
|
||||
|
||||
Add Adaptive Card response templates to MCP-based API plugins to enhance how data is presented visually in Microsoft 365 Copilot.
|
||||
|
||||
## Adaptive Card Types
|
||||
|
||||
### Static Response Templates
|
||||
Use when API always returns items of the same type and format doesn't change often.
|
||||
|
||||
Define in `response_semantics.static_template` in ai-plugin.json:
|
||||
|
||||
```json
|
||||
{
|
||||
"functions": [
|
||||
{
|
||||
"name": "GetBudgets",
|
||||
"description": "Returns budget details including name and available funds",
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"subtitle": "$.availableFunds"
|
||||
},
|
||||
"static_template": {
|
||||
"type": "AdaptiveCard",
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${$root}",
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Name: ${if(name, name, 'N/A')}",
|
||||
"wrap": true
|
||||
},
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Available funds: ${if(availableFunds, formatNumber(availableFunds, 2), 'N/A')}",
|
||||
"wrap": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic Response Templates
|
||||
Use when API returns multiple types and each item needs a different template.
|
||||
|
||||
**ai-plugin.json configuration:**
|
||||
```json
|
||||
{
|
||||
"name": "GetTransactions",
|
||||
"description": "Returns transaction details with dynamic templates",
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$.transactions",
|
||||
"properties": {
|
||||
"template_selector": "$.displayTemplate"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**API Response with Embedded Templates:**
|
||||
```json
|
||||
{
|
||||
"transactions": [
|
||||
{
|
||||
"budgetName": "Fourth Coffee lobby renovation",
|
||||
"amount": -2000,
|
||||
"description": "Property survey for permit application",
|
||||
"expenseCategory": "permits",
|
||||
"displayTemplate": "$.templates.debit"
|
||||
},
|
||||
{
|
||||
"budgetName": "Fourth Coffee lobby renovation",
|
||||
"amount": 5000,
|
||||
"description": "Additional funds to cover cost overruns",
|
||||
"expenseCategory": null,
|
||||
"displayTemplate": "$.templates.credit"
|
||||
}
|
||||
],
|
||||
"templates": {
|
||||
"debit": {
|
||||
"type": "AdaptiveCard",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"size": "medium",
|
||||
"weight": "bolder",
|
||||
"color": "attention",
|
||||
"text": "Debit"
|
||||
},
|
||||
{
|
||||
"type": "FactSet",
|
||||
"facts": [
|
||||
{
|
||||
"title": "Budget",
|
||||
"value": "${budgetName}"
|
||||
},
|
||||
{
|
||||
"title": "Amount",
|
||||
"value": "${formatNumber(amount, 2)}"
|
||||
},
|
||||
{
|
||||
"title": "Category",
|
||||
"value": "${if(expenseCategory, expenseCategory, 'N/A')}"
|
||||
},
|
||||
{
|
||||
"title": "Description",
|
||||
"value": "${if(description, description, 'N/A')}"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
|
||||
},
|
||||
"credit": {
|
||||
"type": "AdaptiveCard",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"size": "medium",
|
||||
"weight": "bolder",
|
||||
"color": "good",
|
||||
"text": "Credit"
|
||||
},
|
||||
{
|
||||
"type": "FactSet",
|
||||
"facts": [
|
||||
{
|
||||
"title": "Budget",
|
||||
"value": "${budgetName}"
|
||||
},
|
||||
{
|
||||
"title": "Amount",
|
||||
"value": "${formatNumber(amount, 2)}"
|
||||
},
|
||||
{
|
||||
"title": "Description",
|
||||
"value": "${if(description, description, 'N/A')}"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Combined Static and Dynamic Templates
|
||||
Use static template as default when item doesn't have template_selector or when value doesn't resolve.
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$.items",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"template_selector": "$.templateId"
|
||||
},
|
||||
"static_template": {
|
||||
"type": "AdaptiveCard",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Default: ${name}",
|
||||
"wrap": true
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response Semantics Properties
|
||||
|
||||
### data_path
|
||||
JSONPath query indicating where data resides in API response:
|
||||
```json
|
||||
"data_path": "$" // Root of response
|
||||
"data_path": "$.results" // In results property
|
||||
"data_path": "$.data.items"// Nested path
|
||||
```
|
||||
|
||||
### properties
|
||||
Map response fields for Copilot citations:
|
||||
```json
|
||||
"properties": {
|
||||
"title": "$.name", // Citation title
|
||||
"subtitle": "$.description", // Citation subtitle
|
||||
"url": "$.link" // Citation link
|
||||
}
|
||||
```
|
||||
|
||||
### template_selector
|
||||
Property on each item indicating which template to use:
|
||||
```json
|
||||
"template_selector": "$.displayTemplate"
|
||||
```
|
||||
|
||||
## Adaptive Card Template Language
|
||||
|
||||
### Conditional Rendering
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${if(field, field, 'N/A')}" // Show field or 'N/A'
|
||||
}
|
||||
```
|
||||
|
||||
### Number Formatting
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${formatNumber(amount, 2)}" // Two decimal places
|
||||
}
|
||||
```
|
||||
|
||||
### Data Binding
|
||||
```json
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${$root}", // Break to root context
|
||||
"items": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### Conditional Display
|
||||
```json
|
||||
{
|
||||
"type": "Image",
|
||||
"url": "${imageUrl}",
|
||||
"$when": "${imageUrl != null}" // Only show if imageUrl exists
|
||||
}
|
||||
```
|
||||
|
||||
## Card Elements
|
||||
|
||||
### TextBlock
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Text content",
|
||||
"size": "medium", // small, default, medium, large, extraLarge
|
||||
"weight": "bolder", // lighter, default, bolder
|
||||
"color": "attention", // default, dark, light, accent, good, warning, attention
|
||||
"wrap": true
|
||||
}
|
||||
```
|
||||
|
||||
### FactSet
|
||||
```json
|
||||
{
|
||||
"type": "FactSet",
|
||||
"facts": [
|
||||
{
|
||||
"title": "Label",
|
||||
"value": "Value"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Image
|
||||
```json
|
||||
{
|
||||
"type": "Image",
|
||||
"url": "https://example.com/image.png",
|
||||
"size": "medium", // auto, stretch, small, medium, large
|
||||
"style": "default" // default, person
|
||||
}
|
||||
```
|
||||
|
||||
### Container
|
||||
```json
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${items}", // Iterate over array
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${name}"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### ColumnSet
|
||||
```json
|
||||
{
|
||||
"type": "ColumnSet",
|
||||
"columns": [
|
||||
{
|
||||
"type": "Column",
|
||||
"width": "auto",
|
||||
"items": [ ... ]
|
||||
},
|
||||
{
|
||||
"type": "Column",
|
||||
"width": "stretch",
|
||||
"items": [ ... ]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Actions
|
||||
```json
|
||||
{
|
||||
"type": "Action.OpenUrl",
|
||||
"title": "View Details",
|
||||
"url": "https://example.com/item/${id}"
|
||||
}
|
||||
```
|
||||
|
||||
## Responsive Design Best Practices
|
||||
|
||||
### Single-Column Layouts
|
||||
- Use single columns for narrow viewports
|
||||
- Avoid multi-column layouts when possible
|
||||
- Ensure cards work at minimum viewport width
|
||||
|
||||
### Flexible Widths
|
||||
- Don't assign fixed widths to elements
|
||||
- Use "auto" or "stretch" for width properties
|
||||
- Allow elements to resize with viewport
|
||||
- Fixed widths OK for icons/avatars only
|
||||
|
||||
### Text and Images
|
||||
- Avoid placing text and images in same row
|
||||
- Exception: Small icons or avatars
|
||||
- Use "wrap": true for text content
|
||||
- Test at various viewport widths
|
||||
|
||||
### Test Across Hubs
|
||||
Validate cards in:
|
||||
- Teams (desktop and mobile)
|
||||
- Word
|
||||
- PowerPoint
|
||||
- Various viewport widths (contract/expand UI)
|
||||
|
||||
## Complete Example
|
||||
|
||||
**ai-plugin.json:**
|
||||
```json
|
||||
{
|
||||
"functions": [
|
||||
{
|
||||
"name": "SearchProjects",
|
||||
"description": "Search for projects with status and details",
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$.projects",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"subtitle": "$.status",
|
||||
"url": "$.projectUrl"
|
||||
},
|
||||
"static_template": {
|
||||
"type": "AdaptiveCard",
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${$root}",
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"size": "medium",
|
||||
"weight": "bolder",
|
||||
"text": "${if(name, name, 'Untitled Project')}",
|
||||
"wrap": true
|
||||
},
|
||||
{
|
||||
"type": "FactSet",
|
||||
"facts": [
|
||||
{
|
||||
"title": "Status",
|
||||
"value": "${status}"
|
||||
},
|
||||
{
|
||||
"title": "Owner",
|
||||
"value": "${if(owner, owner, 'Unassigned')}"
|
||||
},
|
||||
{
|
||||
"title": "Due Date",
|
||||
"value": "${if(dueDate, dueDate, 'Not set')}"
|
||||
},
|
||||
{
|
||||
"title": "Budget",
|
||||
"value": "${if(budget, formatNumber(budget, 2), 'N/A')}"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${if(description, description, 'No description')}",
|
||||
"wrap": true,
|
||||
"separator": true
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
{
|
||||
"type": "Action.OpenUrl",
|
||||
"title": "View Project",
|
||||
"url": "${projectUrl}"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
Ask the user:
|
||||
1. What type of data does the API return?
|
||||
2. Are all items the same type (static) or different types (dynamic)?
|
||||
3. What fields should appear in the card?
|
||||
4. Should there be actions (e.g., "View Details")?
|
||||
5. Are there multiple states or categories requiring different templates?
|
||||
|
||||
Then generate:
|
||||
- Appropriate response_semantics configuration
|
||||
- Static template, dynamic templates, or both
|
||||
- Proper data binding with conditional rendering
|
||||
- Responsive single-column layout
|
||||
- Test scenarios for validation
|
||||
|
||||
## Resources
|
||||
|
||||
- [Adaptive Card Designer](https://adaptivecards.microsoft.com/designer) - Visual design tool
|
||||
- [Adaptive Card Schema](https://adaptivecards.io/schemas/adaptive-card.json) - Full schema reference
|
||||
- [Template Language](https://learn.microsoft.com/en-us/adaptive-cards/templating/language) - Binding syntax guide
|
||||
- [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) - Path query syntax
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### List with Images
|
||||
```json
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${items}",
|
||||
"items": [
|
||||
{
|
||||
"type": "ColumnSet",
|
||||
"columns": [
|
||||
{
|
||||
"type": "Column",
|
||||
"width": "auto",
|
||||
"items": [
|
||||
{
|
||||
"type": "Image",
|
||||
"url": "${thumbnailUrl}",
|
||||
"size": "small",
|
||||
"$when": "${thumbnailUrl != null}"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "Column",
|
||||
"width": "stretch",
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${title}",
|
||||
"weight": "bolder",
|
||||
"wrap": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Status Indicators
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${status}",
|
||||
"color": "${if(status == 'Completed', 'good', if(status == 'In Progress', 'attention', 'default'))}"
|
||||
}
|
||||
```
|
||||
|
||||
### Currency Formatting
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "$${formatNumber(amount, 2)}"
|
||||
}
|
||||
```
|
||||
|
||||
````
|
||||
310
prompts/mcp-create-declarative-agent.prompt.md
Normal file
310
prompts/mcp-create-declarative-agent.prompt.md
Normal file
@@ -0,0 +1,310 @@
|
||||
````prompt
|
||||
---
|
||||
mode: 'agent'
|
||||
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
|
||||
description: 'Create a declarative agent for Microsoft 365 Copilot by integrating an MCP server with authentication, tool selection, and configuration'
|
||||
model: 'gpt-4.1'
|
||||
tags: [mcp, m365-copilot, declarative-agent, model-context-protocol, api-plugin]
|
||||
---
|
||||
|
||||
# Create MCP-based Declarative Agent for Microsoft 365 Copilot
|
||||
|
||||
Create a complete declarative agent for Microsoft 365 Copilot that integrates with a Model Context Protocol (MCP) server to access external systems and data.
|
||||
|
||||
## Requirements
|
||||
|
||||
Generate the following project structure using Microsoft 365 Agents Toolkit:
|
||||
|
||||
### Project Setup
|
||||
1. **Scaffold declarative agent** via Agents Toolkit
|
||||
2. **Add MCP action** pointing to MCP server
|
||||
3. **Select tools** to import from MCP server
|
||||
4. **Configure authentication** (OAuth 2.0 or SSO)
|
||||
5. **Review generated files** (manifest.json, ai-plugin.json, declarativeAgent.json)
|
||||
|
||||
### Key Files Generated
|
||||
|
||||
**appPackage/manifest.json** - Teams app manifest with plugin reference:
|
||||
```json
|
||||
{
|
||||
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
|
||||
"manifestVersion": "devPreview",
|
||||
"version": "1.0.0",
|
||||
"id": "...",
|
||||
"developer": {
|
||||
"name": "...",
|
||||
"websiteUrl": "...",
|
||||
"privacyUrl": "...",
|
||||
"termsOfUseUrl": "..."
|
||||
},
|
||||
"name": {
|
||||
"short": "Agent Name",
|
||||
"full": "Full Agent Name"
|
||||
},
|
||||
"description": {
|
||||
"short": "Short description",
|
||||
"full": "Full description"
|
||||
},
|
||||
"copilotAgents": {
|
||||
"declarativeAgents": [
|
||||
{
|
||||
"id": "declarativeAgent",
|
||||
"file": "declarativeAgent.json"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**appPackage/declarativeAgent.json** - Agent definition:
|
||||
```json
|
||||
{
|
||||
"$schema": "https://aka.ms/json-schemas/copilot/declarative-agent/v1.0/schema.json",
|
||||
"version": "v1.0",
|
||||
"name": "Agent Name",
|
||||
"description": "Agent description",
|
||||
"instructions": "You are an assistant that helps with [specific domain]. Use the available tools to [capabilities].",
|
||||
"capabilities": [
|
||||
{
|
||||
"name": "WebSearch",
|
||||
"websites": [
|
||||
{
|
||||
"url": "https://learn.microsoft.com"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "MCP",
|
||||
"file": "ai-plugin.json"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**appPackage/ai-plugin.json** - MCP plugin manifest:
|
||||
```json
|
||||
{
|
||||
"schema_version": "v2.1",
|
||||
"name_for_human": "Service Name",
|
||||
"description_for_human": "Description for users",
|
||||
"description_for_model": "Description for AI model",
|
||||
"contact_email": "support@company.com",
|
||||
"namespace": "serviceName",
|
||||
"capabilities": {
|
||||
"conversation_starters": [
|
||||
{
|
||||
"text": "Example query 1"
|
||||
}
|
||||
]
|
||||
},
|
||||
"functions": [
|
||||
{
|
||||
"name": "functionName",
|
||||
"description": "Function description",
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$",
|
||||
"properties": {
|
||||
"title": "$.title",
|
||||
"subtitle": "$.description"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"runtimes": [
|
||||
{
|
||||
"type": "MCP",
|
||||
"spec": {
|
||||
"url": "https://api.service.com/mcp/"
|
||||
},
|
||||
"run_for_functions": ["functionName"],
|
||||
"auth": {
|
||||
"type": "OAuthPluginVault",
|
||||
"reference_id": "${{OAUTH_REFERENCE_ID}}"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**/.vscode/mcp.json** - MCP server configuration:
|
||||
```json
|
||||
{
|
||||
"serverUrl": "https://api.service.com/mcp/",
|
||||
"pluginFilePath": "appPackage/ai-plugin.json"
|
||||
}
|
||||
```
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
### Supported MCP Endpoints
|
||||
The MCP server must provide:
|
||||
- **Server metadata** endpoint
|
||||
- **Tools listing** endpoint (exposes available functions)
|
||||
- **Tool execution** endpoint (handles function calls)
|
||||
|
||||
### Tool Selection
|
||||
When importing from MCP:
|
||||
1. Fetch available tools from server
|
||||
2. Select specific tools to include (for security/simplicity)
|
||||
3. Tool definitions are auto-generated in ai-plugin.json
|
||||
|
||||
### Authentication Types
|
||||
|
||||
**OAuth 2.0 (Static Registration)**
|
||||
```json
|
||||
"auth": {
|
||||
"type": "OAuthPluginVault",
|
||||
"reference_id": "${{OAUTH_REFERENCE_ID}}",
|
||||
"authorization_url": "https://auth.service.com/authorize",
|
||||
"client_id": "${{CLIENT_ID}}",
|
||||
"client_secret": "${{CLIENT_SECRET}}",
|
||||
"scope": "read write"
|
||||
}
|
||||
```
|
||||
|
||||
**Single Sign-On (SSO)**
|
||||
```json
|
||||
"auth": {
|
||||
"type": "SSO"
|
||||
}
|
||||
```
|
||||
|
||||
## Response Semantics
|
||||
|
||||
### Define Data Mapping
|
||||
Use `response_semantics` to extract relevant fields from API responses:
|
||||
|
||||
```json
|
||||
"capabilities": {
|
||||
"response_semantics": {
|
||||
"data_path": "$.results",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"subtitle": "$.description",
|
||||
"url": "$.link"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Add Adaptive Cards (Optional)
|
||||
See the `mcp-create-adaptive-cards` prompt for adding visual card templates.
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Create `.env.local` or `.env.dev` for credentials:
|
||||
|
||||
```env
|
||||
OAUTH_REFERENCE_ID=your-oauth-reference-id
|
||||
CLIENT_ID=your-client-id
|
||||
CLIENT_SECRET=your-client-secret
|
||||
```
|
||||
|
||||
## Testing & Deployment
|
||||
|
||||
### Local Testing
|
||||
1. **Provision** agent in Agents Toolkit
|
||||
2. **Start debugging** to sideload in Teams
|
||||
3. Test in Microsoft 365 Copilot at https://m365.cloud.microsoft/chat
|
||||
4. Authenticate when prompted
|
||||
5. Query the agent using natural language
|
||||
|
||||
### Validation
|
||||
- Verify tool imports in ai-plugin.json
|
||||
- Check authentication configuration
|
||||
- Test each exposed function
|
||||
- Validate response data mapping
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Tool Design
|
||||
- **Focused functions**: Each tool should do one thing well
|
||||
- **Clear descriptions**: Help the model understand when to use each tool
|
||||
- **Minimal scoping**: Only import tools the agent needs
|
||||
- **Descriptive names**: Use action-oriented function names
|
||||
|
||||
### Security
|
||||
- **Use OAuth 2.0** for production scenarios
|
||||
- **Store secrets** in environment variables
|
||||
- **Validate inputs** on the MCP server side
|
||||
- **Limit scopes** to minimum required permissions
|
||||
- **Use reference IDs** for OAuth registration
|
||||
|
||||
### Instructions
|
||||
- **Be specific** about the agent's purpose and capabilities
|
||||
- **Define behavior** for both successful and error scenarios
|
||||
- **Reference tools** explicitly in instructions when applicable
|
||||
- **Set expectations** for users about what the agent can/cannot do
|
||||
|
||||
### Performance
|
||||
- **Cache responses** when appropriate on MCP server
|
||||
- **Batch operations** where possible
|
||||
- **Set timeouts** for long-running operations
|
||||
- **Paginate results** for large datasets
|
||||
|
||||
## Common MCP Server Examples
|
||||
|
||||
### GitHub MCP Server
|
||||
```
|
||||
URL: https://api.githubcopilot.com/mcp/
|
||||
Tools: search_repositories, search_users, get_repository
|
||||
Auth: OAuth 2.0
|
||||
```
|
||||
|
||||
### Jira MCP Server
|
||||
```
|
||||
URL: https://your-domain.atlassian.net/mcp/
|
||||
Tools: search_issues, create_issue, update_issue
|
||||
Auth: OAuth 2.0
|
||||
```
|
||||
|
||||
### Custom Service
|
||||
```
|
||||
URL: https://api.your-service.com/mcp/
|
||||
Tools: Custom tools exposed by your service
|
||||
Auth: OAuth 2.0 or SSO
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
Ask the user:
|
||||
1. What MCP server are you integrating with (URL)?
|
||||
2. What tools should be exposed to Copilot?
|
||||
3. What authentication method does the server support?
|
||||
4. What should the agent's primary purpose be?
|
||||
5. Do you need response semantics or Adaptive Cards?
|
||||
|
||||
Then generate:
|
||||
- Complete appPackage/ structure (manifest.json, declarativeAgent.json, ai-plugin.json)
|
||||
- mcp.json configuration
|
||||
- .env.local template
|
||||
- Provisioning and testing instructions
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### MCP Server Not Responding
|
||||
- Verify server URL is correct
|
||||
- Check network connectivity
|
||||
- Validate MCP server implements required endpoints
|
||||
|
||||
### Authentication Fails
|
||||
- Verify OAuth credentials are correct
|
||||
- Check reference ID matches registration
|
||||
- Confirm scopes are requested properly
|
||||
- Test OAuth flow independently
|
||||
|
||||
### Tools Not Appearing
|
||||
- Ensure mcp.json points to correct server
|
||||
- Verify tools were selected during import
|
||||
- Check ai-plugin.json has correct function definitions
|
||||
- Re-fetch actions from MCP if server changed
|
||||
|
||||
### Agent Not Understanding Queries
|
||||
- Review instructions in declarativeAgent.json
|
||||
- Check function descriptions are clear
|
||||
- Verify response_semantics extract correct data
|
||||
- Test with more specific queries
|
||||
|
||||
````
|
||||
336
prompts/mcp-deploy-manage-agents.prompt.md
Normal file
336
prompts/mcp-deploy-manage-agents.prompt.md
Normal file
@@ -0,0 +1,336 @@
|
||||
````prompt
|
||||
---
|
||||
mode: 'agent'
|
||||
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
|
||||
description: 'Deploy and manage MCP-based declarative agents in Microsoft 365 admin center with governance, assignments, and organizational distribution'
|
||||
model: 'gpt-4.1'
|
||||
tags: [mcp, m365-copilot, deployment, admin, agent-management, governance]
|
||||
---
|
||||
|
||||
# Deploy and Manage MCP-Based Agents
|
||||
|
||||
Deploy, manage, and govern MCP-based declarative agents in Microsoft 365 using the admin center for organizational distribution and control.
|
||||
|
||||
## Agent Types
|
||||
|
||||
### Published by Organization
|
||||
- Built with predefined instructions and actions
|
||||
- Follow structured logic for predictable tasks
|
||||
- Require admin approval and publishing process
|
||||
- Support compliance and governance requirements
|
||||
|
||||
### Shared by Creator
|
||||
- Created in Microsoft 365 Copilot Studio or Agent Builder
|
||||
- Shared directly with specific users
|
||||
- Enhanced functionality with search, actions, connectors, APIs
|
||||
- Visible to admins in agent registry
|
||||
|
||||
### Microsoft Agents
|
||||
- Developed and maintained by Microsoft
|
||||
- Integrated with Microsoft 365 services
|
||||
- Pre-approved and ready to use
|
||||
|
||||
### External Partner Agents
|
||||
- Created by verified external developers/vendors
|
||||
- Subject to admin approval and control
|
||||
- Configurable availability and permissions
|
||||
|
||||
### Frontier Agents
|
||||
- Experimental or advanced capabilities
|
||||
- May require limited rollout or additional oversight
|
||||
- Examples:
|
||||
- **App Builder agent**: Managed via M365 Copilot or Power Platform admin center
|
||||
- **Workflows agent**: Flow automation managed via Power Platform admin center
|
||||
|
||||
## Admin Roles and Permissions
|
||||
|
||||
### Required Roles
|
||||
- **AI Admin**: Full agent management capabilities
|
||||
- **Global Reader**: View-only access (no editing)
|
||||
|
||||
### Best Practices
|
||||
- Use roles with fewest permissions
|
||||
- Limit Global Administrator to emergency scenarios
|
||||
- Follow principle of least privilege
|
||||
|
||||
## Agent Management in Microsoft 365 Admin Center
|
||||
|
||||
### Access Agent Management
|
||||
1. Go to [Microsoft 365 admin center](https://admin.microsoft.com/)
|
||||
2. Navigate to **Agents** page
|
||||
3. View available, deployed, or blocked agents
|
||||
|
||||
### Available Actions
|
||||
|
||||
**View Agents**
|
||||
- Filter by availability (available, deployed, blocked)
|
||||
- Search for specific agents
|
||||
- View agent details (name, creator, date, host products, status)
|
||||
|
||||
**Deploy Agents**
|
||||
Options for distribution:
|
||||
1. **Agent Store**: Submit to Partner Center for validation and public availability
|
||||
2. **Organization Deployment**: IT admin deploys to all or selected employees
|
||||
|
||||
**Manage Agent Lifecycle**
|
||||
- **Publish**: Make agent available to organization
|
||||
- **Deploy**: Assign to specific users or groups
|
||||
- **Block**: Prevent agent from being used
|
||||
- **Remove**: Delete agent from organization
|
||||
|
||||
**Configure Access**
|
||||
- Set availability for specific user groups
|
||||
- Manage permissions per agent
|
||||
- Control which agents appear in Copilot
|
||||
|
||||
## Deployment Workflows
|
||||
|
||||
### Publish to Organization
|
||||
|
||||
**For Agent Developers:**
|
||||
1. Build agent with Microsoft 365 Agents Toolkit
|
||||
2. Test thoroughly in development
|
||||
3. Submit agent for approval
|
||||
4. Wait for admin review
|
||||
|
||||
**For Admins:**
|
||||
1. Review submitted agent in admin center
|
||||
2. Validate compliance and security
|
||||
3. Approve for organizational use
|
||||
4. Configure deployment settings
|
||||
5. Publish to selected users or organization-wide
|
||||
|
||||
### Deploy via Agent Store
|
||||
|
||||
**Developer Steps:**
|
||||
1. Complete agent development and testing
|
||||
2. Package agent for submission
|
||||
3. Submit to Partner Center
|
||||
4. Await validation process
|
||||
5. Receive approval notification
|
||||
6. Agent appears in Copilot store
|
||||
|
||||
**Admin Steps:**
|
||||
1. Discover agents in Copilot store
|
||||
2. Review agent details and permissions
|
||||
3. Assign to organization or user groups
|
||||
4. Monitor usage and feedback
|
||||
|
||||
### Deploy Organizational Agent
|
||||
|
||||
**Admin Deployment Options:**
|
||||
```
|
||||
Organization-wide:
|
||||
- All employees with Copilot license
|
||||
- Automatically available in Copilot
|
||||
|
||||
Group-based:
|
||||
- Specific departments or teams
|
||||
- Security group assignments
|
||||
- Role-based access control
|
||||
```
|
||||
|
||||
**Configuration Steps:**
|
||||
1. Navigate to Agents page in admin center
|
||||
2. Select agent to deploy
|
||||
3. Choose deployment scope:
|
||||
- All users
|
||||
- Specific security groups
|
||||
- Individual users
|
||||
4. Set availability status
|
||||
5. Configure permissions if applicable
|
||||
6. Deploy and monitor
|
||||
|
||||
## User Experience
|
||||
|
||||
### Agent Discovery
|
||||
Users find agents in:
|
||||
- Microsoft 365 Copilot hub
|
||||
- Agent picker in Copilot interface
|
||||
- Organization's agent catalog
|
||||
|
||||
### Agent Access Control
|
||||
Users can:
|
||||
- Toggle agents on/off during interactions
|
||||
- Add/remove agents from their experience
|
||||
- Right-click agents to manage preferences
|
||||
- Only access admin-allowed agents
|
||||
|
||||
### Agent Usage
|
||||
- Agents appear in Copilot sidebar
|
||||
- Users select agent for context
|
||||
- Queries routed through selected agent
|
||||
- Responses leverage agent's capabilities
|
||||
|
||||
## Governance and Compliance
|
||||
|
||||
### Security Considerations
|
||||
- **Data access**: Review what data agent can access
|
||||
- **API permissions**: Validate required scopes
|
||||
- **Authentication**: Ensure secure OAuth flows
|
||||
- **External connections**: Assess risk of external integrations
|
||||
|
||||
### Compliance Requirements
|
||||
- **Data residency**: Verify data stays within boundaries
|
||||
- **Privacy policies**: Review agent privacy statement
|
||||
- **Terms of use**: Validate acceptable use policies
|
||||
- **Audit logs**: Monitor agent usage and activity
|
||||
|
||||
### Monitoring and Reporting
|
||||
Track:
|
||||
- Agent adoption rates
|
||||
- User feedback and satisfaction
|
||||
- Error rates and performance
|
||||
- Security incidents or violations
|
||||
|
||||
## MCP-Specific Management
|
||||
|
||||
### MCP Agent Characteristics
|
||||
- Connect to external systems via Model Context Protocol
|
||||
- Use tools exposed by MCP servers
|
||||
- Require OAuth 2.0 or SSO authentication
|
||||
- Support same governance as REST API agents
|
||||
|
||||
### MCP Agent Validation
|
||||
Verify:
|
||||
- MCP server URL is accessible
|
||||
- Authentication configuration is secure
|
||||
- Tools imported are appropriate
|
||||
- Response data doesn't expose sensitive info
|
||||
- Server follows security best practices
|
||||
|
||||
### MCP Agent Deployment
|
||||
Same process as REST API agents:
|
||||
1. Review in admin center
|
||||
2. Validate MCP server compliance
|
||||
3. Test authentication flow
|
||||
4. Deploy to users/groups
|
||||
5. Monitor performance
|
||||
|
||||
## Agent Settings and Configuration
|
||||
|
||||
### Organizational Settings
|
||||
Configure at tenant level:
|
||||
- Enable/disable agent creation
|
||||
- Set default permissions
|
||||
- Configure approval workflows
|
||||
- Define compliance policies
|
||||
|
||||
### Per-Agent Settings
|
||||
Configure for individual agents:
|
||||
- Availability (on/off)
|
||||
- User assignment (all/groups/individuals)
|
||||
- Permission scopes
|
||||
- Usage limits or quotas
|
||||
|
||||
### Environment Routing
|
||||
For Power Platform-based agents:
|
||||
- Configure default environment
|
||||
- Enable environment routing for Copilot Studio
|
||||
- Manage flows via Power Platform admin center
|
||||
|
||||
## Shared Agent Management
|
||||
|
||||
### View Shared Agents
|
||||
Admins can see:
|
||||
- List of all shared agents
|
||||
- Creator information
|
||||
- Creation date
|
||||
- Host products
|
||||
- Availability status
|
||||
|
||||
### Manage Shared Agents
|
||||
Admin actions:
|
||||
- Search for specific shared agents
|
||||
- View agent capabilities
|
||||
- Block unsafe or non-compliant agents
|
||||
- Monitor agent lifecycle
|
||||
|
||||
### User Access to Shared Agents
|
||||
Users access through:
|
||||
- Microsoft 365 Copilot on various surfaces
|
||||
- Agent-specific tasks and assistance
|
||||
- Creator-defined capabilities
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Deployment
|
||||
- **Pilot test** with small user group
|
||||
- **Gather feedback** from early adopters
|
||||
- **Validate security** and compliance
|
||||
- **Document** agent capabilities and limitations
|
||||
- **Train users** on agent usage
|
||||
|
||||
### During Deployment
|
||||
- **Phased rollout** to manage adoption
|
||||
- **Monitor performance** and errors
|
||||
- **Collect feedback** continuously
|
||||
- **Address issues** promptly
|
||||
- **Communicate** availability to users
|
||||
|
||||
### Post-Deployment
|
||||
- **Track metrics**: Adoption, satisfaction, errors
|
||||
- **Iterate**: Improve based on feedback
|
||||
- **Update**: Keep agent current with new features
|
||||
- **Retire**: Remove obsolete or unused agents
|
||||
- **Review**: Regular security and compliance audits
|
||||
|
||||
### Communication
|
||||
- Announce new agents to users
|
||||
- Provide documentation and examples
|
||||
- Share best practices and use cases
|
||||
- Highlight benefits and capabilities
|
||||
- Offer support channels
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent Not Appearing
|
||||
- Check deployment status in admin center
|
||||
- Verify user is in assigned group
|
||||
- Confirm agent is not blocked
|
||||
- Check user has Copilot license
|
||||
- Refresh Copilot interface
|
||||
|
||||
### Authentication Failures
|
||||
- Verify OAuth credentials are valid
|
||||
- Check user has necessary permissions
|
||||
- Confirm MCP server is accessible
|
||||
- Test authentication flow independently
|
||||
|
||||
### Performance Issues
|
||||
- Monitor MCP server response times
|
||||
- Check network connectivity
|
||||
- Review error logs in admin center
|
||||
- Validate agent isn't rate-limited
|
||||
|
||||
### Compliance Violations
|
||||
- Block agent immediately if unsafe
|
||||
- Review audit logs for violations
|
||||
- Investigate data access patterns
|
||||
- Update policies to prevent recurrence
|
||||
|
||||
## Resources
|
||||
|
||||
- [Microsoft 365 admin center](https://admin.microsoft.com/)
|
||||
- [Power Platform admin center](https://admin.powerplatform.microsoft.com/)
|
||||
- [Partner Center](https://partner.microsoft.com/) for agent submissions
|
||||
- [Microsoft Agent 365 Overview](https://learn.microsoft.com/en-us/microsoft-agent-365/overview)
|
||||
- [Agent Registry Documentation](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/agent-registry)
|
||||
|
||||
## Workflow
|
||||
|
||||
Ask the user:
|
||||
1. Is this agent ready for deployment or still in development?
|
||||
2. Who should have access (all users, specific groups, individuals)?
|
||||
3. Are there compliance or security requirements to address?
|
||||
4. Should this be published to the organization or the public store?
|
||||
5. What monitoring and reporting is needed?
|
||||
|
||||
Then provide:
|
||||
- Step-by-step deployment guide
|
||||
- Admin center configuration steps
|
||||
- User assignment recommendations
|
||||
- Governance and compliance checklist
|
||||
- Monitoring and reporting plan
|
||||
|
||||
````
|
||||
421
prompts/typespec-api-operations.prompt.md
Normal file
421
prompts/typespec-api-operations.prompt.md
Normal file
@@ -0,0 +1,421 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
|
||||
description: 'Add GET, POST, PATCH, and DELETE operations to a TypeSpec API plugin with proper routing, parameters, and adaptive cards'
|
||||
model: 'gpt-4.1'
|
||||
tags: [typespec, m365-copilot, api-plugin, rest-operations, crud]
|
||||
---
|
||||
|
||||
# Add TypeSpec API Operations
|
||||
|
||||
Add RESTful operations to an existing TypeSpec API plugin for Microsoft 365 Copilot.
|
||||
|
||||
## Adding GET Operations
|
||||
|
||||
### Simple GET - List All Items
|
||||
```typescript
|
||||
/**
|
||||
* List all items.
|
||||
*/
|
||||
@route("/items")
|
||||
@get op listItems(): Item[];
|
||||
```
|
||||
|
||||
### GET with Query Parameter - Filter Results
|
||||
```typescript
|
||||
/**
|
||||
* List items filtered by criteria.
|
||||
* @param userId Optional user ID to filter items
|
||||
*/
|
||||
@route("/items")
|
||||
@get op listItems(@query userId?: integer): Item[];
|
||||
```
|
||||
|
||||
### GET with Path Parameter - Get Single Item
|
||||
```typescript
|
||||
/**
|
||||
* Get a specific item by ID.
|
||||
* @param id The ID of the item to retrieve
|
||||
*/
|
||||
@route("/items/{id}")
|
||||
@get op getItem(@path id: integer): Item;
|
||||
```
|
||||
|
||||
### GET with Adaptive Card
|
||||
```typescript
|
||||
/**
|
||||
* List items with adaptive card visualization.
|
||||
*/
|
||||
@route("/items")
|
||||
@card(#{
|
||||
dataPath: "$",
|
||||
title: "$.title",
|
||||
file: "item-card.json"
|
||||
})
|
||||
@get op listItems(): Item[];
|
||||
```
|
||||
|
||||
**Create the Adaptive Card** (`appPackage/item-card.json`):
|
||||
```json
|
||||
{
|
||||
"type": "AdaptiveCard",
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${$root}",
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "**${if(title, title, 'N/A')}**",
|
||||
"wrap": true
|
||||
},
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${if(description, description, 'N/A')}",
|
||||
"wrap": true
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
{
|
||||
"type": "Action.OpenUrl",
|
||||
"title": "View Details",
|
||||
"url": "https://example.com/items/${id}"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Adding POST Operations
|
||||
|
||||
### Simple POST - Create Item
|
||||
```typescript
|
||||
/**
|
||||
* Create a new item.
|
||||
* @param item The item to create
|
||||
*/
|
||||
@route("/items")
|
||||
@post op createItem(@body item: CreateItemRequest): Item;
|
||||
|
||||
model CreateItemRequest {
|
||||
title: string;
|
||||
description?: string;
|
||||
userId: integer;
|
||||
}
|
||||
```
|
||||
|
||||
### POST with Confirmation
|
||||
```typescript
|
||||
/**
|
||||
* Create a new item with confirmation.
|
||||
*/
|
||||
@route("/items")
|
||||
@post
|
||||
@capabilities(#{
|
||||
confirmation: #{
|
||||
type: "AdaptiveCard",
|
||||
title: "Create Item",
|
||||
body: """
|
||||
Are you sure you want to create this item?
|
||||
* **Title**: {{ function.parameters.item.title }}
|
||||
* **User ID**: {{ function.parameters.item.userId }}
|
||||
"""
|
||||
}
|
||||
})
|
||||
op createItem(@body item: CreateItemRequest): Item;
|
||||
```
|
||||
|
||||
## Adding PATCH Operations
|
||||
|
||||
### Simple PATCH - Update Item
|
||||
```typescript
|
||||
/**
|
||||
* Update an existing item.
|
||||
* @param id The ID of the item to update
|
||||
* @param item The updated item data
|
||||
*/
|
||||
@route("/items/{id}")
|
||||
@patch op updateItem(
|
||||
@path id: integer,
|
||||
@body item: UpdateItemRequest
|
||||
): Item;
|
||||
|
||||
model UpdateItemRequest {
|
||||
title?: string;
|
||||
description?: string;
|
||||
status?: "active" | "completed" | "archived";
|
||||
}
|
||||
```
|
||||
|
||||
### PATCH with Confirmation
|
||||
```typescript
|
||||
/**
|
||||
* Update an item with confirmation.
|
||||
*/
|
||||
@route("/items/{id}")
|
||||
@patch
|
||||
@capabilities(#{
|
||||
confirmation: #{
|
||||
type: "AdaptiveCard",
|
||||
title: "Update Item",
|
||||
body: """
|
||||
Updating item #{{ function.parameters.id }}:
|
||||
* **Title**: {{ function.parameters.item.title }}
|
||||
* **Status**: {{ function.parameters.item.status }}
|
||||
"""
|
||||
}
|
||||
})
|
||||
op updateItem(
|
||||
@path id: integer,
|
||||
@body item: UpdateItemRequest
|
||||
): Item;
|
||||
```
|
||||
|
||||
## Adding DELETE Operations
|
||||
|
||||
### Simple DELETE
|
||||
```typescript
|
||||
/**
|
||||
* Delete an item.
|
||||
* @param id The ID of the item to delete
|
||||
*/
|
||||
@route("/items/{id}")
|
||||
@delete op deleteItem(@path id: integer): void;
|
||||
```
|
||||
|
||||
### DELETE with Confirmation
|
||||
```typescript
|
||||
/**
|
||||
* Delete an item with confirmation.
|
||||
*/
|
||||
@route("/items/{id}")
|
||||
@delete
|
||||
@capabilities(#{
|
||||
confirmation: #{
|
||||
type: "AdaptiveCard",
|
||||
title: "Delete Item",
|
||||
body: """
|
||||
⚠️ Are you sure you want to delete item #{{ function.parameters.id }}?
|
||||
This action cannot be undone.
|
||||
"""
|
||||
}
|
||||
})
|
||||
op deleteItem(@path id: integer): void;
|
||||
```
|
||||
|
||||
## Complete CRUD Example
|
||||
|
||||
### Define the Service and Models
|
||||
```typescript
|
||||
@service
|
||||
@server("https://api.example.com")
|
||||
@actions(#{
|
||||
nameForHuman: "Items API",
|
||||
descriptionForHuman: "Manage items",
|
||||
descriptionForModel: "Read, create, update, and delete items"
|
||||
})
|
||||
namespace ItemsAPI {
|
||||
|
||||
// Models
|
||||
model Item {
|
||||
@visibility(Lifecycle.Read)
|
||||
id: integer;
|
||||
|
||||
userId: integer;
|
||||
title: string;
|
||||
description?: string;
|
||||
status: "active" | "completed" | "archived";
|
||||
|
||||
@format("date-time")
|
||||
createdAt: utcDateTime;
|
||||
|
||||
@format("date-time")
|
||||
updatedAt?: utcDateTime;
|
||||
}
|
||||
|
||||
model CreateItemRequest {
|
||||
userId: integer;
|
||||
title: string;
|
||||
description?: string;
|
||||
}
|
||||
|
||||
model UpdateItemRequest {
|
||||
title?: string;
|
||||
description?: string;
|
||||
status?: "active" | "completed" | "archived";
|
||||
}
|
||||
|
||||
// Operations
|
||||
@route("/items")
|
||||
@card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
|
||||
@get op listItems(@query userId?: integer): Item[];
|
||||
|
||||
@route("/items/{id}")
|
||||
@card(#{ dataPath: "$", title: "$.title", file: "item-card.json" })
|
||||
@get op getItem(@path id: integer): Item;
|
||||
|
||||
@route("/items")
|
||||
@post
|
||||
@capabilities(#{
|
||||
confirmation: #{
|
||||
type: "AdaptiveCard",
|
||||
title: "Create Item",
|
||||
body: "Creating: **{{ function.parameters.item.title }}**"
|
||||
}
|
||||
})
|
||||
op createItem(@body item: CreateItemRequest): Item;
|
||||
|
||||
@route("/items/{id}")
|
||||
@patch
|
||||
@capabilities(#{
|
||||
confirmation: #{
|
||||
type: "AdaptiveCard",
|
||||
title: "Update Item",
|
||||
body: "Updating item #{{ function.parameters.id }}"
|
||||
}
|
||||
})
|
||||
op updateItem(@path id: integer, @body item: UpdateItemRequest): Item;
|
||||
|
||||
@route("/items/{id}")
|
||||
@delete
|
||||
@capabilities(#{
|
||||
confirmation: #{
|
||||
type: "AdaptiveCard",
|
||||
title: "Delete Item",
|
||||
body: "⚠️ Delete item #{{ function.parameters.id }}?"
|
||||
}
|
||||
})
|
||||
op deleteItem(@path id: integer): void;
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Multiple Query Parameters
|
||||
```typescript
|
||||
@route("/items")
|
||||
@get op listItems(
|
||||
@query userId?: integer,
|
||||
@query status?: "active" | "completed" | "archived",
|
||||
@query limit?: integer,
|
||||
@query offset?: integer
|
||||
): ItemList;
|
||||
|
||||
model ItemList {
|
||||
items: Item[];
|
||||
total: integer;
|
||||
hasMore: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### Header Parameters
|
||||
```typescript
|
||||
@route("/items")
|
||||
@get op listItems(
|
||||
@header("X-API-Version") apiVersion?: string,
|
||||
@query userId?: integer
|
||||
): Item[];
|
||||
```
|
||||
|
||||
### Custom Response Models
|
||||
```typescript
|
||||
@route("/items/{id}")
|
||||
@delete op deleteItem(@path id: integer): DeleteResponse;
|
||||
|
||||
model DeleteResponse {
|
||||
success: boolean;
|
||||
message: string;
|
||||
deletedId: integer;
|
||||
}
|
||||
```
|
||||
|
||||
### Error Responses
|
||||
```typescript
|
||||
model ErrorResponse {
|
||||
error: {
|
||||
code: string;
|
||||
message: string;
|
||||
details?: string[];
|
||||
};
|
||||
}
|
||||
|
||||
@route("/items/{id}")
|
||||
@get op getItem(@path id: integer): Item | ErrorResponse;
|
||||
```
|
||||
|
||||
## Testing Prompts
|
||||
|
||||
After adding operations, test with these prompts:
|
||||
|
||||
**GET Operations:**
|
||||
- "List all items and show them in a table"
|
||||
- "Show me items for user ID 1"
|
||||
- "Get the details of item 42"
|
||||
|
||||
**POST Operations:**
|
||||
- "Create a new item with title 'My Task' for user 1"
|
||||
- "Add an item: title 'New Feature', description 'Add login'"
|
||||
|
||||
**PATCH Operations:**
|
||||
- "Update item 10 with title 'Updated Title'"
|
||||
- "Change the status of item 5 to completed"
|
||||
|
||||
**DELETE Operations:**
|
||||
- "Delete item 99"
|
||||
- "Remove the item with ID 15"
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Parameter Naming
|
||||
- Use descriptive parameter names: `userId` not `uid`
|
||||
- Be consistent across operations
|
||||
- Use optional parameters (`?`) for filters
|
||||
|
||||
### Documentation
|
||||
- Add JSDoc comments to all operations
|
||||
- Describe what each parameter does
|
||||
- Document expected responses
|
||||
|
||||
### Models
|
||||
- Use `@visibility(Lifecycle.Read)` for read-only fields like `id`
|
||||
- Use `@format("date-time")` for date fields
|
||||
- Use union types for enums: `"active" | "completed"`
|
||||
- Make optional fields explicit with `?`
|
||||
|
||||
### Confirmations
|
||||
- Always add confirmations to destructive operations (DELETE, PATCH)
|
||||
- Show key details in confirmation body
|
||||
- Use warning emoji (⚠️) for irreversible actions
|
||||
|
||||
### Adaptive Cards
|
||||
- Keep cards simple and focused
|
||||
- Use conditional rendering with `${if(..., ..., 'N/A')}`
|
||||
- Include action buttons for common next steps
|
||||
- Test data binding with actual API responses
|
||||
|
||||
### Routing
|
||||
- Use RESTful conventions:
|
||||
- `GET /items` - List
|
||||
- `GET /items/{id}` - Get one
|
||||
- `POST /items` - Create
|
||||
- `PATCH /items/{id}` - Update
|
||||
- `DELETE /items/{id}` - Delete
|
||||
- Group related operations in the same namespace
|
||||
- Use nested routes for hierarchical resources
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Parameter not showing in Copilot
|
||||
**Solution**: Check parameter is properly decorated with `@query`, `@path`, or `@body`
|
||||
|
||||
### Issue: Adaptive card not rendering
|
||||
**Solution**: Verify file path in `@card` decorator and check JSON syntax
|
||||
|
||||
### Issue: Confirmation not appearing
|
||||
**Solution**: Ensure `@capabilities` decorator is properly formatted with confirmation object
|
||||
|
||||
### Issue: Model property not appearing in response
|
||||
**Solution**: Check if property needs `@visibility(Lifecycle.Read)` or remove it if it should be writable
|
||||
94
prompts/typespec-create-agent.prompt.md
Normal file
94
prompts/typespec-create-agent.prompt.md
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
|
||||
description: 'Generate a complete TypeSpec declarative agent with instructions, capabilities, and conversation starters for Microsoft 365 Copilot'
|
||||
model: 'gpt-4.1'
|
||||
tags: [typespec, m365-copilot, declarative-agent, agent-development]
|
||||
---
|
||||
|
||||
# Create TypeSpec Declarative Agent
|
||||
|
||||
Create a complete TypeSpec declarative agent for Microsoft 365 Copilot with the following structure:
|
||||
|
||||
## Requirements
|
||||
|
||||
Generate a `main.tsp` file with:
|
||||
|
||||
1. **Agent Declaration**
|
||||
- Use `@agent` decorator with a descriptive name and description
|
||||
- Name should be 100 characters or less
|
||||
- Description should be 1,000 characters or less
|
||||
|
||||
2. **Instructions**
|
||||
- Use `@instructions` decorator with clear behavioral guidelines
|
||||
- Define the agent's role, expertise, and personality
|
||||
- Specify what the agent should and shouldn't do
|
||||
- Keep under 8,000 characters
|
||||
|
||||
3. **Conversation Starters**
|
||||
- Include 2-4 `@conversationStarter` decorators
|
||||
- Each with a title and example query
|
||||
- Make them diverse and showcase different capabilities
|
||||
|
||||
4. **Capabilities** (based on user needs)
|
||||
- `WebSearch` - for web content with optional site scoping
|
||||
- `OneDriveAndSharePoint` - for document access with URL filtering
|
||||
- `TeamsMessages` - for Teams channel/chat access
|
||||
- `Email` - for email access with folder filtering
|
||||
- `People` - for organization people search
|
||||
- `CodeInterpreter` - for Python code execution
|
||||
- `GraphicArt` - for image generation
|
||||
- `GraphConnectors` - for Copilot connector content
|
||||
- `Dataverse` - for Dataverse data access
|
||||
- `Meetings` - for meeting content access
|
||||
|
||||
## Template Structure
|
||||
|
||||
```typescript
|
||||
import "@typespec/http";
|
||||
import "@typespec/openapi3";
|
||||
import "@microsoft/typespec-m365-copilot";
|
||||
|
||||
using TypeSpec.Http;
|
||||
using TypeSpec.M365.Copilot.Agents;
|
||||
|
||||
@agent({
|
||||
name: "[Agent Name]",
|
||||
description: "[Agent Description]"
|
||||
})
|
||||
@instructions("""
|
||||
[Detailed instructions about agent behavior, role, and guidelines]
|
||||
""")
|
||||
@conversationStarter(#{
|
||||
title: "[Starter Title 1]",
|
||||
text: "[Example query 1]"
|
||||
})
|
||||
@conversationStarter(#{
|
||||
title: "[Starter Title 2]",
|
||||
text: "[Example query 2]"
|
||||
})
|
||||
namespace [AgentName] {
|
||||
// Add capabilities as operations here
|
||||
op capabilityName is AgentCapabilities.[CapabilityType]<[Parameters]>;
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Use descriptive, role-based agent names (e.g., "Customer Support Assistant", "Research Helper")
|
||||
- Write instructions in second person ("You are...")
|
||||
- Be specific about the agent's expertise and limitations
|
||||
- Include diverse conversation starters that showcase different features
|
||||
- Only include capabilities the agent actually needs
|
||||
- Scope capabilities (URLs, folders, etc.) when possible for better performance
|
||||
- Use triple-quoted strings for multi-line instructions
|
||||
|
||||
## Examples
|
||||
|
||||
Ask the user:
|
||||
1. What is the agent's purpose and role?
|
||||
2. What capabilities does it need?
|
||||
3. What knowledge sources should it access?
|
||||
4. What are typical user interactions?
|
||||
|
||||
Then generate the complete TypeSpec agent definition.
|
||||
167
prompts/typespec-create-api-plugin.prompt.md
Normal file
167
prompts/typespec-create-api-plugin.prompt.md
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
mode: 'agent'
|
||||
tools: ['changes', 'search/codebase', 'edit/editFiles', 'problems']
|
||||
description: 'Generate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot'
|
||||
model: 'gpt-4.1'
|
||||
tags: [typespec, m365-copilot, api-plugin, rest-api]
|
||||
---
|
||||
|
||||
# Create TypeSpec API Plugin
|
||||
|
||||
Create a complete TypeSpec API plugin for Microsoft 365 Copilot that integrates with external REST APIs.
|
||||
|
||||
## Requirements
|
||||
|
||||
Generate TypeSpec files with:
|
||||
|
||||
### main.tsp - Agent Definition
|
||||
```typescript
|
||||
import "@typespec/http";
|
||||
import "@typespec/openapi3";
|
||||
import "@microsoft/typespec-m365-copilot";
|
||||
import "./actions.tsp";
|
||||
|
||||
using TypeSpec.Http;
|
||||
using TypeSpec.M365.Copilot.Agents;
|
||||
using TypeSpec.M365.Copilot.Actions;
|
||||
|
||||
@agent({
|
||||
name: "[Agent Name]",
|
||||
description: "[Description]"
|
||||
})
|
||||
@instructions("""
|
||||
[Instructions for using the API operations]
|
||||
""")
|
||||
namespace [AgentName] {
|
||||
// Reference operations from actions.tsp
|
||||
op operation1 is [APINamespace].operationName;
|
||||
}
|
||||
```
|
||||
|
||||
### actions.tsp - API Operations
|
||||
```typescript
|
||||
import "@typespec/http";
|
||||
import "@microsoft/typespec-m365-copilot";
|
||||
|
||||
using TypeSpec.Http;
|
||||
using TypeSpec.M365.Copilot.Actions;
|
||||
|
||||
@service
|
||||
@actions(#{
|
||||
nameForHuman: "[API Display Name]",
|
||||
descriptionForModel: "[Model description]",
|
||||
descriptionForHuman: "[User description]"
|
||||
})
|
||||
@server("[API_BASE_URL]", "[API Name]")
|
||||
@useAuth([AuthType]) // Optional
|
||||
namespace [APINamespace] {
|
||||
|
||||
@route("[/path]")
|
||||
@get
|
||||
@action
|
||||
op operationName(
|
||||
@path param1: string,
|
||||
@query param2?: string
|
||||
): ResponseModel;
|
||||
|
||||
model ResponseModel {
|
||||
// Response structure
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Authentication Options
|
||||
|
||||
Choose based on API requirements:
|
||||
|
||||
1. **No Authentication** (Public APIs)
|
||||
```typescript
|
||||
// No @useAuth decorator needed
|
||||
```
|
||||
|
||||
2. **API Key**
|
||||
```typescript
|
||||
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)
|
||||
```
|
||||
|
||||
3. **OAuth2**
|
||||
```typescript
|
||||
@useAuth(OAuth2Auth<[{
|
||||
type: OAuth2FlowType.authorizationCode;
|
||||
authorizationUrl: "https://oauth.example.com/authorize";
|
||||
tokenUrl: "https://oauth.example.com/token";
|
||||
refreshUrl: "https://oauth.example.com/token";
|
||||
scopes: ["read", "write"];
|
||||
}]>)
|
||||
```
|
||||
|
||||
4. **Registered Auth Reference**
|
||||
```typescript
|
||||
@useAuth(Auth)
|
||||
|
||||
@authReferenceId("registration-id-here")
|
||||
model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">
|
||||
```
|
||||
|
||||
## Function Capabilities
|
||||
|
||||
### Confirmation Dialog
|
||||
```typescript
|
||||
@capabilities(#{
|
||||
confirmation: #{
|
||||
type: "AdaptiveCard",
|
||||
title: "Confirm Action",
|
||||
body: """
|
||||
Are you sure you want to perform this action?
|
||||
* **Parameter**: {{ function.parameters.paramName }}
|
||||
"""
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Adaptive Card Response
|
||||
```typescript
|
||||
@card(#{
|
||||
dataPath: "$.items",
|
||||
title: "$.title",
|
||||
url: "$.link",
|
||||
file: "cards/card.json"
|
||||
})
|
||||
```
|
||||
|
||||
### Reasoning & Response Instructions
|
||||
```typescript
|
||||
@reasoning("""
|
||||
Consider user's context when calling this operation.
|
||||
Prioritize recent items over older ones.
|
||||
""")
|
||||
@responding("""
|
||||
Present results in a clear table format with columns: ID, Title, Status.
|
||||
Include a summary count at the end.
|
||||
""")
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Operation Names**: Use clear, action-oriented names (listProjects, createTicket)
|
||||
2. **Models**: Define TypeScript-like models for requests and responses
|
||||
3. **HTTP Methods**: Use appropriate verbs (@get, @post, @patch, @delete)
|
||||
4. **Paths**: Use RESTful path conventions with @route
|
||||
5. **Parameters**: Use @path, @query, @header, @body appropriately
|
||||
6. **Descriptions**: Provide clear descriptions for model understanding
|
||||
7. **Confirmations**: Add for destructive operations (delete, update critical data)
|
||||
8. **Cards**: Use for rich visual responses with multiple data items
|
||||
|
||||
## Workflow
|
||||
|
||||
Ask the user:
|
||||
1. What is the API base URL and purpose?
|
||||
2. What operations are needed (CRUD operations)?
|
||||
3. What authentication method does the API use?
|
||||
4. Should confirmations be required for any operations?
|
||||
5. Do responses need Adaptive Cards?
|
||||
|
||||
Then generate:
|
||||
- Complete `main.tsp` with agent definition
|
||||
- Complete `actions.tsp` with API operations and models
|
||||
- Optional `cards/card.json` if Adaptive Cards are needed
|
||||
Reference in New Issue
Block a user