mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-20 10:25:13 +00:00
Merge branch 'main' into add-lws-instructions
This commit is contained in:
Matt Soucoup
GitHub
791
instructions/agents.instructions.md
Normal file
791
instructions/agents.instructions.md
Normal file
@@ -0,0 +1,791 @@
|
||||
---
|
||||
description: 'Guidelines for creating custom agent files for GitHub Copilot'
|
||||
applyTo: '**/*.agent.md'
|
||||
---
|
||||
|
||||
# Custom Agent File Guidelines
|
||||
|
||||
Instructions for creating effective and maintainable custom agent files that provide specialized expertise for specific development tasks in GitHub Copilot.
|
||||
|
||||
## Project Context
|
||||
|
||||
- Target audience: Developers creating custom agents for GitHub Copilot
|
||||
- File format: Markdown with YAML frontmatter
|
||||
- File naming convention: lowercase with hyphens (e.g., `test-specialist.agent.md`)
|
||||
- Location: `.github/agents/` directory (repository-level) or `agents/` directory (organization/enterprise-level)
|
||||
- Purpose: Define specialized agents with tailored expertise, tools, and instructions for specific tasks
|
||||
- Official documentation: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents
|
||||
|
||||
## Required Frontmatter
|
||||
|
||||
Every agent file must include YAML frontmatter with the following fields:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: 'Brief description of the agent purpose and capabilities'
|
||||
name: 'Agent Display Name'
|
||||
tools: ['read', 'edit', 'search']
|
||||
model: 'Claude Sonnet 4.5'
|
||||
target: 'vscode'
|
||||
infer: true
|
||||
---
|
||||
```
|
||||
|
||||
### Core Frontmatter Properties
|
||||
|
||||
#### **description** (REQUIRED)
|
||||
- Single-quoted string, clearly stating the agent's purpose and domain expertise
|
||||
- Should be concise (50-150 characters) and actionable
|
||||
- Example: `'Focuses on test coverage, quality, and testing best practices'`
|
||||
|
||||
#### **name** (OPTIONAL)
|
||||
- Display name for the agent in the UI
|
||||
- If omitted, defaults to filename (without `.md` or `.agent.md`)
|
||||
- Use title case and be descriptive
|
||||
- Example: `'Testing Specialist'`
|
||||
|
||||
#### **tools** (OPTIONAL)
|
||||
- List of tool names or aliases the agent can use
|
||||
- Supports comma-separated string or YAML array format
|
||||
- If omitted, agent has access to all available tools
|
||||
- See "Tool Configuration" section below for details
|
||||
|
||||
#### **model** (STRONGLY RECOMMENDED)
|
||||
- Specifies which AI model the agent should use
|
||||
- Supported in VS Code, JetBrains IDEs, Eclipse, and Xcode
|
||||
- Example: `'Claude Sonnet 4.5'`, `'gpt-4'`, `'gpt-4o'`
|
||||
- Choose based on agent complexity and required capabilities
|
||||
|
||||
#### **target** (OPTIONAL)
|
||||
- Specifies target environment: `'vscode'` or `'github-copilot'`
|
||||
- If omitted, agent is available in both environments
|
||||
- Use when agent has environment-specific features
|
||||
|
||||
#### **infer** (OPTIONAL)
|
||||
- Boolean controlling whether Copilot can automatically use this agent based on context
|
||||
- Default: `true` if omitted
|
||||
- Set to `false` to require manual agent selection
|
||||
|
||||
#### **metadata** (OPTIONAL, GitHub.com only)
|
||||
- Object with name-value pairs for agent annotation
|
||||
- Example: `metadata: { category: 'testing', version: '1.0' }`
|
||||
- Not supported in VS Code
|
||||
|
||||
#### **mcp-servers** (OPTIONAL, Organization/Enterprise only)
|
||||
- Configure MCP servers available only to this agent
|
||||
- Only supported for organization/enterprise level agents
|
||||
- See "MCP Server Configuration" section below
|
||||
|
||||
## Tool Configuration
|
||||
|
||||
### Tool Specification Strategies
|
||||
|
||||
**Enable all tools** (default):
|
||||
```yaml
|
||||
# Omit tools property entirely, or use:
|
||||
tools: ['*']
|
||||
```
|
||||
|
||||
**Enable specific tools**:
|
||||
```yaml
|
||||
tools: ['read', 'edit', 'search', 'execute']
|
||||
```
|
||||
|
||||
**Enable MCP server tools**:
|
||||
```yaml
|
||||
tools: ['read', 'edit', 'github/*', 'playwright/navigate']
|
||||
```
|
||||
|
||||
**Disable all tools**:
|
||||
```yaml
|
||||
tools: []
|
||||
```
|
||||
|
||||
### Standard Tool Aliases
|
||||
|
||||
All aliases are case-insensitive:
|
||||
|
||||
| Alias | Alternative Names | Category | Description |
|
||||
|-------|------------------|----------|-------------|
|
||||
| `execute` | shell, Bash, powershell | Shell execution | Execute commands in appropriate shell |
|
||||
| `read` | Read, NotebookRead, view | File reading | Read file contents |
|
||||
| `edit` | Edit, MultiEdit, Write, NotebookEdit | File editing | Edit and modify files |
|
||||
| `search` | Grep, Glob, search | Code search | Search for files or text in files |
|
||||
| `agent` | custom-agent, Task | Agent invocation | Invoke other custom agents |
|
||||
| `web` | WebSearch, WebFetch | Web access | Fetch web content and search |
|
||||
| `todo` | TodoWrite | Task management | Create and manage task lists (VS Code only) |
|
||||
|
||||
### Built-in MCP Server Tools
|
||||
|
||||
**GitHub MCP Server**:
|
||||
```yaml
|
||||
tools: ['github/*'] # All GitHub tools
|
||||
tools: ['github/get_file_contents', 'github/search_repositories'] # Specific tools
|
||||
```
|
||||
- All read-only tools available by default
|
||||
- Token scoped to source repository
|
||||
|
||||
**Playwright MCP Server**:
|
||||
```yaml
|
||||
tools: ['playwright/*'] # All Playwright tools
|
||||
tools: ['playwright/navigate', 'playwright/screenshot'] # Specific tools
|
||||
```
|
||||
- Configured to access localhost only
|
||||
- Useful for browser automation and testing
|
||||
|
||||
### Tool Selection Best Practices
|
||||
|
||||
- **Principle of Least Privilege**: Only enable tools necessary for the agent's purpose
|
||||
- **Security**: Limit `execute` access unless explicitly required
|
||||
- **Focus**: Fewer tools = clearer agent purpose and better performance
|
||||
- **Documentation**: Comment why specific tools are required for complex configurations
|
||||
|
||||
## Sub-Agent Invocation (Agent Orchestration)
|
||||
|
||||
Agents can invoke other agents using `runSubagent` to orchestrate multi-step workflows.
|
||||
|
||||
### How It Works
|
||||
|
||||
Include `agent` in tools list to enable sub-agent invocation:
|
||||
|
||||
```yaml
|
||||
tools: ['read', 'edit', 'search', 'agent']
|
||||
```
|
||||
|
||||
Then invoke other agents with `runSubagent`:
|
||||
|
||||
```javascript
|
||||
const result = await runSubagent({
|
||||
description: 'What this step does',
|
||||
prompt: `You are the [Specialist] specialist.
|
||||
|
||||
Context:
|
||||
- Parameter: ${parameterValue}
|
||||
- Input: ${inputPath}
|
||||
- Output: ${outputPath}
|
||||
|
||||
Task:
|
||||
1. Do the specific work
|
||||
2. Write results to output location
|
||||
3. Return summary of completion`
|
||||
});
|
||||
```
|
||||
|
||||
### Basic Pattern
|
||||
|
||||
Structure each sub-agent call with:
|
||||
|
||||
1. **description**: Clear one-line purpose of the sub-agent invocation
|
||||
2. **prompt**: Detailed instructions with substituted variables
|
||||
|
||||
The prompt should include:
|
||||
- Who the sub-agent is (specialist role)
|
||||
- What context it needs (parameters, paths)
|
||||
- What to do (concrete tasks)
|
||||
- Where to write output
|
||||
- What to return (summary)
|
||||
|
||||
### Example: Multi-Step Processing
|
||||
|
||||
```javascript
|
||||
// Step 1: Process data
|
||||
const processing = await runSubagent({
|
||||
description: 'Transform raw input data',
|
||||
prompt: `You are the Data Processor specialist.
|
||||
|
||||
Project: ${projectName}
|
||||
Input: ${basePath}/raw/
|
||||
Output: ${basePath}/processed/
|
||||
|
||||
Task:
|
||||
1. Read all files from input directory
|
||||
2. Apply transformations
|
||||
3. Write processed files to output
|
||||
4. Create summary: ${basePath}/processed/summary.md
|
||||
|
||||
Return: Number of files processed and any issues found`
|
||||
});
|
||||
|
||||
// Step 2: Analyze (depends on Step 1)
|
||||
const analysis = await runSubagent({
|
||||
description: 'Analyze processed data',
|
||||
prompt: `You are the Data Analyst specialist.
|
||||
|
||||
Project: ${projectName}
|
||||
Input: ${basePath}/processed/
|
||||
Output: ${basePath}/analysis/
|
||||
|
||||
Task:
|
||||
1. Read processed files from input
|
||||
2. Generate analysis report
|
||||
3. Write to: ${basePath}/analysis/report.md
|
||||
|
||||
Return: Key findings and identified patterns`
|
||||
});
|
||||
```
|
||||
|
||||
### Key Points
|
||||
|
||||
- **Pass variables in prompts**: Use `${variableName}` for all dynamic values
|
||||
- **Keep prompts focused**: Clear, specific tasks for each sub-agent
|
||||
- **Return summaries**: Each sub-agent should report what it accomplished
|
||||
- **Sequential execution**: Use `await` to maintain order when steps depend on each other
|
||||
- **Error handling**: Check results before proceeding to dependent steps
|
||||
|
||||
### ⚠️ Tool Availability Requirement
|
||||
|
||||
**Critical**: If a sub-agent requires specific tools (e.g., `edit`, `execute`, `search`), the orchestrator must include those tools in its own `tools` list. Sub-agents cannot access tools that aren't available to their parent orchestrator.
|
||||
|
||||
**Example**:
|
||||
```yaml
|
||||
# If your sub-agents need to edit files, execute commands, or search code
|
||||
tools: ['read', 'edit', 'search', 'execute', 'agent']
|
||||
```
|
||||
|
||||
The orchestrator's tool permissions act as a ceiling for all invoked sub-agents. Plan your tool list carefully to ensure all sub-agents have the tools they need.
|
||||
|
||||
### ⚠️ Important Limitation
|
||||
|
||||
**Sub-agent orchestration is NOT suitable for large-scale data processing.** Avoid using `runSubagent` when:
|
||||
- Processing hundreds or thousands of files
|
||||
- Handling large datasets
|
||||
- Performing bulk transformations on big codebases
|
||||
- Orchestrating more than 5-10 sequential steps
|
||||
|
||||
Each sub-agent call adds latency and context overhead. For high-volume processing, implement logic directly in a single agent instead. Use orchestration only for coordinating specialized tasks on focused, manageable datasets.
|
||||
|
||||
## Agent Prompt Structure
|
||||
|
||||
The markdown content below the frontmatter defines the agent's behavior, expertise, and instructions. Well-structured prompts typically include:
|
||||
|
||||
1. **Agent Identity and Role**: Who the agent is and its primary role
|
||||
2. **Core Responsibilities**: What specific tasks the agent performs
|
||||
3. **Approach and Methodology**: How the agent works to accomplish tasks
|
||||
4. **Guidelines and Constraints**: What to do/avoid and quality standards
|
||||
5. **Output Expectations**: Expected output format and quality
|
||||
|
||||
### Prompt Writing Best Practices
|
||||
|
||||
- **Be Specific and Direct**: Use imperative mood ("Analyze", "Generate"); avoid vague terms
|
||||
- **Define Boundaries**: Clearly state scope limits and constraints
|
||||
- **Include Context**: Explain domain expertise and reference relevant frameworks
|
||||
- **Focus on Behavior**: Describe how the agent should think and work
|
||||
- **Use Structured Format**: Headers, bullets, and lists make prompts scannable
|
||||
|
||||
## Variable Definition and Extraction
|
||||
|
||||
Agents can define dynamic parameters to extract values from user input and use them throughout the agent's behavior and sub-agent communications. This enables flexible, context-aware agents that adapt to user-provided data.
|
||||
|
||||
### When to Use Variables
|
||||
|
||||
**Use variables when**:
|
||||
- Agent behavior depends on user input
|
||||
- Need to pass dynamic values to sub-agents
|
||||
- Want to make agents reusable across different contexts
|
||||
- Require parameterized workflows
|
||||
- Need to track or reference user-provided context
|
||||
|
||||
**Examples**:
|
||||
- Extract project name from user prompt
|
||||
- Capture certification name for pipeline processing
|
||||
- Identify file paths or directories
|
||||
- Extract configuration options
|
||||
- Parse feature names or module identifiers
|
||||
|
||||
### Variable Declaration Pattern
|
||||
|
||||
Define variables section early in the agent prompt to document expected parameters:
|
||||
|
||||
```markdown
|
||||
# Agent Name
|
||||
|
||||
## Dynamic Parameters
|
||||
|
||||
- **Parameter Name**: Description and usage
|
||||
- **Another Parameter**: How it's extracted and used
|
||||
|
||||
## Your Mission
|
||||
|
||||
Process [PARAMETER_NAME] to accomplish [task].
|
||||
```
|
||||
|
||||
### Variable Extraction Methods
|
||||
|
||||
#### 1. **Explicit User Input**
|
||||
Ask the user to provide the variable if not detected in the prompt:
|
||||
|
||||
```markdown
|
||||
## Your Mission
|
||||
|
||||
Process the project by analyzing your codebase.
|
||||
|
||||
### Step 1: Identify Project
|
||||
If no project name is provided, **ASK THE USER** for:
|
||||
- Project name or identifier
|
||||
- Base path or directory location
|
||||
- Configuration type (if applicable)
|
||||
|
||||
Use this information to contextualize all subsequent tasks.
|
||||
```
|
||||
|
||||
#### 2. **Implicit Extraction from Prompt**
|
||||
Automatically extract variables from the user's natural language input:
|
||||
|
||||
```javascript
|
||||
// Example: Extract certification name from user input
|
||||
const userInput = "Process My Certification";
|
||||
|
||||
// Extract key information
|
||||
const certificationName = extractCertificationName(userInput);
|
||||
// Result: "My Certification"
|
||||
|
||||
const basePath = `certifications/${certificationName}`;
|
||||
// Result: "certifications/My Certification"
|
||||
```
|
||||
|
||||
#### 3. **Contextual Variable Resolution**
|
||||
Use file context or workspace information to derive variables:
|
||||
|
||||
```markdown
|
||||
## Variable Resolution Strategy
|
||||
|
||||
1. **From User Prompt**: First, look for explicit mentions in user input
|
||||
2. **From File Context**: Check current file name or path
|
||||
3. **From Workspace**: Use workspace folder or active project
|
||||
4. **From Settings**: Reference configuration files
|
||||
5. **Ask User**: If all else fails, request missing information
|
||||
```
|
||||
|
||||
### Using Variables in Agent Prompts
|
||||
|
||||
#### Variable Substitution in Instructions
|
||||
|
||||
Use template variables in agent prompts to make them dynamic:
|
||||
|
||||
```markdown
|
||||
# Agent Name
|
||||
|
||||
## Dynamic Parameters
|
||||
- **Project Name**: ${projectName}
|
||||
- **Base Path**: ${basePath}
|
||||
- **Output Directory**: ${outputDir}
|
||||
|
||||
## Your Mission
|
||||
|
||||
Process the **${projectName}** project located at `${basePath}`.
|
||||
|
||||
## Process Steps
|
||||
|
||||
1. Read input from: `${basePath}/input/`
|
||||
2. Process files according to project configuration
|
||||
3. Write results to: `${outputDir}/`
|
||||
4. Generate summary report
|
||||
|
||||
## Quality Standards
|
||||
|
||||
- Maintain project-specific coding standards for **${projectName}**
|
||||
- Follow directory structure: `${basePath}/[structure]`
|
||||
```
|
||||
|
||||
#### Passing Variables to Sub-Agents
|
||||
|
||||
When invoking a sub-agent, pass all context through template variables in the prompt:
|
||||
|
||||
```javascript
|
||||
// Extract and prepare variables
|
||||
const basePath = `projects/${projectName}`;
|
||||
const inputPath = `${basePath}/src/`;
|
||||
const outputPath = `${basePath}/docs/`;
|
||||
|
||||
// Pass to sub-agent with all variables substituted
|
||||
const result = await runSubagent({
|
||||
description: 'Generate project documentation',
|
||||
prompt: `You are the Documentation specialist.
|
||||
|
||||
Project: ${projectName}
|
||||
Input: ${inputPath}
|
||||
Output: ${outputPath}
|
||||
|
||||
Task:
|
||||
1. Read source files from ${inputPath}
|
||||
2. Generate comprehensive documentation
|
||||
3. Write to ${outputPath}/index.md
|
||||
4. Include code examples and usage guides
|
||||
|
||||
Return: Summary of documentation generated (file count, word count)`
|
||||
});
|
||||
```
|
||||
|
||||
The sub-agent receives all necessary context embedded in the prompt. Variables are resolved before sending the prompt, so the sub-agent works with concrete paths and values, not variable placeholders.
|
||||
|
||||
### Real-World Example: Code Review Orchestrator
|
||||
|
||||
Example of a simple orchestrator that validates code through multiple specialized agents:
|
||||
|
||||
```javascript
|
||||
async function reviewCodePipeline(repositoryName, prNumber) {
|
||||
const basePath = `projects/${repositoryName}/pr-${prNumber}`;
|
||||
|
||||
// Step 1: Security Review
|
||||
const security = await runSubagent({
|
||||
description: 'Scan for security vulnerabilities',
|
||||
prompt: `You are the Security Reviewer specialist.
|
||||
|
||||
Repository: ${repositoryName}
|
||||
PR: ${prNumber}
|
||||
Code: ${basePath}/changes/
|
||||
|
||||
Task:
|
||||
1. Scan code for OWASP Top 10 vulnerabilities
|
||||
2. Check for injection attacks, auth flaws
|
||||
3. Write findings to ${basePath}/security-review.md
|
||||
|
||||
Return: List of critical, high, and medium issues found`
|
||||
});
|
||||
|
||||
// Step 2: Test Coverage Check
|
||||
const coverage = await runSubagent({
|
||||
description: 'Verify test coverage for changes',
|
||||
prompt: `You are the Test Coverage specialist.
|
||||
|
||||
Repository: ${repositoryName}
|
||||
PR: ${prNumber}
|
||||
Changes: ${basePath}/changes/
|
||||
|
||||
Task:
|
||||
1. Analyze code coverage for modified files
|
||||
2. Identify untested critical paths
|
||||
3. Write report to ${basePath}/coverage-report.md
|
||||
|
||||
Return: Current coverage percentage and gaps`
|
||||
});
|
||||
|
||||
// Step 3: Aggregate Results
|
||||
const finalReport = await runSubagent({
|
||||
description: 'Compile all review findings',
|
||||
prompt: `You are the Review Aggregator specialist.
|
||||
|
||||
Repository: ${repositoryName}
|
||||
Reports: ${basePath}/*.md
|
||||
|
||||
Task:
|
||||
1. Read all review reports from ${basePath}/
|
||||
2. Synthesize findings into single report
|
||||
3. Determine overall verdict (APPROVE/NEEDS_FIXES/BLOCK)
|
||||
4. Write to ${basePath}/final-review.md
|
||||
|
||||
Return: Final verdict and executive summary`
|
||||
});
|
||||
|
||||
return finalReport;
|
||||
}
|
||||
```
|
||||
|
||||
This pattern applies to any orchestration scenario: extract variables, call sub-agents with clear context, await results.
|
||||
|
||||
|
||||
### Variable Best Practices
|
||||
|
||||
#### 1. **Clear Documentation**
|
||||
Always document what variables are expected:
|
||||
|
||||
```markdown
|
||||
## Required Variables
|
||||
- **projectName**: The name of the project (string, required)
|
||||
- **basePath**: Root directory for project files (path, required)
|
||||
|
||||
## Optional Variables
|
||||
- **mode**: Processing mode - quick/standard/detailed (enum, default: standard)
|
||||
- **outputFormat**: Output format - markdown/json/html (enum, default: markdown)
|
||||
|
||||
## Derived Variables
|
||||
- **outputDir**: Automatically set to ${basePath}/output
|
||||
- **logFile**: Automatically set to ${basePath}/.log.md
|
||||
```
|
||||
|
||||
#### 2. **Consistent Naming**
|
||||
Use consistent variable naming conventions:
|
||||
|
||||
```javascript
|
||||
// Good: Clear, descriptive naming
|
||||
const variables = {
|
||||
projectName, // What project to work on
|
||||
basePath, // Where project files are located
|
||||
outputDirectory, // Where to save results
|
||||
processingMode, // How to process (detail level)
|
||||
configurationPath // Where config files are
|
||||
};
|
||||
|
||||
// Avoid: Ambiguous or inconsistent
|
||||
const bad_variables = {
|
||||
name, // Too generic
|
||||
path, // Unclear which path
|
||||
mode, // Too short
|
||||
config // Too vague
|
||||
};
|
||||
```
|
||||
|
||||
#### 3. **Validation and Constraints**
|
||||
Document valid values and constraints:
|
||||
|
||||
```markdown
|
||||
## Variable Constraints
|
||||
|
||||
**projectName**:
|
||||
- Type: string (alphanumeric, hyphens, underscores allowed)
|
||||
- Length: 1-100 characters
|
||||
- Required: yes
|
||||
- Pattern: `/^[a-zA-Z0-9_-]+$/`
|
||||
|
||||
**processingMode**:
|
||||
- Type: enum
|
||||
- Valid values: "quick" (< 5min), "standard" (5-15min), "detailed" (15+ min)
|
||||
- Default: "standard"
|
||||
- Required: no
|
||||
```
|
||||
|
||||
## MCP Server Configuration (Organization/Enterprise Only)
|
||||
|
||||
MCP servers extend agent capabilities with additional tools. Only supported for organization and enterprise-level agents.
|
||||
|
||||
### Configuration Format
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-custom-agent
|
||||
description: 'Agent with MCP integration'
|
||||
tools: ['read', 'edit', 'custom-mcp/tool-1']
|
||||
mcp-servers:
|
||||
custom-mcp:
|
||||
type: 'local'
|
||||
command: 'some-command'
|
||||
args: ['--arg1', '--arg2']
|
||||
tools: ["*"]
|
||||
env:
|
||||
ENV_VAR_NAME: ${{ secrets.API_KEY }}
|
||||
---
|
||||
```
|
||||
|
||||
### MCP Server Properties
|
||||
|
||||
- **type**: Server type (`'local'` or `'stdio'`)
|
||||
- **command**: Command to start the MCP server
|
||||
- **args**: Array of command arguments
|
||||
- **tools**: Tools to enable from this server (`["*"]` for all)
|
||||
- **env**: Environment variables (supports secrets)
|
||||
|
||||
### Environment Variables and Secrets
|
||||
|
||||
Secrets must be configured in repository settings under "copilot" environment.
|
||||
|
||||
**Supported syntax**:
|
||||
```yaml
|
||||
env:
|
||||
# Environment variable only
|
||||
VAR_NAME: COPILOT_MCP_ENV_VAR_VALUE
|
||||
|
||||
# Variable with header
|
||||
VAR_NAME: $COPILOT_MCP_ENV_VAR_VALUE
|
||||
VAR_NAME: ${COPILOT_MCP_ENV_VAR_VALUE}
|
||||
|
||||
# GitHub Actions-style (YAML only)
|
||||
VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
|
||||
VAR_NAME: ${{ var.COPILOT_MCP_ENV_VAR_VALUE }}
|
||||
```
|
||||
|
||||
## File Organization and Naming
|
||||
|
||||
### Repository-Level Agents
|
||||
- Location: `.github/agents/`
|
||||
- Scope: Available only in the specific repository
|
||||
- Access: Uses repository-configured MCP servers
|
||||
|
||||
### Organization/Enterprise-Level Agents
|
||||
- Location: `.github-private/agents/` (then move to `agents/` root)
|
||||
- Scope: Available across all repositories in org/enterprise
|
||||
- Access: Can configure dedicated MCP servers
|
||||
|
||||
### Naming Conventions
|
||||
- Use lowercase with hyphens: `test-specialist.agent.md`
|
||||
- Name should reflect agent purpose
|
||||
- Filename becomes default agent name (if `name` not specified)
|
||||
- Allowed characters: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`
|
||||
|
||||
## Agent Processing and Behavior
|
||||
|
||||
### Versioning
|
||||
- Based on Git commit SHAs for the agent file
|
||||
- Create branches/tags for different agent versions
|
||||
- Instantiated using latest version for repository/branch
|
||||
- PR interactions use same agent version for consistency
|
||||
|
||||
### Name Conflicts
|
||||
Priority (highest to lowest):
|
||||
1. Repository-level agent
|
||||
2. Organization-level agent
|
||||
3. Enterprise-level agent
|
||||
|
||||
Lower-level configurations override higher-level ones with the same name.
|
||||
|
||||
### Tool Processing
|
||||
- `tools` list filters available tools (built-in and MCP)
|
||||
- No tools specified = all tools enabled
|
||||
- Empty list (`[]`) = all tools disabled
|
||||
- Specific list = only those tools enabled
|
||||
- Unrecognized tool names are ignored (allows environment-specific tools)
|
||||
|
||||
### MCP Server Processing Order
|
||||
1. Out-of-the-box MCP servers (e.g., GitHub MCP)
|
||||
2. Custom agent MCP configuration (org/enterprise only)
|
||||
3. Repository-level MCP configurations
|
||||
|
||||
Each level can override settings from previous levels.
|
||||
|
||||
## Agent Creation Checklist
|
||||
|
||||
### Frontmatter
|
||||
- [ ] `description` field present and descriptive (50-150 chars)
|
||||
- [ ] `description` wrapped in single quotes
|
||||
- [ ] `name` specified (optional but recommended)
|
||||
- [ ] `tools` configured appropriately (or intentionally omitted)
|
||||
- [ ] `model` specified for optimal performance
|
||||
- [ ] `target` set if environment-specific
|
||||
- [ ] `infer` set to `false` if manual selection required
|
||||
|
||||
### Prompt Content
|
||||
- [ ] Clear agent identity and role defined
|
||||
- [ ] Core responsibilities listed explicitly
|
||||
- [ ] Approach and methodology explained
|
||||
- [ ] Guidelines and constraints specified
|
||||
- [ ] Output expectations documented
|
||||
- [ ] Examples provided where helpful
|
||||
- [ ] Instructions are specific and actionable
|
||||
- [ ] Scope and boundaries clearly defined
|
||||
- [ ] Total content under 30,000 characters
|
||||
|
||||
### File Structure
|
||||
- [ ] Filename follows lowercase-with-hyphens convention
|
||||
- [ ] File placed in correct directory (`.github/agents/` or `agents/`)
|
||||
- [ ] Filename uses only allowed characters
|
||||
- [ ] File extension is `.agent.md`
|
||||
|
||||
### Quality Assurance
|
||||
- [ ] Agent purpose is unique and not duplicative
|
||||
- [ ] Tools are minimal and necessary
|
||||
- [ ] Instructions are clear and unambiguous
|
||||
- [ ] Agent has been tested with representative tasks
|
||||
- [ ] Documentation references are current
|
||||
- [ ] Security considerations addressed (if applicable)
|
||||
|
||||
## Common Agent Patterns
|
||||
|
||||
### Testing Specialist
|
||||
**Purpose**: Focus on test coverage and quality
|
||||
**Tools**: All tools (for comprehensive test creation)
|
||||
**Approach**: Analyze, identify gaps, write tests, avoid production code changes
|
||||
|
||||
### Implementation Planner
|
||||
**Purpose**: Create detailed technical plans and specifications
|
||||
**Tools**: Limited to `['read', 'search', 'edit']`
|
||||
**Approach**: Analyze requirements, create documentation, avoid implementation
|
||||
|
||||
### Code Reviewer
|
||||
**Purpose**: Review code quality and provide feedback
|
||||
**Tools**: `['read', 'search']` only
|
||||
**Approach**: Analyze, suggest improvements, no direct modifications
|
||||
|
||||
### Refactoring Specialist
|
||||
**Purpose**: Improve code structure and maintainability
|
||||
**Tools**: `['read', 'search', 'edit']`
|
||||
**Approach**: Analyze patterns, propose refactorings, implement safely
|
||||
|
||||
### Security Auditor
|
||||
**Purpose**: Identify security issues and vulnerabilities
|
||||
**Tools**: `['read', 'search', 'web']`
|
||||
**Approach**: Scan code, check against OWASP, report findings
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### Frontmatter Errors
|
||||
- ❌ Missing `description` field
|
||||
- ❌ Description not wrapped in quotes
|
||||
- ❌ Invalid tool names without checking documentation
|
||||
- ❌ Incorrect YAML syntax (indentation, quotes)
|
||||
|
||||
### Tool Configuration Issues
|
||||
- ❌ Granting excessive tool access unnecessarily
|
||||
- ❌ Missing required tools for agent's purpose
|
||||
- ❌ Not using tool aliases consistently
|
||||
- ❌ Forgetting MCP server namespace (`server-name/tool`)
|
||||
|
||||
### Prompt Content Problems
|
||||
- ❌ Vague, ambiguous instructions
|
||||
- ❌ Conflicting or contradictory guidelines
|
||||
- ❌ Lack of clear scope definition
|
||||
- ❌ Missing output expectations
|
||||
- ❌ Overly verbose instructions (exceeding character limits)
|
||||
- ❌ No examples or context for complex tasks
|
||||
|
||||
### Organizational Issues
|
||||
- ❌ Filename doesn't reflect agent purpose
|
||||
- ❌ Wrong directory (confusing repo vs org level)
|
||||
- ❌ Using spaces or special characters in filename
|
||||
- ❌ Duplicate agent names causing conflicts
|
||||
|
||||
## Testing and Validation
|
||||
|
||||
### Manual Testing
|
||||
1. Create the agent file with proper frontmatter
|
||||
2. Reload VS Code or refresh GitHub.com
|
||||
3. Select the agent from the dropdown in Copilot Chat
|
||||
4. Test with representative user queries
|
||||
5. Verify tool access works as expected
|
||||
6. Confirm output meets expectations
|
||||
|
||||
### Integration Testing
|
||||
- Test agent with different file types in scope
|
||||
- Verify MCP server connectivity (if configured)
|
||||
- Check agent behavior with missing context
|
||||
- Test error handling and edge cases
|
||||
- Validate agent switching and handoffs
|
||||
|
||||
### Quality Checks
|
||||
- Run through agent creation checklist
|
||||
- Review against common mistakes list
|
||||
- Compare with example agents in repository
|
||||
- Get peer review for complex agents
|
||||
- Document any special configuration needs
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Official Documentation
|
||||
- [Creating Custom Agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents)
|
||||
- [Custom Agents Configuration](https://docs.github.com/en/copilot/reference/custom-agents-configuration)
|
||||
- [Custom Agents in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
|
||||
- [MCP Integration](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp)
|
||||
|
||||
### Community Resources
|
||||
- [Awesome Copilot Agents Collection](https://github.com/github/awesome-copilot/tree/main/agents)
|
||||
- [Customization Library Examples](https://docs.github.com/en/copilot/tutorials/customization-library/custom-agents)
|
||||
- [Your First Custom Agent Tutorial](https://docs.github.com/en/copilot/tutorials/customization-library/custom-agents/your-first-custom-agent)
|
||||
|
||||
### Related Files
|
||||
- [Prompt Files Guidelines](./prompt.instructions.md) - For creating prompt files
|
||||
- [Instructions Guidelines](./instructions.instructions.md) - For creating instruction files
|
||||
|
||||
## Version Compatibility Notes
|
||||
|
||||
### GitHub.com (Coding Agent)
|
||||
- ✅ Fully supports all standard frontmatter properties
|
||||
- ✅ Repository and org/enterprise level agents
|
||||
- ✅ MCP server configuration (org/enterprise)
|
||||
- ❌ Does not support `model`, `argument-hint`, `handoffs` properties
|
||||
|
||||
### VS Code / JetBrains / Eclipse / Xcode
|
||||
- ✅ Supports `model` property for AI model selection
|
||||
- ✅ Supports `argument-hint` and `handoffs` properties
|
||||
- ✅ User profile and workspace-level agents
|
||||
- ❌ Cannot configure MCP servers at repository level
|
||||
- ⚠️ Some properties may behave differently
|
||||
|
||||
When creating agents for multiple environments, focus on common properties and test in all target environments. Use `target` property to create environment-specific agents when necessary.
|
||||
136
instructions/kubernetes-manifests.instructions.md
Normal file
136
instructions/kubernetes-manifests.instructions.md
Normal file
@@ -0,0 +1,136 @@
|
||||
---
|
||||
applyTo: 'k8s/**/*.yaml,k8s/**/*.yml,manifests/**/*.yaml,manifests/**/*.yml,deploy/**/*.yaml,deploy/**/*.yml,charts/**/templates/**/*.yaml,charts/**/templates/**/*.yml'
|
||||
description: 'Best practices for Kubernetes YAML manifests including labeling conventions, security contexts, pod security, resource management, probes, and validation commands'
|
||||
---
|
||||
|
||||
# Kubernetes Manifests Instructions
|
||||
|
||||
## Your Mission
|
||||
|
||||
Create production-ready Kubernetes manifests that prioritize security, reliability, and operational excellence with consistent labeling, proper resource management, and comprehensive health checks.
|
||||
|
||||
## Labeling Conventions
|
||||
|
||||
**Required Labels** (Kubernetes recommended):
|
||||
- `app.kubernetes.io/name`: Application name
|
||||
- `app.kubernetes.io/instance`: Instance identifier
|
||||
- `app.kubernetes.io/version`: Version
|
||||
- `app.kubernetes.io/component`: Component role
|
||||
- `app.kubernetes.io/part-of`: Application group
|
||||
- `app.kubernetes.io/managed-by`: Management tool
|
||||
|
||||
**Additional Labels**:
|
||||
- `environment`: Environment name
|
||||
- `team`: Owning team
|
||||
- `cost-center`: For billing
|
||||
|
||||
**Useful Annotations**:
|
||||
- Documentation and ownership
|
||||
- Monitoring: `prometheus.io/scrape`, `prometheus.io/port`, `prometheus.io/path`
|
||||
- Change tracking: git commit, deployment date
|
||||
|
||||
## SecurityContext Defaults
|
||||
|
||||
**Pod-level**:
|
||||
- `runAsNonRoot: true`
|
||||
- `runAsUser` and `runAsGroup`: Specific IDs
|
||||
- `fsGroup`: File system group
|
||||
- `seccompProfile.type: RuntimeDefault`
|
||||
|
||||
**Container-level**:
|
||||
- `allowPrivilegeEscalation: false`
|
||||
- `readOnlyRootFilesystem: true` (with tmpfs mounts for writable dirs)
|
||||
- `capabilities.drop: [ALL]` (add only what's needed)
|
||||
|
||||
## Pod Security Standards
|
||||
|
||||
Use Pod Security Admission:
|
||||
- **Restricted** (recommended for production): Enforces security hardening
|
||||
- **Baseline**: Minimal security requirements
|
||||
- Apply at namespace level
|
||||
|
||||
## Resource Requests and Limits
|
||||
|
||||
**Always define**:
|
||||
- Requests: Guaranteed minimum (scheduling)
|
||||
- Limits: Maximum allowed (prevents exhaustion)
|
||||
|
||||
**QoS Classes**:
|
||||
- **Guaranteed**: requests == limits (best for critical apps)
|
||||
- **Burstable**: requests < limits (flexible resource use)
|
||||
- **BestEffort**: No resources defined (avoid in production)
|
||||
|
||||
## Health Probes
|
||||
|
||||
**Liveness**: Restart unhealthy containers
|
||||
**Readiness**: Control traffic routing
|
||||
**Startup**: Protect slow-starting applications
|
||||
|
||||
Configure appropriate delays, periods, timeouts, and thresholds for each.
|
||||
|
||||
## Rollout Strategies
|
||||
|
||||
**Deployment Strategy**:
|
||||
- `RollingUpdate` with `maxSurge` and `maxUnavailable`
|
||||
- Set `maxUnavailable: 0` for zero-downtime
|
||||
|
||||
**High Availability**:
|
||||
- Minimum 2-3 replicas
|
||||
- Pod Disruption Budget (PDB)
|
||||
- Anti-affinity rules (spread across nodes/zones)
|
||||
- Horizontal Pod Autoscaler (HPA) for variable load
|
||||
|
||||
## Validation Commands
|
||||
|
||||
**Pre-deployment**:
|
||||
- `kubectl apply --dry-run=client -f manifest.yaml`
|
||||
- `kubectl apply --dry-run=server -f manifest.yaml`
|
||||
- `kubeconform -strict manifest.yaml` (schema validation)
|
||||
- `helm template ./chart | kubeconform -strict` (for Helm)
|
||||
|
||||
**Policy Validation**:
|
||||
- OPA Conftest, Kyverno, or Datree
|
||||
|
||||
## Rollout & Rollback
|
||||
|
||||
**Deploy**:
|
||||
- `kubectl apply -f manifest.yaml`
|
||||
- `kubectl rollout status deployment/NAME`
|
||||
|
||||
**Rollback**:
|
||||
- `kubectl rollout undo deployment/NAME`
|
||||
- `kubectl rollout undo deployment/NAME --to-revision=N`
|
||||
- `kubectl rollout history deployment/NAME`
|
||||
|
||||
**Restart**:
|
||||
- `kubectl rollout restart deployment/NAME`
|
||||
|
||||
## Manifest Checklist
|
||||
|
||||
- [ ] Labels: Standard labels applied
|
||||
- [ ] Annotations: Documentation and monitoring
|
||||
- [ ] Security: runAsNonRoot, readOnlyRootFilesystem, dropped capabilities
|
||||
- [ ] Resources: Requests and limits defined
|
||||
- [ ] Probes: Liveness, readiness, startup configured
|
||||
- [ ] Images: Specific tags (never :latest)
|
||||
- [ ] Replicas: Minimum 2-3 for production
|
||||
- [ ] Strategy: RollingUpdate with appropriate surge/unavailable
|
||||
- [ ] PDB: Defined for production
|
||||
- [ ] Anti-affinity: Configured for HA
|
||||
- [ ] Graceful shutdown: terminationGracePeriodSeconds set
|
||||
- [ ] Validation: Dry-run and kubeconform passed
|
||||
- [ ] Secrets: In Secrets resource, not ConfigMaps
|
||||
- [ ] NetworkPolicy: Least-privilege access (if applicable)
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
1. Use standard labels and annotations
|
||||
2. Always run as non-root with dropped capabilities
|
||||
3. Define resource requests and limits
|
||||
4. Implement all three probe types
|
||||
5. Pin image tags to specific versions
|
||||
6. Configure anti-affinity for HA
|
||||
7. Set Pod Disruption Budgets
|
||||
8. Use rolling updates with zero unavailability
|
||||
9. Validate manifests before applying
|
||||
10. Enable read-only root filesystem when possible
|
||||
357
instructions/mcp-m365-copilot.instructions.md
Normal file
357
instructions/mcp-m365-copilot.instructions.md
Normal file
@@ -0,0 +1,357 @@
|
||||
---
|
||||
description: 'Best practices for building MCP-based declarative agents and API plugins for Microsoft 365 Copilot with Model Context Protocol integration'
|
||||
applyTo: '**/{*mcp*,*agent*,*plugin*,declarativeAgent.json,ai-plugin.json,mcp.json,manifest.json}'
|
||||
---
|
||||
|
||||
# MCP-based M365 Copilot Development Guidelines
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Model Context Protocol First
|
||||
- Leverage MCP servers for external system integration
|
||||
- Import tools from server endpoints, not manual definitions
|
||||
- Let MCP handle schema discovery and function generation
|
||||
- Use point-and-click tool selection in Agents Toolkit
|
||||
|
||||
### Declarative Over Imperative
|
||||
- Define agent behavior through configuration, not code
|
||||
- Use declarativeAgent.json for instructions and capabilities
|
||||
- Specify tools and actions in ai-plugin.json
|
||||
- Configure MCP servers in mcp.json
|
||||
|
||||
### Security and Governance
|
||||
- Always use OAuth 2.0 or SSO for authentication
|
||||
- Follow principle of least privilege for tool selection
|
||||
- Validate MCP server endpoints are secure
|
||||
- Review compliance requirements before deployment
|
||||
|
||||
### User-Centric Design
|
||||
- Create adaptive cards for rich visual responses
|
||||
- Provide clear conversation starters
|
||||
- Design for responsive experience across hubs
|
||||
- Test thoroughly before organizational deployment
|
||||
|
||||
## MCP Server Design
|
||||
|
||||
### Server Selection
|
||||
Choose MCP servers that:
|
||||
- Expose relevant tools for user tasks
|
||||
- Support secure authentication (OAuth 2.0, SSO)
|
||||
- Provide reliable uptime and performance
|
||||
- Follow MCP specification standards
|
||||
- Return well-structured response data
|
||||
|
||||
### Tool Import Strategy
|
||||
- Import only necessary tools (avoid over-scoping)
|
||||
- Group related tools from same server
|
||||
- Test each tool individually before combining
|
||||
- Consider token limits when selecting multiple tools
|
||||
|
||||
### Authentication Configuration
|
||||
**OAuth 2.0 Static Registration:**
|
||||
```json
|
||||
{
|
||||
"type": "OAuthPluginVault",
|
||||
"reference_id": "YOUR_AUTH_ID",
|
||||
"client_id": "github_client_id",
|
||||
"client_secret": "github_client_secret",
|
||||
"authorization_url": "https://github.com/login/oauth/authorize",
|
||||
"token_url": "https://github.com/login/oauth/access_token",
|
||||
"scope": "repo read:user"
|
||||
}
|
||||
```
|
||||
|
||||
**SSO (Microsoft Entra ID):**
|
||||
```json
|
||||
{
|
||||
"type": "OAuthPluginVault",
|
||||
"reference_id": "sso_auth",
|
||||
"authorization_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
|
||||
"token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
|
||||
"scope": "User.Read"
|
||||
}
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
project-root/
|
||||
├── appPackage/
|
||||
│ ├── manifest.json # Teams app manifest
|
||||
│ ├── declarativeAgent.json # Agent config (instructions, capabilities)
|
||||
│ ├── ai-plugin.json # API plugin definition
|
||||
│ ├── color.png # App icon color
|
||||
│ └── outline.png # App icon outline
|
||||
├── .vscode/
|
||||
│ └── mcp.json # MCP server configuration
|
||||
├── .env.local # Credentials (NEVER commit)
|
||||
└── teamsapp.yml # Teams Toolkit config
|
||||
```
|
||||
|
||||
### Critical Files
|
||||
|
||||
**declarativeAgent.json:**
|
||||
- Agent name and description
|
||||
- Instructions for behavior
|
||||
- Conversation starters
|
||||
- Capabilities (actions from plugins)
|
||||
|
||||
**ai-plugin.json:**
|
||||
- MCP server tools import
|
||||
- Response semantics (data_path, properties)
|
||||
- Static adaptive card templates
|
||||
- Function definitions (auto-generated)
|
||||
|
||||
**mcp.json:**
|
||||
- MCP server URL
|
||||
- Server metadata endpoint
|
||||
- Authentication reference
|
||||
|
||||
**.env.local:**
|
||||
- OAuth client credentials
|
||||
- API keys and secrets
|
||||
- Environment-specific config
|
||||
- **CRITICAL**: Add to .gitignore
|
||||
|
||||
## Response Semantics Best Practices
|
||||
|
||||
### Data Path Configuration
|
||||
Use JSONPath to extract relevant data:
|
||||
```json
|
||||
{
|
||||
"data_path": "$.items[*]",
|
||||
"properties": {
|
||||
"title": "$.name",
|
||||
"subtitle": "$.description",
|
||||
"url": "$.html_url"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Template Selection
|
||||
For dynamic templates:
|
||||
```json
|
||||
{
|
||||
"data_path": "$",
|
||||
"template_selector": "$.templateType",
|
||||
"properties": {
|
||||
"title": "$.title",
|
||||
"url": "$.url"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Static Templates
|
||||
Define in ai-plugin.json for consistent formatting:
|
||||
- Use when all responses follow same structure
|
||||
- Better performance than dynamic templates
|
||||
- Easier to maintain and version control
|
||||
|
||||
## Adaptive Card Guidelines
|
||||
|
||||
### Design Principles
|
||||
- **Single-column layout**: Stack elements vertically
|
||||
- **Flexible widths**: Use "stretch" or "auto", not fixed pixels
|
||||
- **Responsive design**: Test in Chat, Teams, Outlook
|
||||
- **Minimal complexity**: Keep cards simple and scannable
|
||||
|
||||
### Template Language Patterns
|
||||
**Conditionals:**
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${if(status == 'active', '✅ Active', '❌ Inactive')}"
|
||||
}
|
||||
```
|
||||
|
||||
**Data Binding:**
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "${title}",
|
||||
"weight": "bolder"
|
||||
}
|
||||
```
|
||||
|
||||
**Number Formatting:**
|
||||
```json
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Score: ${formatNumber(score, 0)}"
|
||||
}
|
||||
```
|
||||
|
||||
**Conditional Rendering:**
|
||||
```json
|
||||
{
|
||||
"type": "Container",
|
||||
"$when": "${count(items) > 0}",
|
||||
"items": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### Card Elements Usage
|
||||
- **TextBlock**: Titles, descriptions, metadata
|
||||
- **FactSet**: Key-value pairs (status, dates, IDs)
|
||||
- **Image**: Icons, thumbnails (use size: "small")
|
||||
- **Container**: Grouping related content
|
||||
- **ActionSet**: Buttons for follow-up actions
|
||||
|
||||
## Testing and Deployment
|
||||
|
||||
### Local Testing Workflow
|
||||
1. **Provision**: Teams Toolkit → Provision
|
||||
2. **Deploy**: Teams Toolkit → Deploy
|
||||
3. **Sideload**: App uploaded to Teams
|
||||
4. **Test**: Visit [m365.cloud.microsoft/chat](https://m365.cloud.microsoft/chat)
|
||||
5. **Iterate**: Fix issues and re-deploy
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
- [ ] All MCP server tools tested individually
|
||||
- [ ] Authentication flow works end-to-end
|
||||
- [ ] Adaptive cards render correctly across hubs
|
||||
- [ ] Response semantics extract expected data
|
||||
- [ ] Error handling provides clear messages
|
||||
- [ ] Conversation starters are relevant and clear
|
||||
- [ ] Agent instructions guide proper behavior
|
||||
- [ ] Compliance and security reviewed
|
||||
|
||||
### Deployment Options
|
||||
**Organization Deployment:**
|
||||
- IT admin deploys to all or selected users
|
||||
- Requires approval in Microsoft 365 admin center
|
||||
- Best for internal business agents
|
||||
|
||||
**Agent Store:**
|
||||
- Submit to Partner Center for validation
|
||||
- Public availability to all Copilot users
|
||||
- Requires rigorous security review
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Multi-Tool Agent
|
||||
Import tools from multiple MCP servers:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"url": "https://github-mcp.example.com"
|
||||
},
|
||||
"jira": {
|
||||
"url": "https://jira-mcp.example.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Search and Display
|
||||
1. Tool retrieves data from MCP server
|
||||
2. Response semantics extract relevant fields
|
||||
3. Adaptive card displays formatted results
|
||||
4. User can take action from card buttons
|
||||
|
||||
### Authenticated Actions
|
||||
1. User triggers tool requiring auth
|
||||
2. OAuth flow redirects for consent
|
||||
3. Access token stored in plugin vault
|
||||
4. Subsequent requests use stored token
|
||||
|
||||
## Error Handling
|
||||
|
||||
### MCP Server Errors
|
||||
- Provide clear error messages in agent responses
|
||||
- Fall back to alternative tools if available
|
||||
- Log errors for debugging
|
||||
- Guide user to retry or alternative approach
|
||||
|
||||
### Authentication Failures
|
||||
- Check OAuth credentials in .env.local
|
||||
- Verify scopes match required permissions
|
||||
- Test auth flow outside Copilot first
|
||||
- Ensure token refresh logic works
|
||||
|
||||
### Response Parsing Failures
|
||||
- Validate JSONPath expressions in response semantics
|
||||
- Handle missing or null data gracefully
|
||||
- Provide default values where appropriate
|
||||
- Test with varied API responses
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Tool Selection
|
||||
- Import only necessary tools (reduces token usage)
|
||||
- Avoid redundant tools from multiple servers
|
||||
- Test impact of each tool on response time
|
||||
|
||||
### Response Size
|
||||
- Use data_path to filter unnecessary data
|
||||
- Limit result sets where possible
|
||||
- Consider pagination for large datasets
|
||||
- Keep adaptive cards lightweight
|
||||
|
||||
### Caching Strategy
|
||||
- MCP servers should cache where appropriate
|
||||
- Agent responses may be cached by M365
|
||||
- Consider cache invalidation for time-sensitive data
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Credential Management
|
||||
- **NEVER** commit .env.local to source control
|
||||
- Use environment variables for all secrets
|
||||
- Rotate OAuth credentials regularly
|
||||
- Use separate credentials for dev/prod
|
||||
|
||||
### Data Privacy
|
||||
- Only request minimum necessary scopes
|
||||
- Avoid logging sensitive user data
|
||||
- Review data residency requirements
|
||||
- Follow compliance policies (GDPR, etc.)
|
||||
|
||||
### Server Validation
|
||||
- Verify MCP server is trusted and secure
|
||||
- Check HTTPS endpoints only
|
||||
- Review server's privacy policy
|
||||
- Test for injection vulnerabilities
|
||||
|
||||
## Governance and Compliance
|
||||
|
||||
### Admin Controls
|
||||
Agents can be:
|
||||
- **Blocked**: Prevented from use
|
||||
- **Deployed**: Assigned to specific users/groups
|
||||
- **Published**: Made available organization-wide
|
||||
|
||||
### Monitoring
|
||||
Track:
|
||||
- Agent usage and adoption
|
||||
- Error rates and performance
|
||||
- User feedback and satisfaction
|
||||
- Security incidents
|
||||
|
||||
### Audit Requirements
|
||||
Maintain:
|
||||
- Change history for agent configurations
|
||||
- Access logs for sensitive operations
|
||||
- Approval records for deployments
|
||||
- Compliance attestations
|
||||
|
||||
## Resources and References
|
||||
|
||||
### Official Documentation
|
||||
- [Build Declarative Agents with MCP (DevBlogs)](https://devblogs.microsoft.com/microsoft365dev/build-declarative-agents-for-microsoft-365-copilot-with-mcp/)
|
||||
- [Build MCP Plugins (Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/build-mcp-plugins)
|
||||
- [API Plugin Adaptive Cards (Learn)](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api-plugin-adaptive-cards)
|
||||
- [Manage Copilot Agents (Learn)](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-copilot-agents-integrated-apps)
|
||||
|
||||
### Tools and SDKs
|
||||
- Microsoft 365 Agents Toolkit (VS Code extension v6.3.x+)
|
||||
- Teams Toolkit for agent packaging
|
||||
- Adaptive Cards Designer
|
||||
- MCP specification documentation
|
||||
|
||||
### Partner Examples
|
||||
- monday.com: Task management integration
|
||||
- Canva: Design automation
|
||||
- Sitecore: Content management
|
||||
834
instructions/scala2.instructions.md
Normal file
834
instructions/scala2.instructions.md
Normal file
@@ -0,0 +1,834 @@
|
||||
---
|
||||
description: 'Scala 2.12/2.13 programming language coding conventions and best practices following Databricks style guide for functional programming, type safety, and production code quality.'
|
||||
applyTo: '**.scala, **/build.sbt, **/build.sc'
|
||||
---
|
||||
|
||||
# Scala Best Practices
|
||||
|
||||
Based on the [Databricks Scala Style Guide](https://github.com/databricks/scala-style-guide)
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Write Simple Code
|
||||
Code is written once but read and modified multiple times. Optimize for long-term readability and maintainability by writing simple code.
|
||||
|
||||
### Immutability by Default
|
||||
- Always prefer `val` over `var`
|
||||
- Use immutable collections from `scala.collection.immutable`
|
||||
- Case class constructor parameters should NOT be mutable
|
||||
- Use copy constructor to create modified instances
|
||||
|
||||
```scala
|
||||
// Good - Immutable case class
|
||||
case class Person(name: String, age: Int)
|
||||
|
||||
// Bad - Mutable case class
|
||||
case class Person(name: String, var age: Int)
|
||||
|
||||
// To change values, use copy constructor
|
||||
val p1 = Person("Peter", 15)
|
||||
val p2 = p1.copy(age = 16)
|
||||
|
||||
// Good - Immutable collections
|
||||
val users = List(User("Alice", 30), User("Bob", 25))
|
||||
val updatedUsers = users.map(u => u.copy(age = u.age + 1))
|
||||
```
|
||||
|
||||
### Pure Functions
|
||||
- Functions should be deterministic and side-effect free
|
||||
- Separate pure logic from effects
|
||||
- Use explicit types for methods with effects
|
||||
|
||||
```scala
|
||||
// Good - Pure function
|
||||
def calculateTotal(items: List[Item]): BigDecimal =
|
||||
items.map(_.price).sum
|
||||
|
||||
// Bad - Impure function with side effects
|
||||
def calculateTotal(items: List[Item]): BigDecimal = {
|
||||
println(s"Calculating total for ${items.size} items") // Side effect
|
||||
val total = items.map(_.price).sum
|
||||
saveToDatabase(total) // Side effect
|
||||
total
|
||||
}
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Classes and Objects
|
||||
|
||||
```scala
|
||||
// Classes, traits, objects - PascalCase
|
||||
class ClusterManager
|
||||
trait Expression
|
||||
object Configuration
|
||||
|
||||
// Packages - all lowercase ASCII
|
||||
package com.databricks.resourcemanager
|
||||
|
||||
// Methods/functions - camelCase
|
||||
def getUserById(id: Long): Option[User]
|
||||
def processData(input: String): Result
|
||||
|
||||
// Constants - uppercase in companion object
|
||||
object Configuration {
|
||||
val DEFAULT_PORT = 10000
|
||||
val MAX_RETRIES = 3
|
||||
val TIMEOUT_MS = 5000L
|
||||
}
|
||||
```
|
||||
|
||||
### Variables and Parameters
|
||||
|
||||
```scala
|
||||
// Variables - camelCase, self-evident names
|
||||
val serverPort = 1000
|
||||
val clientPort = 2000
|
||||
val maxRetryAttempts = 3
|
||||
|
||||
// One-character names OK in small, localized scope
|
||||
for (i <- 0 until 10) {
|
||||
// ...
|
||||
}
|
||||
|
||||
// Do NOT use "l" (Larry) - looks like "1", "|", "I"
|
||||
```
|
||||
|
||||
### Enumerations
|
||||
|
||||
```scala
|
||||
// Enumeration object - PascalCase
|
||||
// Values - UPPER_CASE with underscores
|
||||
private object ParseState extends Enumeration {
|
||||
type ParseState = Value
|
||||
|
||||
val PREFIX,
|
||||
TRIM_BEFORE_SIGN,
|
||||
SIGN,
|
||||
VALUE,
|
||||
UNIT_BEGIN,
|
||||
UNIT_END = Value
|
||||
}
|
||||
```
|
||||
|
||||
## Syntactic Style
|
||||
|
||||
### Line Length and Spacing
|
||||
|
||||
```scala
|
||||
// Limit lines to 100 characters
|
||||
// One space before and after operators
|
||||
def add(int1: Int, int2: Int): Int = int1 + int2
|
||||
|
||||
// One space after commas
|
||||
val list = List("a", "b", "c")
|
||||
|
||||
// One space after colons
|
||||
def getConf(key: String, defaultValue: String): String = {
|
||||
// code
|
||||
}
|
||||
|
||||
// Use 2-space indentation
|
||||
if (true) {
|
||||
println("Wow!")
|
||||
}
|
||||
|
||||
// 4-space indentation for long parameter lists
|
||||
def newAPIHadoopFile[K, V, F <: NewInputFormat[K, V]](
|
||||
path: String,
|
||||
fClass: Class[F],
|
||||
kClass: Class[K],
|
||||
vClass: Class[V],
|
||||
conf: Configuration = hadoopConfiguration): RDD[(K, V)] = {
|
||||
// method body
|
||||
}
|
||||
|
||||
// Class with long parameters
|
||||
class Foo(
|
||||
val param1: String, // 4 space indent
|
||||
val param2: String,
|
||||
val param3: Array[Byte])
|
||||
extends FooInterface // 2 space indent
|
||||
with Logging {
|
||||
|
||||
def firstMethod(): Unit = { ... } // blank line above
|
||||
}
|
||||
```
|
||||
|
||||
### Rule of 30
|
||||
|
||||
- A method should contain less than 30 lines of code
|
||||
- A class should contain less than 30 methods
|
||||
|
||||
### Curly Braces
|
||||
|
||||
```scala
|
||||
// Always use curly braces for multi-line blocks
|
||||
if (true) {
|
||||
println("Wow!")
|
||||
}
|
||||
|
||||
// Exception: one-line ternary (side-effect free)
|
||||
val result = if (condition) value1 else value2
|
||||
|
||||
// Always use braces for try-catch
|
||||
try {
|
||||
foo()
|
||||
} catch {
|
||||
case e: Exception => handle(e)
|
||||
}
|
||||
```
|
||||
|
||||
### Long Literals
|
||||
|
||||
```scala
|
||||
// Use uppercase L for long literals
|
||||
val longValue = 5432L // Do this
|
||||
val badValue = 5432l // Don't do this - hard to see
|
||||
```
|
||||
|
||||
### Parentheses
|
||||
|
||||
```scala
|
||||
// Methods with side-effects - use parentheses
|
||||
class Job {
|
||||
def killJob(): Unit = { ... } // Correct - changes state
|
||||
def getStatus: JobStatus = { ... } // Correct - no side-effect
|
||||
}
|
||||
|
||||
// Callsite should match declaration
|
||||
new Job().killJob() // Correct
|
||||
new Job().getStatus // Correct
|
||||
```
|
||||
|
||||
### Imports
|
||||
|
||||
```scala
|
||||
// Avoid wildcard imports unless importing 6+ entities
|
||||
import scala.collection.mutable.{Map, HashMap, ArrayBuffer}
|
||||
|
||||
// OK to use wildcard for implicits or 6+ items
|
||||
import scala.collection.JavaConverters._
|
||||
import java.util.{Map, HashMap, List, ArrayList, Set, HashSet}
|
||||
|
||||
// Always use absolute paths
|
||||
import scala.util.Random // Good
|
||||
// import util.Random // Don't use relative
|
||||
|
||||
// Import order (with blank lines):
|
||||
import java.io.File
|
||||
import javax.servlet.http.HttpServlet
|
||||
|
||||
import scala.collection.mutable.HashMap
|
||||
import scala.util.Random
|
||||
|
||||
import org.apache.spark.SparkContext
|
||||
import org.apache.spark.rdd.RDD
|
||||
|
||||
import com.databricks.MyClass
|
||||
```
|
||||
|
||||
### Pattern Matching
|
||||
|
||||
```scala
|
||||
// Put match on same line if method is entirely pattern match
|
||||
def test(msg: Message): Unit = msg match {
|
||||
case TextMessage(text) => handleText(text)
|
||||
case ImageMessage(url) => handleImage(url)
|
||||
}
|
||||
|
||||
// Single case closures - same line
|
||||
list.zipWithIndex.map { case (elem, i) =>
|
||||
// process
|
||||
}
|
||||
|
||||
// Multiple cases - indent and wrap
|
||||
list.map {
|
||||
case a: Foo => processFoo(a)
|
||||
case b: Bar => processBar(b)
|
||||
case _ => handleDefault()
|
||||
}
|
||||
|
||||
// Match on type only - don't expand all args
|
||||
case class Pokemon(name: String, weight: Int, hp: Int, attack: Int, defense: Int)
|
||||
|
||||
// Bad - brittle when fields change
|
||||
targets.foreach {
|
||||
case Pokemon(_, _, hp, _, defense) =>
|
||||
// error prone
|
||||
}
|
||||
|
||||
// Good - match on type
|
||||
targets.foreach {
|
||||
case p: Pokemon =>
|
||||
val loss = math.min(0, myAttack - p.defense)
|
||||
p.copy(hp = p.hp - loss)
|
||||
}
|
||||
```
|
||||
|
||||
### Anonymous Functions
|
||||
|
||||
```scala
|
||||
// Avoid excessive parentheses
|
||||
// Correct
|
||||
list.map { item =>
|
||||
transform(item)
|
||||
}
|
||||
|
||||
// Correct
|
||||
list.map(item => transform(item))
|
||||
|
||||
// Wrong - unnecessary braces
|
||||
list.map(item => {
|
||||
transform(item)
|
||||
})
|
||||
|
||||
// Wrong - excessive nesting
|
||||
list.map({ item => ... })
|
||||
```
|
||||
|
||||
### Infix Methods
|
||||
|
||||
```scala
|
||||
// Avoid infix for non-symbolic methods
|
||||
list.map(func) // Correct
|
||||
list map func // Wrong
|
||||
|
||||
// OK for operators
|
||||
arrayBuffer += elem
|
||||
```
|
||||
|
||||
## Language Features
|
||||
|
||||
### Avoid apply() on Classes
|
||||
|
||||
```scala
|
||||
// Avoid apply on classes - hard to trace
|
||||
class TreeNode {
|
||||
def apply(name: String): TreeNode = { ... } // Don't do this
|
||||
}
|
||||
|
||||
// OK on companion objects as factory
|
||||
object TreeNode {
|
||||
def apply(name: String): TreeNode = new TreeNode(name) // OK
|
||||
}
|
||||
```
|
||||
|
||||
### override Modifier
|
||||
|
||||
```scala
|
||||
// Always use override - even for abstract methods
|
||||
trait Parent {
|
||||
def hello(data: Map[String, String]): Unit
|
||||
}
|
||||
|
||||
class Child extends Parent {
|
||||
// Without override, this might not actually override!
|
||||
override def hello(data: Map[String, String]): Unit = {
|
||||
println(data)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Avoid Destructuring in Constructors
|
||||
|
||||
```scala
|
||||
// Don't use destructuring binds in constructors
|
||||
class MyClass {
|
||||
// Bad - creates non-transient Tuple2
|
||||
@transient private val (a, b) = someFuncThatReturnsTuple2()
|
||||
|
||||
// Good
|
||||
@transient private val tuple = someFuncThatReturnsTuple2()
|
||||
@transient private val a = tuple._1
|
||||
@transient private val b = tuple._2
|
||||
}
|
||||
```
|
||||
|
||||
### Avoid Call-by-Name
|
||||
|
||||
```scala
|
||||
// Avoid call-by-name parameters
|
||||
// Bad - caller can't tell if executed once or many times
|
||||
def print(value: => Int): Unit = {
|
||||
println(value)
|
||||
println(value + 1)
|
||||
}
|
||||
|
||||
// Good - explicit function type
|
||||
def print(value: () => Int): Unit = {
|
||||
println(value())
|
||||
println(value() + 1)
|
||||
}
|
||||
```
|
||||
|
||||
### Avoid Multiple Parameter Lists
|
||||
|
||||
```scala
|
||||
// Avoid multiple parameter lists (except for implicits)
|
||||
// Bad
|
||||
case class Person(name: String, age: Int)(secret: String)
|
||||
|
||||
// Good
|
||||
case class Person(name: String, age: Int, secret: String)
|
||||
|
||||
// Exception: separate list for implicits (but avoid implicits!)
|
||||
def foo(x: Int)(implicit ec: ExecutionContext): Future[Int]
|
||||
```
|
||||
|
||||
### Symbolic Methods
|
||||
|
||||
```scala
|
||||
// Only use for arithmetic operators
|
||||
class Vector {
|
||||
def +(other: Vector): Vector = { ... } // OK
|
||||
def -(other: Vector): Vector = { ... } // OK
|
||||
}
|
||||
|
||||
// Don't use for other methods
|
||||
// Bad
|
||||
channel ! msg
|
||||
stream1 >>= stream2
|
||||
|
||||
// Good
|
||||
channel.send(msg)
|
||||
stream1.join(stream2)
|
||||
```
|
||||
|
||||
### Type Inference
|
||||
|
||||
```scala
|
||||
// Always type public methods
|
||||
def getUserById(id: Long): Option[User] = { ... }
|
||||
|
||||
// Always type implicit methods
|
||||
implicit def stringToInt(s: String): Int = s.toInt
|
||||
|
||||
// Type variables when not obvious (3 second rule)
|
||||
val user: User = complexComputation()
|
||||
|
||||
// OK to omit when obvious
|
||||
val count = 5
|
||||
val name = "Alice"
|
||||
```
|
||||
|
||||
### Return Statements
|
||||
|
||||
```scala
|
||||
// Avoid return in closures - uses exceptions under the hood
|
||||
def receive(rpc: WebSocketRPC): Option[Response] = {
|
||||
tableFut.onComplete { table =>
|
||||
if (table.isFailure) {
|
||||
return None // Don't do this - wrong thread!
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Use return as guard to simplify control flow
|
||||
def doSomething(obj: Any): Any = {
|
||||
if (obj eq null) {
|
||||
return null
|
||||
}
|
||||
// do something
|
||||
}
|
||||
|
||||
// Use return to break loops early
|
||||
while (true) {
|
||||
if (cond) {
|
||||
return
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Recursion and Tail Recursion
|
||||
|
||||
```scala
|
||||
// Avoid recursion unless naturally recursive (trees, graphs)
|
||||
// Use @tailrec for tail-recursive methods
|
||||
@scala.annotation.tailrec
|
||||
def max0(data: Array[Int], pos: Int, max: Int): Int = {
|
||||
if (pos == data.length) {
|
||||
max
|
||||
} else {
|
||||
max0(data, pos + 1, if (data(pos) > max) data(pos) else max)
|
||||
}
|
||||
}
|
||||
|
||||
// Prefer explicit loops for clarity
|
||||
def max(data: Array[Int]): Int = {
|
||||
var max = Int.MinValue
|
||||
for (v <- data) {
|
||||
if (v > max) {
|
||||
max = v
|
||||
}
|
||||
}
|
||||
max
|
||||
}
|
||||
```
|
||||
|
||||
### Implicits
|
||||
|
||||
```scala
|
||||
// Avoid implicits unless:
|
||||
// 1. Building a DSL
|
||||
// 2. Implicit type parameters (ClassTag, TypeTag)
|
||||
// 3. Private type conversions within your class
|
||||
|
||||
// If you must use them, don't overload
|
||||
object ImplicitHolder {
|
||||
// Bad - can't selectively import
|
||||
def toRdd(seq: Seq[Int]): RDD[Int] = { ... }
|
||||
def toRdd(seq: Seq[Long]): RDD[Long] = { ... }
|
||||
}
|
||||
|
||||
// Good - distinct names
|
||||
object ImplicitHolder {
|
||||
def intSeqToRdd(seq: Seq[Int]): RDD[Int] = { ... }
|
||||
def longSeqToRdd(seq: Seq[Long]): RDD[Long] = { ... }
|
||||
}
|
||||
```
|
||||
|
||||
## Type Safety
|
||||
|
||||
### Algebraic Data Types
|
||||
|
||||
```scala
|
||||
// Sum types - sealed traits with case classes
|
||||
sealed trait PaymentMethod
|
||||
case class CreditCard(number: String, cvv: String) extends PaymentMethod
|
||||
case class PayPal(email: String) extends PaymentMethod
|
||||
case class BankTransfer(account: String, routing: String) extends PaymentMethod
|
||||
|
||||
def processPayment(payment: PaymentMethod): Either[Error, Receipt] = payment match {
|
||||
case CreditCard(number, cvv) => chargeCreditCard(number, cvv)
|
||||
case PayPal(email) => chargePayPal(email)
|
||||
case BankTransfer(account, routing) => chargeBankAccount(account, routing)
|
||||
}
|
||||
|
||||
// Product types - case classes
|
||||
case class User(id: Long, name: String, email: String, age: Int)
|
||||
case class Order(id: Long, userId: Long, items: List[Item], total: BigDecimal)
|
||||
```
|
||||
|
||||
### Option over null
|
||||
|
||||
```scala
|
||||
// Use Option instead of null
|
||||
def findUserById(id: Long): Option[User] = {
|
||||
database.query(id)
|
||||
}
|
||||
|
||||
// Use Option() to guard against nulls
|
||||
def myMethod1(input: String): Option[String] = Option(transform(input))
|
||||
|
||||
// Don't use Some() - it won't protect against null
|
||||
def myMethod2(input: String): Option[String] = Some(transform(input)) // Bad
|
||||
|
||||
// Pattern matching on Option
|
||||
def processUser(id: Long): String = findUserById(id) match {
|
||||
case Some(user) => s"Found: ${user.name}"
|
||||
case None => "User not found"
|
||||
}
|
||||
|
||||
// Don't call get() unless absolutely sure
|
||||
val user = findUserById(123).get // Dangerous!
|
||||
|
||||
// Use getOrElse, map, flatMap, fold instead
|
||||
val name = findUserById(123).map(_.name).getOrElse("Unknown")
|
||||
```
|
||||
|
||||
### Error Handling with Either
|
||||
|
||||
```scala
|
||||
sealed trait ValidationError
|
||||
case class InvalidEmail(email: String) extends ValidationError
|
||||
case class InvalidAge(age: Int) extends ValidationError
|
||||
case class MissingField(field: String) extends ValidationError
|
||||
|
||||
def validateUser(data: Map[String, String]): Either[ValidationError, User] = {
|
||||
for {
|
||||
name <- data.get("name").toRight(MissingField("name"))
|
||||
email <- data.get("email").toRight(MissingField("email"))
|
||||
validEmail <- validateEmail(email)
|
||||
ageStr <- data.get("age").toRight(MissingField("age"))
|
||||
age <- ageStr.toIntOption.toRight(InvalidAge(-1))
|
||||
} yield User(name, validEmail, age)
|
||||
}
|
||||
```
|
||||
|
||||
### Try vs Exceptions
|
||||
|
||||
```scala
|
||||
// Don't return Try from APIs
|
||||
// Bad
|
||||
def getUser(id: Long): Try[User]
|
||||
|
||||
// Good - explicit throws
|
||||
@throws(classOf[DatabaseConnectionException])
|
||||
def getUser(id: Long): Option[User]
|
||||
|
||||
// Use NonFatal for catching exceptions
|
||||
import scala.util.control.NonFatal
|
||||
|
||||
try {
|
||||
dangerousOperation()
|
||||
} catch {
|
||||
case NonFatal(e) =>
|
||||
logger.error("Operation failed", e)
|
||||
case e: InterruptedException =>
|
||||
// handle interruption
|
||||
}
|
||||
```
|
||||
|
||||
## Collections
|
||||
|
||||
### Prefer Immutable Collections
|
||||
|
||||
```scala
|
||||
import scala.collection.immutable._
|
||||
|
||||
// Good
|
||||
val numbers = List(1, 2, 3, 4, 5)
|
||||
val doubled = numbers.map(_ * 2)
|
||||
val evens = numbers.filter(_ % 2 == 0)
|
||||
|
||||
val userMap = Map(
|
||||
1L -> "Alice",
|
||||
2L -> "Bob"
|
||||
)
|
||||
val updated = userMap + (3L -> "Charlie")
|
||||
|
||||
// Use Stream (Scala 2.12) or LazyList (Scala 2.13) for lazy sequences
|
||||
val fibonacci: LazyList[BigInt] =
|
||||
BigInt(0) #:: BigInt(1) #:: fibonacci.zip(fibonacci.tail).map { case (a, b) => a + b }
|
||||
|
||||
val first10 = fibonacci.take(10).toList
|
||||
```
|
||||
|
||||
### Monadic Chaining
|
||||
|
||||
```scala
|
||||
// Avoid chaining more than 3 operations
|
||||
// Break after flatMap
|
||||
// Don't chain with if-else blocks
|
||||
|
||||
// Bad - too complex
|
||||
database.get(name).flatMap { elem =>
|
||||
elem.data.get("address").flatMap(Option.apply)
|
||||
}
|
||||
|
||||
// Good - more readable
|
||||
def getAddress(name: String): Option[String] = {
|
||||
if (!database.contains(name)) {
|
||||
return None
|
||||
}
|
||||
|
||||
database(name).data.get("address") match {
|
||||
case Some(null) => None
|
||||
case Some(addr) => Option(addr)
|
||||
case None => None
|
||||
}
|
||||
}
|
||||
|
||||
// Don't chain with if-else
|
||||
// Bad
|
||||
if (condition) {
|
||||
Seq(1, 2, 3)
|
||||
} else {
|
||||
Seq(1, 2, 3)
|
||||
}.map(_ + 1)
|
||||
|
||||
// Good
|
||||
val seq = if (condition) Seq(1, 2, 3) else Seq(4, 5, 6)
|
||||
seq.map(_ + 1)
|
||||
```
|
||||
|
||||
## Performance
|
||||
|
||||
### Use while Loops
|
||||
|
||||
```scala
|
||||
// For performance-critical code, use while instead of for/map
|
||||
val arr = Array.fill(1000)(Random.nextInt())
|
||||
|
||||
// Slow
|
||||
val newArr = arr.zipWithIndex.map { case (elem, i) =>
|
||||
if (i % 2 == 0) 0 else elem
|
||||
}
|
||||
|
||||
// Fast
|
||||
val newArr = new Array[Int](arr.length)
|
||||
var i = 0
|
||||
while (i < arr.length) {
|
||||
newArr(i) = if (i % 2 == 0) 0 else arr(i)
|
||||
i += 1
|
||||
}
|
||||
```
|
||||
|
||||
### Option vs null
|
||||
|
||||
```scala
|
||||
// For performance-critical code, prefer null over Option
|
||||
class Foo {
|
||||
@javax.annotation.Nullable
|
||||
private[this] var nullableField: Bar = _
|
||||
}
|
||||
```
|
||||
|
||||
### Use private[this]
|
||||
|
||||
```scala
|
||||
// private[this] generates fields, not accessor methods
|
||||
class MyClass {
|
||||
private val field1 = ... // Might use accessor
|
||||
private[this] val field2 = ... // Direct field access
|
||||
|
||||
def perfSensitiveMethod(): Unit = {
|
||||
var i = 0
|
||||
while (i < 1000000) {
|
||||
field2 // Guaranteed field access
|
||||
i += 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Java Collections
|
||||
|
||||
```scala
|
||||
// For performance, prefer Java collections
|
||||
import java.util.{ArrayList, HashMap}
|
||||
|
||||
val list = new ArrayList[String]()
|
||||
val map = new HashMap[String, Int]()
|
||||
```
|
||||
|
||||
## Concurrency
|
||||
|
||||
### Prefer ConcurrentHashMap
|
||||
|
||||
```scala
|
||||
// Use java.util.concurrent.ConcurrentHashMap
|
||||
private[this] val map = new java.util.concurrent.ConcurrentHashMap[String, String]
|
||||
|
||||
// Or synchronized map for low contention
|
||||
private[this] val map = java.util.Collections.synchronizedMap(
|
||||
new java.util.HashMap[String, String]
|
||||
)
|
||||
```
|
||||
|
||||
### Explicit Synchronization
|
||||
|
||||
```scala
|
||||
class Manager {
|
||||
private[this] var count = 0
|
||||
private[this] val map = new java.util.HashMap[String, String]
|
||||
|
||||
def update(key: String, value: String): Unit = synchronized {
|
||||
map.put(key, value)
|
||||
count += 1
|
||||
}
|
||||
|
||||
def getCount: Int = synchronized { count }
|
||||
}
|
||||
```
|
||||
|
||||
### Atomic Variables
|
||||
|
||||
```scala
|
||||
import java.util.concurrent.atomic._
|
||||
|
||||
// Prefer Atomic over @volatile
|
||||
val initialized = new AtomicBoolean(false)
|
||||
|
||||
// Clearly express only-once execution
|
||||
if (!initialized.getAndSet(true)) {
|
||||
initialize()
|
||||
}
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Intercept Specific Exceptions
|
||||
|
||||
```scala
|
||||
import org.scalatest._
|
||||
|
||||
// Bad - too broad
|
||||
intercept[Exception] {
|
||||
thingThatThrows()
|
||||
}
|
||||
|
||||
// Good - specific type
|
||||
intercept[IllegalArgumentException] {
|
||||
thingThatThrows()
|
||||
}
|
||||
```
|
||||
|
||||
## SBT Configuration
|
||||
|
||||
```scala
|
||||
// build.sbt
|
||||
ThisBuild / version := "0.1.0-SNAPSHOT"
|
||||
ThisBuild / scalaVersion := "2.13.12"
|
||||
ThisBuild / organization := "com.example"
|
||||
|
||||
lazy val root = (project in file("."))
|
||||
.settings(
|
||||
name := "my-application",
|
||||
|
||||
libraryDependencies ++= Seq(
|
||||
"org.typelevel" %% "cats-core" % "2.10.0",
|
||||
"org.typelevel" %% "cats-effect" % "3.5.2",
|
||||
|
||||
// Testing
|
||||
"org.scalatest" %% "scalatest" % "3.2.17" % Test,
|
||||
"org.scalatestplus" %% "scalacheck-1-17" % "3.2.17.0" % Test
|
||||
),
|
||||
|
||||
scalacOptions ++= Seq(
|
||||
"-encoding", "UTF-8",
|
||||
"-feature",
|
||||
"-unchecked",
|
||||
"-deprecation",
|
||||
"-Xfatal-warnings"
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
## Miscellaneous
|
||||
|
||||
### Use nanoTime
|
||||
|
||||
```scala
|
||||
// Use nanoTime for durations, not currentTimeMillis
|
||||
val start = System.nanoTime()
|
||||
doWork()
|
||||
val elapsed = System.nanoTime() - start
|
||||
|
||||
import java.util.concurrent.TimeUnit
|
||||
val elapsedMs = TimeUnit.NANOSECONDS.toMillis(elapsed)
|
||||
```
|
||||
|
||||
### URI over URL
|
||||
|
||||
```scala
|
||||
// Use URI instead of URL (URL.equals does DNS lookup!)
|
||||
val uri = new java.net.URI("http://example.com")
|
||||
// Not: val url = new java.net.URL("http://example.com")
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
1. **Write simple code** - Optimize for readability and maintainability
|
||||
2. **Use immutable data** - val, immutable collections, case classes
|
||||
3. **Avoid language features** - Limit implicits, avoid symbolic methods
|
||||
4. **Type public APIs** - Explicit types for methods and fields
|
||||
5. **Prefer explicit over implicit** - Clear is better than concise
|
||||
6. **Use standard libraries** - Don't reinvent the wheel
|
||||
7. **Follow naming conventions** - PascalCase, camelCase, UPPER_CASE
|
||||
8. **Keep methods small** - Rule of 30
|
||||
9. **Handle errors explicitly** - Option, Either, exceptions with @throws
|
||||
10. **Profile before optimizing** - Measure, don't guess
|
||||
|
||||
For complete details, see the [Databricks Scala Style Guide](https://github.com/databricks/scala-style-guide).
|
||||
440
instructions/typespec-m365-copilot.instructions.md
Normal file
440
instructions/typespec-m365-copilot.instructions.md
Normal file
@@ -0,0 +1,440 @@
|
||||
---
|
||||
description: 'Guidelines and best practices for building TypeSpec-based declarative agents and API plugins for Microsoft 365 Copilot'
|
||||
applyTo: '**/*.tsp'
|
||||
---
|
||||
|
||||
# TypeSpec for Microsoft 365 Copilot Development Guidelines
|
||||
|
||||
## Core Principles
|
||||
|
||||
When working with TypeSpec for Microsoft 365 Copilot:
|
||||
|
||||
1. **Type Safety First**: Leverage TypeSpec's strong typing for all models and operations
|
||||
2. **Declarative Approach**: Use decorators to describe intent, not implementation
|
||||
3. **Scoped Capabilities**: Always scope capabilities to specific resources when possible
|
||||
4. **Clear Instructions**: Write explicit, detailed agent instructions
|
||||
5. **User-Centric**: Design for the end-user experience in Microsoft 365 Copilot
|
||||
|
||||
## File Organization
|
||||
|
||||
### Standard Structure
|
||||
```
|
||||
project/
|
||||
├── appPackage/
|
||||
│ ├── cards/ # Adaptive Card templates
|
||||
│ │ └── *.json
|
||||
│ ├── .generated/ # Generated manifests (auto-generated)
|
||||
│ └── manifest.json # Teams app manifest
|
||||
├── src/
|
||||
│ ├── main.tsp # Agent definition
|
||||
│ └── actions.tsp # API operations (for plugins)
|
||||
├── m365agents.yml # Agents Toolkit configuration
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Import Statements
|
||||
Always include required imports at the top of TypeSpec files:
|
||||
|
||||
```typescript
|
||||
import "@typespec/http";
|
||||
import "@typespec/openapi3";
|
||||
import "@microsoft/typespec-m365-copilot";
|
||||
|
||||
using TypeSpec.Http;
|
||||
using TypeSpec.M365.Copilot.Agents; // For agents
|
||||
using TypeSpec.M365.Copilot.Actions; // For API plugins
|
||||
```
|
||||
|
||||
## Agent Development Best Practices
|
||||
|
||||
### Agent Declaration
|
||||
```typescript
|
||||
@agent({
|
||||
name: "Role-Based Name", // e.g., "Customer Support Assistant"
|
||||
description: "Clear, concise description under 1,000 characters"
|
||||
})
|
||||
```
|
||||
|
||||
- Use role-based names that describe what the agent does
|
||||
- Make descriptions informative but concise
|
||||
- Avoid generic names like "Helper" or "Bot"
|
||||
|
||||
### Instructions
|
||||
```typescript
|
||||
@instructions("""
|
||||
You are a [specific role] specialized in [domain].
|
||||
|
||||
Your responsibilities include:
|
||||
- [Key responsibility 1]
|
||||
- [Key responsibility 2]
|
||||
|
||||
When helping users:
|
||||
- [Behavioral guideline 1]
|
||||
- [Behavioral guideline 2]
|
||||
|
||||
You should NOT:
|
||||
- [Constraint 1]
|
||||
- [Constraint 2]
|
||||
""")
|
||||
```
|
||||
|
||||
- Write in second person ("You are...")
|
||||
- Be specific about the agent's role and expertise
|
||||
- Define both what to do AND what not to do
|
||||
- Keep under 8,000 characters
|
||||
- Use clear, structured formatting
|
||||
|
||||
### Conversation Starters
|
||||
```typescript
|
||||
@conversationStarter(#{
|
||||
title: "Action-Oriented Title", // e.g., "Check Status"
|
||||
text: "Specific example query" // e.g., "What's the status of my ticket?"
|
||||
})
|
||||
```
|
||||
|
||||
- Provide 2-4 diverse starters
|
||||
- Make each showcase a different capability
|
||||
- Use action-oriented titles
|
||||
- Write realistic example queries
|
||||
|
||||
### Capabilities - Knowledge Sources
|
||||
|
||||
**Web Search** - Scope to specific sites when possible:
|
||||
```typescript
|
||||
op webSearch is AgentCapabilities.WebSearch<Sites = [
|
||||
{ url: "https://learn.microsoft.com" },
|
||||
{ url: "https://docs.microsoft.com" }
|
||||
]>;
|
||||
```
|
||||
|
||||
**OneDrive and SharePoint** - Use URLs or IDs:
|
||||
```typescript
|
||||
op oneDriveAndSharePoint is AgentCapabilities.OneDriveAndSharePoint<
|
||||
ItemsByUrl = [
|
||||
{ url: "https://contoso.sharepoint.com/sites/Engineering" }
|
||||
]
|
||||
>;
|
||||
```
|
||||
|
||||
**Teams Messages** - Specify channels/chats:
|
||||
```typescript
|
||||
op teamsMessages is AgentCapabilities.TeamsMessages<Urls = [
|
||||
{ url: "https://teams.microsoft.com/l/channel/..." }
|
||||
]>;
|
||||
```
|
||||
|
||||
**Email** - Scope to specific folders:
|
||||
```typescript
|
||||
op email is AgentCapabilities.Email<
|
||||
Folders = [
|
||||
{ folderId: "Inbox" },
|
||||
{ folderId: "SentItems" }
|
||||
],
|
||||
SharedMailbox = "support@contoso.com" // Optional
|
||||
>;
|
||||
```
|
||||
|
||||
**People** - No scoping needed:
|
||||
```typescript
|
||||
op people is AgentCapabilities.People;
|
||||
```
|
||||
|
||||
**Copilot Connectors** - Specify connection IDs:
|
||||
```typescript
|
||||
op copilotConnectors is AgentCapabilities.GraphConnectors<
|
||||
Connections = [
|
||||
{ connectionId: "your-connector-id" }
|
||||
]
|
||||
>;
|
||||
```
|
||||
|
||||
**Dataverse** - Scope to specific tables:
|
||||
```typescript
|
||||
op dataverse is AgentCapabilities.Dataverse<
|
||||
KnowledgeSources = [
|
||||
{
|
||||
hostName: "contoso.crm.dynamics.com";
|
||||
tables: [
|
||||
{ tableName: "account" },
|
||||
{ tableName: "contact" }
|
||||
];
|
||||
}
|
||||
]
|
||||
>;
|
||||
```
|
||||
|
||||
### Capabilities - Productivity Tools
|
||||
|
||||
```typescript
|
||||
// Python code execution
|
||||
op codeInterpreter is AgentCapabilities.CodeInterpreter;
|
||||
|
||||
// Image generation
|
||||
op graphicArt is AgentCapabilities.GraphicArt;
|
||||
|
||||
// Meeting content access
|
||||
op meetings is AgentCapabilities.Meetings;
|
||||
|
||||
// Specialized AI models
|
||||
op scenarioModels is AgentCapabilities.ScenarioModels<
|
||||
ModelsById = [
|
||||
{ id: "model-id" }
|
||||
]
|
||||
>;
|
||||
```
|
||||
|
||||
## API Plugin Development Best Practices
|
||||
|
||||
### Service Definition
|
||||
```typescript
|
||||
@service
|
||||
@actions(#{
|
||||
nameForHuman: "User-Friendly API Name",
|
||||
descriptionForHuman: "What users will understand",
|
||||
descriptionForModel: "What the model needs to know",
|
||||
contactEmail: "support@company.com",
|
||||
privacyPolicyUrl: "https://company.com/privacy",
|
||||
legalInfoUrl: "https://company.com/terms"
|
||||
})
|
||||
@server("https://api.example.com", "API Name")
|
||||
@useAuth([AuthType]) // If authentication needed
|
||||
namespace APINamespace {
|
||||
// Operations here
|
||||
}
|
||||
```
|
||||
|
||||
### Operation Definition
|
||||
```typescript
|
||||
@route("/resource/{id}")
|
||||
@get
|
||||
@action
|
||||
@card(#{
|
||||
dataPath: "$.items",
|
||||
title: "$.title",
|
||||
file: "cards/card.json"
|
||||
})
|
||||
@capabilities(#{
|
||||
confirmation: #{
|
||||
type: "AdaptiveCard",
|
||||
title: "Confirm Action",
|
||||
body: "Confirm with {{ function.parameters.param }}"
|
||||
}
|
||||
})
|
||||
@reasoning("Consider X when Y")
|
||||
@responding("Present results as Z")
|
||||
op getResource(
|
||||
@path id: string,
|
||||
@query filter?: string
|
||||
): ResourceResponse;
|
||||
```
|
||||
|
||||
### Models
|
||||
```typescript
|
||||
model Resource {
|
||||
id: string;
|
||||
name: string;
|
||||
description?: string; // Optional fields
|
||||
status: "active" | "inactive"; // Union types for enums
|
||||
@format("date-time")
|
||||
createdAt: utcDateTime;
|
||||
@format("uri")
|
||||
url?: string;
|
||||
}
|
||||
|
||||
model ResourceList {
|
||||
items: Resource[];
|
||||
totalCount: int32;
|
||||
nextPage?: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
**API Key**
|
||||
```typescript
|
||||
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)
|
||||
|
||||
// Or with reference ID
|
||||
@useAuth(Auth)
|
||||
@authReferenceId("${{ENV_VAR_REFERENCE_ID}}")
|
||||
model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">;
|
||||
```
|
||||
|
||||
**OAuth2**
|
||||
```typescript
|
||||
@useAuth(OAuth2Auth<[{
|
||||
type: OAuth2FlowType.authorizationCode;
|
||||
authorizationUrl: "https://auth.example.com/authorize";
|
||||
tokenUrl: "https://auth.example.com/token";
|
||||
refreshUrl: "https://auth.example.com/refresh";
|
||||
scopes: ["read", "write"];
|
||||
}]>)
|
||||
|
||||
// Or with reference ID
|
||||
@useAuth(Auth)
|
||||
@authReferenceId("${{OAUTH_REFERENCE_ID}}")
|
||||
model Auth is OAuth2Auth<[...]>;
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Files
|
||||
- `main.tsp` - Agent definition
|
||||
- `actions.tsp` - API operations
|
||||
- `[feature].tsp` - Additional feature files
|
||||
- `cards/*.json` - Adaptive Card templates
|
||||
|
||||
### TypeSpec Elements
|
||||
- **Namespaces**: PascalCase (e.g., `CustomerSupportAgent`)
|
||||
- **Operations**: camelCase (e.g., `listProjects`, `createTicket`)
|
||||
- **Models**: PascalCase (e.g., `Project`, `TicketResponse`)
|
||||
- **Model Properties**: camelCase (e.g., `projectId`, `createdDate`)
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Multi-Capability Agent
|
||||
```typescript
|
||||
@agent("Knowledge Worker", "Description")
|
||||
@instructions("...")
|
||||
namespace KnowledgeWorker {
|
||||
op webSearch is AgentCapabilities.WebSearch;
|
||||
op files is AgentCapabilities.OneDriveAndSharePoint;
|
||||
op people is AgentCapabilities.People;
|
||||
}
|
||||
```
|
||||
|
||||
### CRUD API Plugin
|
||||
```typescript
|
||||
namespace ProjectAPI {
|
||||
@route("/projects") @get @action
|
||||
op list(): Project[];
|
||||
|
||||
@route("/projects/{id}") @get @action
|
||||
op get(@path id: string): Project;
|
||||
|
||||
@route("/projects") @post @action
|
||||
@capabilities(#{confirmation: ...})
|
||||
op create(@body project: CreateProject): Project;
|
||||
|
||||
@route("/projects/{id}") @patch @action
|
||||
@capabilities(#{confirmation: ...})
|
||||
op update(@path id: string, @body project: UpdateProject): Project;
|
||||
|
||||
@route("/projects/{id}") @delete @action
|
||||
@capabilities(#{confirmation: ...})
|
||||
op delete(@path id: string): void;
|
||||
}
|
||||
```
|
||||
|
||||
### Adaptive Card Data Binding
|
||||
```json
|
||||
{
|
||||
"type": "AdaptiveCard",
|
||||
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
|
||||
"version": "1.5",
|
||||
"body": [
|
||||
{
|
||||
"type": "Container",
|
||||
"$data": "${$root}",
|
||||
"items": [
|
||||
{
|
||||
"type": "TextBlock",
|
||||
"text": "Title: ${if(title, title, 'N/A')}",
|
||||
"wrap": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Validation and Testing
|
||||
|
||||
### Before Provisioning
|
||||
1. Run TypeSpec validation: `npm run build` or use Agents Toolkit
|
||||
2. Check all file paths in `@card` decorators exist
|
||||
3. Verify authentication references match configuration
|
||||
4. Ensure capability scoping is appropriate
|
||||
5. Review instructions for clarity and length
|
||||
|
||||
### Testing Strategy
|
||||
1. **Provision**: Deploy to development environment
|
||||
2. **Test**: Use Microsoft 365 Copilot at https://m365.cloud.microsoft/chat
|
||||
3. **Debug**: Enable Copilot developer mode for orchestrator insights
|
||||
4. **Iterate**: Refine based on actual behavior
|
||||
5. **Validate**: Test all conversation starters and capabilities
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
1. **Scope Capabilities**: Don't grant access to all data if only subset needed
|
||||
2. **Limit Operations**: Only expose API operations the agent actually uses
|
||||
3. **Efficient Models**: Keep response models focused on necessary data
|
||||
4. **Card Optimization**: Use conditional rendering (`$when`) in Adaptive Cards
|
||||
5. **Caching**: Design APIs with appropriate caching headers
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Authentication**: Always use authentication for non-public APIs
|
||||
2. **Scoping**: Limit capability access to minimum required resources
|
||||
3. **Validation**: Validate all inputs in API operations
|
||||
4. **Secrets**: Use environment variables for sensitive data
|
||||
5. **References**: Use `@authReferenceId` for production credentials
|
||||
6. **Permissions**: Request minimum necessary OAuth scopes
|
||||
|
||||
## Error Handling
|
||||
|
||||
```typescript
|
||||
model ErrorResponse {
|
||||
error: {
|
||||
code: string;
|
||||
message: string;
|
||||
details?: ErrorDetail[];
|
||||
};
|
||||
}
|
||||
|
||||
model ErrorDetail {
|
||||
field?: string;
|
||||
message: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
Include comments in TypeSpec for complex operations:
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Retrieves project details with associated tasks and team members.
|
||||
*
|
||||
* @param id - Unique project identifier
|
||||
* @param includeArchived - Whether to include archived tasks
|
||||
* @returns Complete project information
|
||||
*/
|
||||
@route("/projects/{id}")
|
||||
@get
|
||||
@action
|
||||
op getProjectDetails(
|
||||
@path id: string,
|
||||
@query includeArchived?: boolean
|
||||
): ProjectDetails;
|
||||
```
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
1. ❌ Generic agent names ("Helper Bot")
|
||||
2. ❌ Vague instructions ("Help users with things")
|
||||
3. ❌ No capability scoping (accessing all data)
|
||||
4. ❌ Missing confirmations on destructive operations
|
||||
5. ❌ Overly complex Adaptive Cards
|
||||
6. ❌ Hard-coded credentials in TypeSpec files
|
||||
7. ❌ Missing error response models
|
||||
8. ❌ Inconsistent naming conventions
|
||||
9. ❌ Too many capabilities (use only what's needed)
|
||||
10. ❌ Instructions over 8,000 characters
|
||||
|
||||
## Resources
|
||||
|
||||
- [TypeSpec Official Docs](https://typespec.io/)
|
||||
- [Microsoft 365 Copilot Extensibility](https://learn.microsoft.com/microsoft-365-copilot/extensibility/)
|
||||
- [Agents Toolkit](https://aka.ms/M365AgentsToolkit)
|
||||
- [Adaptive Cards Designer](https://adaptivecards.io/designer/)
|
||||
Reference in New Issue
Block a user