feat: sync all 140 Microsoft skills with collision protection
- Add find_github_skills() to discover skills in .github/skills/ not reachable via the skills/ symlink tree (picks up 11 missing skills) - Add collision protection: if a target directory exists and was not from a previous Microsoft sync, append -ms suffix instead of overwriting - Microsoft mcp-builder → mcp-builder-ms (community version preserved) - Microsoft skill-creator → skill-creator-ms (community version preserved) - Total skills: 856 (was 845, +11 newly discovered)
This commit is contained in:
Ahmed Rehan
296
skills/azd-deployment/SKILL.md
Normal file
296
skills/azd-deployment/SKILL.md
Normal file
@@ -0,0 +1,296 @@
|
||||
---
|
||||
name: azd-deployment
|
||||
description: Deploy containerized applications to Azure Container Apps using Azure Developer CLI (azd). Use when setting up azd projects, writing azure.yaml configuration, creating Bicep infrastructure for Container Apps, configuring remote builds with ACR, implementing idempotent deployments, managing environment variables across local/.azure/Bicep, or troubleshooting azd up failures. Triggers on requests for azd configuration, Container Apps deployment, multi-service deployments, and infrastructure-as-code with Bicep.
|
||||
---
|
||||
|
||||
# Azure Developer CLI (azd) Container Apps Deployment
|
||||
|
||||
Deploy containerized frontend + backend applications to Azure Container Apps with remote builds, managed identity, and idempotent infrastructure.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize and deploy
|
||||
azd auth login
|
||||
azd init # Creates azure.yaml and .azure/ folder
|
||||
azd env new <env-name> # Create environment (dev, staging, prod)
|
||||
azd up # Provision infra + build + deploy
|
||||
```
|
||||
|
||||
## Core File Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── azure.yaml # azd service definitions + hooks
|
||||
├── infra/
|
||||
│ ├── main.bicep # Root infrastructure module
|
||||
│ ├── main.parameters.json # Parameter injection from env vars
|
||||
│ └── modules/
|
||||
│ ├── container-apps-environment.bicep
|
||||
│ └── container-app.bicep
|
||||
├── .azure/
|
||||
│ ├── config.json # Default environment pointer
|
||||
│ └── <env-name>/
|
||||
│ ├── .env # Environment-specific values (azd-managed)
|
||||
│ └── config.json # Environment metadata
|
||||
└── src/
|
||||
├── frontend/Dockerfile
|
||||
└── backend/Dockerfile
|
||||
```
|
||||
|
||||
## azure.yaml Configuration
|
||||
|
||||
### Minimal Configuration
|
||||
|
||||
```yaml
|
||||
name: azd-deployment
|
||||
services:
|
||||
backend:
|
||||
project: ./src/backend
|
||||
language: python
|
||||
host: containerapp
|
||||
docker:
|
||||
path: ./Dockerfile
|
||||
remoteBuild: true
|
||||
```
|
||||
|
||||
### Full Configuration with Hooks
|
||||
|
||||
```yaml
|
||||
name: azd-deployment
|
||||
metadata:
|
||||
template: my-project@1.0.0
|
||||
|
||||
infra:
|
||||
provider: bicep
|
||||
path: ./infra
|
||||
|
||||
azure:
|
||||
location: eastus2
|
||||
|
||||
services:
|
||||
frontend:
|
||||
project: ./src/frontend
|
||||
language: ts
|
||||
host: containerapp
|
||||
docker:
|
||||
path: ./Dockerfile
|
||||
context: .
|
||||
remoteBuild: true
|
||||
|
||||
backend:
|
||||
project: ./src/backend
|
||||
language: python
|
||||
host: containerapp
|
||||
docker:
|
||||
path: ./Dockerfile
|
||||
context: .
|
||||
remoteBuild: true
|
||||
|
||||
hooks:
|
||||
preprovision:
|
||||
shell: sh
|
||||
run: |
|
||||
echo "Before provisioning..."
|
||||
|
||||
postprovision:
|
||||
shell: sh
|
||||
run: |
|
||||
echo "After provisioning - set up RBAC, etc."
|
||||
|
||||
postdeploy:
|
||||
shell: sh
|
||||
run: |
|
||||
echo "Frontend: ${SERVICE_FRONTEND_URI}"
|
||||
echo "Backend: ${SERVICE_BACKEND_URI}"
|
||||
```
|
||||
|
||||
### Key azure.yaml Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `remoteBuild: true` | Build images in Azure Container Registry (recommended) |
|
||||
| `context: .` | Docker build context relative to project path |
|
||||
| `host: containerapp` | Deploy to Azure Container Apps |
|
||||
| `infra.provider: bicep` | Use Bicep for infrastructure |
|
||||
|
||||
## Environment Variables Flow
|
||||
|
||||
### Three-Level Configuration
|
||||
|
||||
1. **Local `.env`** - For local development only
|
||||
2. **`.azure/<env>/.env`** - azd-managed, auto-populated from Bicep outputs
|
||||
3. **`main.parameters.json`** - Maps env vars to Bicep parameters
|
||||
|
||||
### Parameter Injection Pattern
|
||||
|
||||
```json
|
||||
// infra/main.parameters.json
|
||||
{
|
||||
"parameters": {
|
||||
"environmentName": { "value": "${AZURE_ENV_NAME}" },
|
||||
"location": { "value": "${AZURE_LOCATION=eastus2}" },
|
||||
"azureOpenAiEndpoint": { "value": "${AZURE_OPENAI_ENDPOINT}" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Syntax: `${VAR_NAME}` or `${VAR_NAME=default_value}`
|
||||
|
||||
### Setting Environment Variables
|
||||
|
||||
```bash
|
||||
# Set for current environment
|
||||
azd env set AZURE_OPENAI_ENDPOINT "https://my-openai.openai.azure.com"
|
||||
azd env set AZURE_SEARCH_ENDPOINT "https://my-search.search.windows.net"
|
||||
|
||||
# Set during init
|
||||
azd env new prod
|
||||
azd env set AZURE_OPENAI_ENDPOINT "..."
|
||||
```
|
||||
|
||||
### Bicep Output → Environment Variable
|
||||
|
||||
```bicep
|
||||
// In main.bicep - outputs auto-populate .azure/<env>/.env
|
||||
output SERVICE_FRONTEND_URI string = frontend.outputs.uri
|
||||
output SERVICE_BACKEND_URI string = backend.outputs.uri
|
||||
output BACKEND_PRINCIPAL_ID string = backend.outputs.principalId
|
||||
```
|
||||
|
||||
## Idempotent Deployments
|
||||
|
||||
### Why azd up is Idempotent
|
||||
|
||||
1. **Bicep is declarative** - Resources reconcile to desired state
|
||||
2. **Remote builds tag uniquely** - Image tags include deployment timestamp
|
||||
3. **ACR reuses layers** - Only changed layers upload
|
||||
|
||||
### Preserving Manual Changes
|
||||
|
||||
Custom domains added via Portal can be lost on redeploy. Preserve with hooks:
|
||||
|
||||
```yaml
|
||||
hooks:
|
||||
preprovision:
|
||||
shell: sh
|
||||
run: |
|
||||
# Save custom domains before provision
|
||||
if az containerapp show --name "$FRONTEND_NAME" -g "$RG" &>/dev/null; then
|
||||
az containerapp show --name "$FRONTEND_NAME" -g "$RG" \
|
||||
--query "properties.configuration.ingress.customDomains" \
|
||||
-o json > /tmp/domains.json
|
||||
fi
|
||||
|
||||
postprovision:
|
||||
shell: sh
|
||||
run: |
|
||||
# Verify/restore custom domains
|
||||
if [ -f /tmp/domains.json ]; then
|
||||
echo "Saved domains: $(cat /tmp/domains.json)"
|
||||
fi
|
||||
```
|
||||
|
||||
### Handling Existing Resources
|
||||
|
||||
```bicep
|
||||
// Reference existing ACR (don't recreate)
|
||||
resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
|
||||
name: containerRegistryName
|
||||
}
|
||||
|
||||
// Set customDomains to null to preserve Portal-added domains
|
||||
customDomains: empty(customDomainsParam) ? null : customDomainsParam
|
||||
```
|
||||
|
||||
## Container App Service Discovery
|
||||
|
||||
Internal HTTP routing between Container Apps in same environment:
|
||||
|
||||
```bicep
|
||||
// Backend reference in frontend env vars
|
||||
env: [
|
||||
{
|
||||
name: 'BACKEND_URL'
|
||||
value: 'http://ca-backend-${resourceToken}' // Internal DNS
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Frontend nginx proxies to internal URL:
|
||||
```nginx
|
||||
location /api {
|
||||
proxy_pass $BACKEND_URL;
|
||||
}
|
||||
```
|
||||
|
||||
## Managed Identity & RBAC
|
||||
|
||||
### Enable System-Assigned Identity
|
||||
|
||||
```bicep
|
||||
resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
|
||||
identity: {
|
||||
type: 'SystemAssigned'
|
||||
}
|
||||
}
|
||||
|
||||
output principalId string = containerApp.identity.principalId
|
||||
```
|
||||
|
||||
### Post-Provision RBAC Assignment
|
||||
|
||||
```yaml
|
||||
hooks:
|
||||
postprovision:
|
||||
shell: sh
|
||||
run: |
|
||||
PRINCIPAL_ID="${BACKEND_PRINCIPAL_ID}"
|
||||
|
||||
# Azure OpenAI access
|
||||
az role assignment create \
|
||||
--assignee-object-id "$PRINCIPAL_ID" \
|
||||
--assignee-principal-type ServicePrincipal \
|
||||
--role "Cognitive Services OpenAI User" \
|
||||
--scope "$OPENAI_RESOURCE_ID" 2>/dev/null || true
|
||||
|
||||
# Azure AI Search access
|
||||
az role assignment create \
|
||||
--assignee-object-id "$PRINCIPAL_ID" \
|
||||
--role "Search Index Data Reader" \
|
||||
--scope "$SEARCH_RESOURCE_ID" 2>/dev/null || true
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# Environment management
|
||||
azd env list # List environments
|
||||
azd env select <name> # Switch environment
|
||||
azd env get-values # Show all env vars
|
||||
azd env set KEY value # Set variable
|
||||
|
||||
# Deployment
|
||||
azd up # Full provision + deploy
|
||||
azd provision # Infrastructure only
|
||||
azd deploy # Code deployment only
|
||||
azd deploy --service backend # Deploy single service
|
||||
|
||||
# Debugging
|
||||
azd show # Show project status
|
||||
az containerapp logs show -n <app> -g <rg> --follow # Stream logs
|
||||
```
|
||||
|
||||
## Reference Files
|
||||
|
||||
- **Bicep patterns**: See [references/bicep-patterns.md](references/bicep-patterns.md) for Container Apps modules
|
||||
- **Troubleshooting**: See [references/troubleshooting.md](references/troubleshooting.md) for common issues
|
||||
- **azure.yaml schema**: See [references/azure-yaml-schema.md](references/azure-yaml-schema.md) for full options
|
||||
|
||||
## Critical Reminders
|
||||
|
||||
1. **Always use `remoteBuild: true`** - Local builds fail on M1/ARM Macs deploying to AMD64
|
||||
2. **Bicep outputs auto-populate .azure/<env>/.env** - Don't manually edit
|
||||
3. **Use `azd env set` for secrets** - Not main.parameters.json defaults
|
||||
4. **Service tags (`azd-service-name`)** - Required for azd to find Container Apps
|
||||
5. **`|| true` in hooks** - Prevent RBAC "already exists" errors from failing deploy
|
||||
349
skills/azure-ai-agents-persistent-dotnet/SKILL.md
Normal file
349
skills/azure-ai-agents-persistent-dotnet/SKILL.md
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
name: azure-ai-agents-persistent-dotnet
|
||||
description: |
|
||||
Azure AI Agents Persistent SDK for .NET. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools. Use for agent CRUD, conversation threads, streaming responses, function calling, file search, and code interpreter. Triggers: "PersistentAgentsClient", "persistent agents", "agent threads", "agent runs", "streaming agents", "function calling agents .NET".
|
||||
package: Azure.AI.Agents.Persistent
|
||||
---
|
||||
|
||||
# Azure.AI.Agents.Persistent (.NET)
|
||||
|
||||
Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
dotnet add package Azure.AI.Agents.Persistent --prerelease
|
||||
dotnet add package Azure.Identity
|
||||
```
|
||||
|
||||
**Current Versions**: Stable v1.1.0, Preview v1.2.0-beta.8
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
|
||||
MODEL_DEPLOYMENT_NAME=gpt-4o-mini
|
||||
AZURE_BING_CONNECTION_ID=<bing-connection-resource-id>
|
||||
AZURE_AI_SEARCH_CONNECTION_ID=<search-connection-resource-id>
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
```csharp
|
||||
using Azure.AI.Agents.Persistent;
|
||||
using Azure.Identity;
|
||||
|
||||
var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
|
||||
PersistentAgentsClient client = new(projectEndpoint, new DefaultAzureCredential());
|
||||
```
|
||||
|
||||
## Client Hierarchy
|
||||
|
||||
```
|
||||
PersistentAgentsClient
|
||||
├── Administration → Agent CRUD operations
|
||||
├── Threads → Thread management
|
||||
├── Messages → Message operations
|
||||
├── Runs → Run execution and streaming
|
||||
├── Files → File upload/download
|
||||
└── VectorStores → Vector store management
|
||||
```
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### 1. Create Agent
|
||||
|
||||
```csharp
|
||||
var modelDeploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME");
|
||||
|
||||
PersistentAgent agent = await client.Administration.CreateAgentAsync(
|
||||
model: modelDeploymentName,
|
||||
name: "Math Tutor",
|
||||
instructions: "You are a personal math tutor. Write and run code to answer math questions.",
|
||||
tools: [new CodeInterpreterToolDefinition()]
|
||||
);
|
||||
```
|
||||
|
||||
### 2. Create Thread and Message
|
||||
|
||||
```csharp
|
||||
// Create thread
|
||||
PersistentAgentThread thread = await client.Threads.CreateThreadAsync();
|
||||
|
||||
// Create message
|
||||
await client.Messages.CreateMessageAsync(
|
||||
thread.Id,
|
||||
MessageRole.User,
|
||||
"I need to solve the equation `3x + 11 = 14`. Can you help me?"
|
||||
);
|
||||
```
|
||||
|
||||
### 3. Run Agent (Polling)
|
||||
|
||||
```csharp
|
||||
// Create run
|
||||
ThreadRun run = await client.Runs.CreateRunAsync(
|
||||
thread.Id,
|
||||
agent.Id,
|
||||
additionalInstructions: "Please address the user as Jane Doe."
|
||||
);
|
||||
|
||||
// Poll for completion
|
||||
do
|
||||
{
|
||||
await Task.Delay(TimeSpan.FromMilliseconds(500));
|
||||
run = await client.Runs.GetRunAsync(thread.Id, run.Id);
|
||||
}
|
||||
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
|
||||
|
||||
// Retrieve messages
|
||||
await foreach (PersistentThreadMessage message in client.Messages.GetMessagesAsync(
|
||||
threadId: thread.Id,
|
||||
order: ListSortOrder.Ascending))
|
||||
{
|
||||
Console.Write($"{message.Role}: ");
|
||||
foreach (MessageContent content in message.ContentItems)
|
||||
{
|
||||
if (content is MessageTextContent textContent)
|
||||
Console.WriteLine(textContent.Text);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Streaming Response
|
||||
|
||||
```csharp
|
||||
AsyncCollectionResult<StreamingUpdate> stream = client.Runs.CreateRunStreamingAsync(
|
||||
thread.Id,
|
||||
agent.Id
|
||||
);
|
||||
|
||||
await foreach (StreamingUpdate update in stream)
|
||||
{
|
||||
if (update.UpdateKind == StreamingUpdateReason.RunCreated)
|
||||
{
|
||||
Console.WriteLine("--- Run started! ---");
|
||||
}
|
||||
else if (update is MessageContentUpdate contentUpdate)
|
||||
{
|
||||
Console.Write(contentUpdate.Text);
|
||||
}
|
||||
else if (update.UpdateKind == StreamingUpdateReason.RunCompleted)
|
||||
{
|
||||
Console.WriteLine("\n--- Run completed! ---");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Function Calling
|
||||
|
||||
```csharp
|
||||
// Define function tool
|
||||
FunctionToolDefinition weatherTool = new(
|
||||
name: "getCurrentWeather",
|
||||
description: "Gets the current weather at a location.",
|
||||
parameters: BinaryData.FromObjectAsJson(new
|
||||
{
|
||||
Type = "object",
|
||||
Properties = new
|
||||
{
|
||||
Location = new { Type = "string", Description = "City and state, e.g. San Francisco, CA" },
|
||||
Unit = new { Type = "string", Enum = new[] { "c", "f" } }
|
||||
},
|
||||
Required = new[] { "location" }
|
||||
}, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase })
|
||||
);
|
||||
|
||||
// Create agent with function
|
||||
PersistentAgent agent = await client.Administration.CreateAgentAsync(
|
||||
model: modelDeploymentName,
|
||||
name: "Weather Bot",
|
||||
instructions: "You are a weather bot.",
|
||||
tools: [weatherTool]
|
||||
);
|
||||
|
||||
// Handle function calls during polling
|
||||
do
|
||||
{
|
||||
await Task.Delay(500);
|
||||
run = await client.Runs.GetRunAsync(thread.Id, run.Id);
|
||||
|
||||
if (run.Status == RunStatus.RequiresAction
|
||||
&& run.RequiredAction is SubmitToolOutputsAction submitAction)
|
||||
{
|
||||
List<ToolOutput> outputs = [];
|
||||
foreach (RequiredToolCall toolCall in submitAction.ToolCalls)
|
||||
{
|
||||
if (toolCall is RequiredFunctionToolCall funcCall)
|
||||
{
|
||||
// Execute function and get result
|
||||
string result = ExecuteFunction(funcCall.Name, funcCall.Arguments);
|
||||
outputs.Add(new ToolOutput(toolCall, result));
|
||||
}
|
||||
}
|
||||
run = await client.Runs.SubmitToolOutputsToRunAsync(run, outputs, toolApprovals: null);
|
||||
}
|
||||
}
|
||||
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
|
||||
```
|
||||
|
||||
### 6. File Search with Vector Store
|
||||
|
||||
```csharp
|
||||
// Upload file
|
||||
PersistentAgentFileInfo file = await client.Files.UploadFileAsync(
|
||||
filePath: "document.txt",
|
||||
purpose: PersistentAgentFilePurpose.Agents
|
||||
);
|
||||
|
||||
// Create vector store
|
||||
PersistentAgentsVectorStore vectorStore = await client.VectorStores.CreateVectorStoreAsync(
|
||||
fileIds: [file.Id],
|
||||
name: "my_vector_store"
|
||||
);
|
||||
|
||||
// Create file search resource
|
||||
FileSearchToolResource fileSearchResource = new();
|
||||
fileSearchResource.VectorStoreIds.Add(vectorStore.Id);
|
||||
|
||||
// Create agent with file search
|
||||
PersistentAgent agent = await client.Administration.CreateAgentAsync(
|
||||
model: modelDeploymentName,
|
||||
name: "Document Assistant",
|
||||
instructions: "You help users find information in documents.",
|
||||
tools: [new FileSearchToolDefinition()],
|
||||
toolResources: new ToolResources { FileSearch = fileSearchResource }
|
||||
);
|
||||
```
|
||||
|
||||
### 7. Bing Grounding
|
||||
|
||||
```csharp
|
||||
var bingConnectionId = Environment.GetEnvironmentVariable("AZURE_BING_CONNECTION_ID");
|
||||
|
||||
BingGroundingToolDefinition bingTool = new(
|
||||
new BingGroundingSearchToolParameters(
|
||||
[new BingGroundingSearchConfiguration(bingConnectionId)]
|
||||
)
|
||||
);
|
||||
|
||||
PersistentAgent agent = await client.Administration.CreateAgentAsync(
|
||||
model: modelDeploymentName,
|
||||
name: "Search Agent",
|
||||
instructions: "Use Bing to answer questions about current events.",
|
||||
tools: [bingTool]
|
||||
);
|
||||
```
|
||||
|
||||
### 8. Azure AI Search
|
||||
|
||||
```csharp
|
||||
AzureAISearchToolResource searchResource = new(
|
||||
connectionId: searchConnectionId,
|
||||
indexName: "my_index",
|
||||
topK: 5,
|
||||
filter: "category eq 'documentation'",
|
||||
queryType: AzureAISearchQueryType.Simple
|
||||
);
|
||||
|
||||
PersistentAgent agent = await client.Administration.CreateAgentAsync(
|
||||
model: modelDeploymentName,
|
||||
name: "Search Agent",
|
||||
instructions: "Search the documentation index to answer questions.",
|
||||
tools: [new AzureAISearchToolDefinition()],
|
||||
toolResources: new ToolResources { AzureAISearch = searchResource }
|
||||
);
|
||||
```
|
||||
|
||||
### 9. Cleanup
|
||||
|
||||
```csharp
|
||||
await client.Threads.DeleteThreadAsync(thread.Id);
|
||||
await client.Administration.DeleteAgentAsync(agent.Id);
|
||||
await client.VectorStores.DeleteVectorStoreAsync(vectorStore.Id);
|
||||
await client.Files.DeleteFileAsync(file.Id);
|
||||
```
|
||||
|
||||
## Available Tools
|
||||
|
||||
| Tool | Class | Purpose |
|
||||
|------|-------|---------|
|
||||
| Code Interpreter | `CodeInterpreterToolDefinition` | Execute Python code, generate visualizations |
|
||||
| File Search | `FileSearchToolDefinition` | Search uploaded files via vector stores |
|
||||
| Function Calling | `FunctionToolDefinition` | Call custom functions |
|
||||
| Bing Grounding | `BingGroundingToolDefinition` | Web search via Bing |
|
||||
| Azure AI Search | `AzureAISearchToolDefinition` | Search Azure AI Search indexes |
|
||||
| OpenAPI | `OpenApiToolDefinition` | Call external APIs via OpenAPI spec |
|
||||
| Azure Functions | `AzureFunctionToolDefinition` | Invoke Azure Functions |
|
||||
| MCP | `MCPToolDefinition` | Model Context Protocol tools |
|
||||
| SharePoint | `SharepointToolDefinition` | Access SharePoint content |
|
||||
| Microsoft Fabric | `MicrosoftFabricToolDefinition` | Access Fabric data |
|
||||
|
||||
## Streaming Update Types
|
||||
|
||||
| Update Type | Description |
|
||||
|-------------|-------------|
|
||||
| `StreamingUpdateReason.RunCreated` | Run started |
|
||||
| `StreamingUpdateReason.RunInProgress` | Run processing |
|
||||
| `StreamingUpdateReason.RunCompleted` | Run finished |
|
||||
| `StreamingUpdateReason.RunFailed` | Run errored |
|
||||
| `MessageContentUpdate` | Text content chunk |
|
||||
| `RunStepUpdate` | Step status change |
|
||||
|
||||
## Key Types Reference
|
||||
|
||||
| Type | Purpose |
|
||||
|------|---------|
|
||||
| `PersistentAgentsClient` | Main entry point |
|
||||
| `PersistentAgent` | Agent with model, instructions, tools |
|
||||
| `PersistentAgentThread` | Conversation thread |
|
||||
| `PersistentThreadMessage` | Message in thread |
|
||||
| `ThreadRun` | Execution of agent against thread |
|
||||
| `RunStatus` | Queued, InProgress, RequiresAction, Completed, Failed |
|
||||
| `ToolResources` | Combined tool resources |
|
||||
| `ToolOutput` | Function call response |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always dispose clients** — Use `using` statements or explicit disposal
|
||||
2. **Poll with appropriate delays** — 500ms recommended between status checks
|
||||
3. **Clean up resources** — Delete threads and agents when done
|
||||
4. **Handle all run statuses** — Check for `RequiresAction`, `Failed`, `Cancelled`
|
||||
5. **Use streaming for real-time UX** — Better user experience than polling
|
||||
6. **Store IDs not objects** — Reference agents/threads by ID
|
||||
7. **Use async methods** — All operations should be async
|
||||
|
||||
## Error Handling
|
||||
|
||||
```csharp
|
||||
using Azure;
|
||||
|
||||
try
|
||||
{
|
||||
var agent = await client.Administration.CreateAgentAsync(...);
|
||||
}
|
||||
catch (RequestFailedException ex) when (ex.Status == 404)
|
||||
{
|
||||
Console.WriteLine("Resource not found");
|
||||
}
|
||||
catch (RequestFailedException ex)
|
||||
{
|
||||
Console.WriteLine($"Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
|
||||
}
|
||||
```
|
||||
|
||||
## Related SDKs
|
||||
|
||||
| SDK | Purpose | Install |
|
||||
|-----|---------|---------|
|
||||
| `Azure.AI.Agents.Persistent` | Low-level agents (this SDK) | `dotnet add package Azure.AI.Agents.Persistent` |
|
||||
| `Azure.AI.Projects` | High-level project client | `dotnet add package Azure.AI.Projects` |
|
||||
|
||||
## Reference Links
|
||||
|
||||
| Resource | URL |
|
||||
|----------|-----|
|
||||
| NuGet Package | https://www.nuget.org/packages/Azure.AI.Agents.Persistent |
|
||||
| API Reference | https://learn.microsoft.com/dotnet/api/azure.ai.agents.persistent |
|
||||
| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Agents.Persistent |
|
||||
| Samples | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Agents.Persistent/samples |
|
||||
137
skills/azure-ai-agents-persistent-java/SKILL.md
Normal file
137
skills/azure-ai-agents-persistent-java/SKILL.md
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
name: azure-ai-agents-persistent-java
|
||||
description: |
|
||||
Azure AI Agents Persistent SDK for Java. Low-level SDK for creating and managing AI agents with threads, messages, runs, and tools.
|
||||
Triggers: "PersistentAgentsClient", "persistent agents java", "agent threads java", "agent runs java", "streaming agents java".
|
||||
package: com.azure:azure-ai-agents-persistent
|
||||
---
|
||||
|
||||
# Azure AI Agents Persistent SDK for Java
|
||||
|
||||
Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.
|
||||
|
||||
## Installation
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.azure</groupId>
|
||||
<artifactId>azure-ai-agents-persistent</artifactId>
|
||||
<version>1.0.0-beta.1</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
|
||||
MODEL_DEPLOYMENT_NAME=gpt-4o-mini
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
```java
|
||||
import com.azure.ai.agents.persistent.PersistentAgentsClient;
|
||||
import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;
|
||||
import com.azure.identity.DefaultAzureCredentialBuilder;
|
||||
|
||||
String endpoint = System.getenv("PROJECT_ENDPOINT");
|
||||
PersistentAgentsClient client = new PersistentAgentsClientBuilder()
|
||||
.endpoint(endpoint)
|
||||
.credential(new DefaultAzureCredentialBuilder().build())
|
||||
.buildClient();
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
The Azure AI Agents Persistent SDK provides a low-level API for managing persistent agents that can be reused across sessions.
|
||||
|
||||
### Client Hierarchy
|
||||
|
||||
| Client | Purpose |
|
||||
|--------|---------|
|
||||
| `PersistentAgentsClient` | Sync client for agent operations |
|
||||
| `PersistentAgentsAsyncClient` | Async client for agent operations |
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### 1. Create Agent
|
||||
|
||||
```java
|
||||
// Create agent with tools
|
||||
PersistentAgent agent = client.createAgent(
|
||||
modelDeploymentName,
|
||||
"Math Tutor",
|
||||
"You are a personal math tutor."
|
||||
);
|
||||
```
|
||||
|
||||
### 2. Create Thread
|
||||
|
||||
```java
|
||||
PersistentAgentThread thread = client.createThread();
|
||||
```
|
||||
|
||||
### 3. Add Message
|
||||
|
||||
```java
|
||||
client.createMessage(
|
||||
thread.getId(),
|
||||
MessageRole.USER,
|
||||
"I need help with equations."
|
||||
);
|
||||
```
|
||||
|
||||
### 4. Run Agent
|
||||
|
||||
```java
|
||||
ThreadRun run = client.createRun(thread.getId(), agent.getId());
|
||||
|
||||
// Poll for completion
|
||||
while (run.getStatus() == RunStatus.QUEUED || run.getStatus() == RunStatus.IN_PROGRESS) {
|
||||
Thread.sleep(500);
|
||||
run = client.getRun(thread.getId(), run.getId());
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Get Response
|
||||
|
||||
```java
|
||||
PagedIterable<PersistentThreadMessage> messages = client.listMessages(thread.getId());
|
||||
for (PersistentThreadMessage message : messages) {
|
||||
System.out.println(message.getRole() + ": " + message.getContent());
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Cleanup
|
||||
|
||||
```java
|
||||
client.deleteThread(thread.getId());
|
||||
client.deleteAgent(agent.getId());
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use DefaultAzureCredential** for production authentication
|
||||
2. **Poll with appropriate delays** — 500ms recommended between status checks
|
||||
3. **Clean up resources** — Delete threads and agents when done
|
||||
4. **Handle all run statuses** — Check for RequiresAction, Failed, Cancelled
|
||||
5. **Use async client** for better throughput in high-concurrency scenarios
|
||||
|
||||
## Error Handling
|
||||
|
||||
```java
|
||||
import com.azure.core.exception.HttpResponseException;
|
||||
|
||||
try {
|
||||
PersistentAgent agent = client.createAgent(modelName, name, instructions);
|
||||
} catch (HttpResponseException e) {
|
||||
System.err.println("Error: " + e.getResponse().getStatusCode() + " - " + e.getMessage());
|
||||
}
|
||||
```
|
||||
|
||||
## Reference Links
|
||||
|
||||
| Resource | URL |
|
||||
|----------|-----|
|
||||
| Maven Package | https://central.sonatype.com/artifact/com.azure/azure-ai-agents-persistent |
|
||||
| GitHub Source | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents-persistent |
|
||||
510
skills/copilot-sdk/SKILL.md
Normal file
510
skills/copilot-sdk/SKILL.md
Normal file
@@ -0,0 +1,510 @@
|
||||
---
|
||||
name: copilot-sdk
|
||||
description: Build applications powered by GitHub Copilot using the Copilot SDK. Use when creating programmatic integrations with Copilot across Node.js/TypeScript, Python, Go, or .NET. Covers session management, custom tools, streaming, hooks, MCP servers, BYOK providers, session persistence, and custom agents. Requires GitHub Copilot CLI installed and a GitHub Copilot subscription (unless using BYOK).
|
||||
---
|
||||
|
||||
# GitHub Copilot SDK
|
||||
|
||||
Build applications that programmatically interact with GitHub Copilot. The SDK wraps the Copilot CLI via JSON-RPC, providing session management, custom tools, hooks, MCP server integration, and streaming across Node.js, Python, Go, and .NET.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **GitHub Copilot CLI** installed and authenticated (`copilot --version` to verify)
|
||||
- **GitHub Copilot subscription** (Individual, Business, or Enterprise) — not required for BYOK
|
||||
- **Runtime:** Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+
|
||||
|
||||
## Installation
|
||||
|
||||
| Language | Package | Install |
|
||||
|----------|---------|---------|
|
||||
| Node.js | `@github/copilot-sdk` | `npm install @github/copilot-sdk` |
|
||||
| Python | `github-copilot-sdk` | `pip install github-copilot-sdk` |
|
||||
| Go | `github.com/github/copilot-sdk/go` | `go get github.com/github/copilot-sdk/go` |
|
||||
| .NET | `GitHub.Copilot.SDK` | `dotnet add package GitHub.Copilot.SDK` |
|
||||
|
||||
---
|
||||
|
||||
## Core Pattern: Client → Session → Message
|
||||
|
||||
All SDK usage follows this pattern: create a client, create a session, send messages.
|
||||
|
||||
### Node.js / TypeScript
|
||||
|
||||
```typescript
|
||||
import { CopilotClient } from "@github/copilot-sdk";
|
||||
|
||||
const client = new CopilotClient();
|
||||
const session = await client.createSession({ model: "gpt-4.1" });
|
||||
|
||||
const response = await session.sendAndWait({ prompt: "What is 2 + 2?" });
|
||||
console.log(response?.data.content);
|
||||
|
||||
await client.stop();
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from copilot import CopilotClient
|
||||
|
||||
async def main():
|
||||
client = CopilotClient()
|
||||
await client.start()
|
||||
session = await client.create_session({"model": "gpt-4.1"})
|
||||
response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
|
||||
print(response.data.content)
|
||||
await client.stop()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
### Go
|
||||
|
||||
```go
|
||||
client := copilot.NewClient(nil)
|
||||
if err := client.Start(ctx); err != nil { log.Fatal(err) }
|
||||
defer client.Stop()
|
||||
|
||||
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
|
||||
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What is 2 + 2?"})
|
||||
fmt.Println(*response.Data.Content)
|
||||
```
|
||||
|
||||
### .NET
|
||||
|
||||
```csharp
|
||||
await using var client = new CopilotClient();
|
||||
await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" });
|
||||
var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2 + 2?" });
|
||||
Console.WriteLine(response?.Data.Content);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Streaming Responses
|
||||
|
||||
Enable real-time output by setting `streaming: true` and subscribing to delta events.
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({ model: "gpt-4.1", streaming: true });
|
||||
|
||||
session.on("assistant.message_delta", (event) => {
|
||||
process.stdout.write(event.data.deltaContent);
|
||||
});
|
||||
session.on("session.idle", () => console.log());
|
||||
|
||||
await session.sendAndWait({ prompt: "Tell me a joke" });
|
||||
```
|
||||
|
||||
**Python equivalent:**
|
||||
|
||||
```python
|
||||
from copilot.generated.session_events import SessionEventType
|
||||
|
||||
session = await client.create_session({"model": "gpt-4.1", "streaming": True})
|
||||
|
||||
def handle_event(event):
|
||||
if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
|
||||
sys.stdout.write(event.data.delta_content)
|
||||
sys.stdout.flush()
|
||||
|
||||
session.on(handle_event)
|
||||
await session.send_and_wait({"prompt": "Tell me a joke"})
|
||||
```
|
||||
|
||||
### Event Subscription
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `on(handler)` | Subscribe to all events; returns unsubscribe function |
|
||||
| `on(eventType, handler)` | Subscribe to specific event type (Node.js only) |
|
||||
|
||||
---
|
||||
|
||||
## Custom Tools
|
||||
|
||||
Define tools that Copilot can call to extend its capabilities.
|
||||
|
||||
### Node.js
|
||||
|
||||
```typescript
|
||||
import { CopilotClient, defineTool } from "@github/copilot-sdk";
|
||||
|
||||
const getWeather = defineTool("get_weather", {
|
||||
description: "Get the current weather for a city",
|
||||
parameters: {
|
||||
type: "object",
|
||||
properties: { city: { type: "string", description: "The city name" } },
|
||||
required: ["city"],
|
||||
},
|
||||
handler: async ({ city }) => ({ city, temperature: "72°F", condition: "sunny" }),
|
||||
});
|
||||
|
||||
const session = await client.createSession({
|
||||
model: "gpt-4.1",
|
||||
tools: [getWeather],
|
||||
});
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
from copilot.tools import define_tool
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
class GetWeatherParams(BaseModel):
|
||||
city: str = Field(description="The city name")
|
||||
|
||||
@define_tool(description="Get the current weather for a city")
|
||||
async def get_weather(params: GetWeatherParams) -> dict:
|
||||
return {"city": params.city, "temperature": "72°F", "condition": "sunny"}
|
||||
|
||||
session = await client.create_session({"model": "gpt-4.1", "tools": [get_weather]})
|
||||
```
|
||||
|
||||
### Go
|
||||
|
||||
```go
|
||||
type WeatherParams struct {
|
||||
City string `json:"city" jsonschema:"The city name"`
|
||||
}
|
||||
|
||||
getWeather := copilot.DefineTool("get_weather", "Get weather for a city",
|
||||
func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) {
|
||||
return WeatherResult{City: params.City, Temperature: "72°F"}, nil
|
||||
},
|
||||
)
|
||||
|
||||
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
|
||||
Model: "gpt-4.1",
|
||||
Tools: []copilot.Tool{getWeather},
|
||||
})
|
||||
```
|
||||
|
||||
### .NET
|
||||
|
||||
```csharp
|
||||
var getWeather = AIFunctionFactory.Create(
|
||||
([Description("The city name")] string city) => new { city, temperature = "72°F" },
|
||||
"get_weather", "Get the current weather for a city");
|
||||
|
||||
await using var session = await client.CreateSessionAsync(new SessionConfig {
|
||||
Model = "gpt-4.1", Tools = [getWeather],
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hooks
|
||||
|
||||
Intercept and customize session behavior at key lifecycle points.
|
||||
|
||||
| Hook | Trigger | Use Case |
|
||||
|------|---------|----------|
|
||||
| `onPreToolUse` | Before tool executes | Permission control, argument modification |
|
||||
| `onPostToolUse` | After tool executes | Result transformation, logging |
|
||||
| `onUserPromptSubmitted` | User sends message | Prompt modification, filtering |
|
||||
| `onSessionStart` | Session begins | Add context, configure session |
|
||||
| `onSessionEnd` | Session ends | Cleanup, analytics |
|
||||
| `onErrorOccurred` | Error happens | Custom error handling, retry logic |
|
||||
|
||||
### Example: Tool Permission Control
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({
|
||||
hooks: {
|
||||
onPreToolUse: async (input) => {
|
||||
if (["shell", "bash"].includes(input.toolName)) {
|
||||
return { permissionDecision: "deny", permissionDecisionReason: "Shell access not permitted" };
|
||||
}
|
||||
return { permissionDecision: "allow" };
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Pre-Tool Use Output
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `permissionDecision` | `"allow"` \| `"deny"` \| `"ask"` | Whether to allow the tool call |
|
||||
| `permissionDecisionReason` | string | Explanation for deny/ask |
|
||||
| `modifiedArgs` | object | Modified arguments to pass |
|
||||
| `additionalContext` | string | Extra context for conversation |
|
||||
| `suppressOutput` | boolean | Hide tool output from conversation |
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Integration
|
||||
|
||||
Connect to MCP servers for pre-built tool capabilities.
|
||||
|
||||
### Remote HTTP Server
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({
|
||||
mcpServers: {
|
||||
github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Local Stdio Server
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({
|
||||
mcpServers: {
|
||||
filesystem: {
|
||||
type: "local",
|
||||
command: "npx",
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
|
||||
tools: ["*"],
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### MCP Config Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `type` | `"local"` \| `"http"` | Server transport type |
|
||||
| `command` | string | Executable path (local) |
|
||||
| `args` | string[] | Command arguments (local) |
|
||||
| `url` | string | Server URL (http) |
|
||||
| `tools` | string[] | `["*"]` or specific tool names |
|
||||
| `env` | object | Environment variables |
|
||||
| `cwd` | string | Working directory (local) |
|
||||
| `timeout` | number | Timeout in milliseconds |
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
### Methods (Priority Order)
|
||||
|
||||
1. **Explicit token** — `githubToken` in constructor
|
||||
2. **Environment variables** — `COPILOT_GITHUB_TOKEN` → `GH_TOKEN` → `GITHUB_TOKEN`
|
||||
3. **Stored OAuth** — From `copilot auth login`
|
||||
4. **GitHub CLI** — `gh auth` credentials
|
||||
|
||||
### Programmatic Token
|
||||
|
||||
```typescript
|
||||
const client = new CopilotClient({ githubToken: process.env.GITHUB_TOKEN });
|
||||
```
|
||||
|
||||
### BYOK (Bring Your Own Key)
|
||||
|
||||
Use your own API keys — no Copilot subscription required.
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({
|
||||
model: "gpt-5.2-codex",
|
||||
provider: {
|
||||
type: "openai",
|
||||
baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
|
||||
wireApi: "responses",
|
||||
apiKey: process.env.FOUNDRY_API_KEY,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
| Provider | Type | Notes |
|
||||
|----------|------|-------|
|
||||
| OpenAI | `"openai"` | OpenAI API and compatible endpoints |
|
||||
| Azure OpenAI | `"azure"` | Native Azure endpoints (don't include `/openai/v1`) |
|
||||
| Azure AI Foundry | `"openai"` | OpenAI-compatible Foundry endpoints |
|
||||
| Anthropic | `"anthropic"` | Claude models |
|
||||
| Ollama | `"openai"` | Local models, no API key needed |
|
||||
|
||||
**Wire API:** Use `"responses"` for GPT-5 series, `"completions"` (default) for others.
|
||||
|
||||
---
|
||||
|
||||
## Session Persistence
|
||||
|
||||
Resume sessions across restarts by providing your own session ID.
|
||||
|
||||
```typescript
|
||||
// Create with explicit ID
|
||||
const session = await client.createSession({
|
||||
sessionId: "user-123-task-456",
|
||||
model: "gpt-4.1",
|
||||
});
|
||||
|
||||
// Resume later
|
||||
const resumed = await client.resumeSession("user-123-task-456");
|
||||
await resumed.sendAndWait({ prompt: "What did we discuss?" });
|
||||
```
|
||||
|
||||
**Session management:**
|
||||
|
||||
```typescript
|
||||
const sessions = await client.listSessions(); // List all
|
||||
await client.deleteSession("user-123-task-456"); // Delete
|
||||
await session.destroy(); // Destroy active
|
||||
```
|
||||
|
||||
**BYOK sessions:** Must re-provide `provider` config on resume (keys are not persisted).
|
||||
|
||||
### Infinite Sessions
|
||||
|
||||
For long-running workflows that may exceed context limits:
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({
|
||||
infiniteSessions: {
|
||||
enabled: true,
|
||||
backgroundCompactionThreshold: 0.80,
|
||||
bufferExhaustionThreshold: 0.95,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Custom Agents
|
||||
|
||||
Define specialized AI personas:
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({
|
||||
customAgents: [{
|
||||
name: "pr-reviewer",
|
||||
displayName: "PR Reviewer",
|
||||
description: "Reviews pull requests for best practices",
|
||||
prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
|
||||
}],
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## System Message
|
||||
|
||||
Control AI behavior and personality:
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({
|
||||
systemMessage: { content: "You are a helpful assistant. Always be concise." },
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skills Integration
|
||||
|
||||
Load skill directories to extend Copilot's capabilities:
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({
|
||||
skillDirectories: ["./skills/code-review", "./skills/documentation"],
|
||||
disabledSkills: ["experimental-feature"],
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Permission & Input Handlers
|
||||
|
||||
Handle tool permissions and user input requests programmatically:
|
||||
|
||||
```typescript
|
||||
const session = await client.createSession({
|
||||
onPermissionRequest: async (request) => {
|
||||
// Auto-approve git commands only
|
||||
if (request.kind === "shell") {
|
||||
return { approved: request.command.startsWith("git") };
|
||||
}
|
||||
return { approved: true };
|
||||
},
|
||||
onUserInputRequest: async (request) => {
|
||||
// Handle ask_user tool calls
|
||||
return { response: "yes" };
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## External CLI Server
|
||||
|
||||
Connect to a separately running CLI instead of auto-managing the process:
|
||||
|
||||
```bash
|
||||
copilot --headless --port 4321
|
||||
```
|
||||
|
||||
```typescript
|
||||
const client = new CopilotClient({ cliUrl: "localhost:4321" });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Client Configuration
|
||||
|
||||
| Option | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `cliPath` | string | Path to Copilot CLI executable |
|
||||
| `cliUrl` | string | URL of external CLI server |
|
||||
| `githubToken` | string | GitHub token for auth |
|
||||
| `useLoggedInUser` | boolean | Use stored CLI credentials (default: true) |
|
||||
| `logLevel` | string | `"none"` \| `"error"` \| `"warning"` \| `"info"` \| `"debug"` |
|
||||
| `autoRestart` | boolean | Auto-restart CLI on crash (default: true) |
|
||||
| `useStdio` | boolean | Use stdio transport (default: true) |
|
||||
|
||||
## Session Configuration
|
||||
|
||||
| Option | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `model` | string | Model to use (e.g., `"gpt-4.1"`) |
|
||||
| `sessionId` | string | Custom ID for resumable sessions |
|
||||
| `streaming` | boolean | Enable streaming responses |
|
||||
| `tools` | Tool[] | Custom tools |
|
||||
| `mcpServers` | object | MCP server configurations |
|
||||
| `hooks` | object | Session hooks |
|
||||
| `provider` | object | BYOK provider config |
|
||||
| `customAgents` | object[] | Custom agent definitions |
|
||||
| `systemMessage` | object | System message override |
|
||||
| `skillDirectories` | string[] | Directories to load skills from |
|
||||
| `disabledSkills` | string[] | Skills to disable |
|
||||
| `reasoningEffort` | string | Reasoning effort level |
|
||||
| `availableTools` | string[] | Restrict available tools |
|
||||
| `excludedTools` | string[] | Exclude specific tools |
|
||||
| `infiniteSessions` | object | Auto-compaction config |
|
||||
| `workingDirectory` | string | Working directory |
|
||||
|
||||
---
|
||||
|
||||
## Debugging
|
||||
|
||||
Enable debug logging to troubleshoot issues:
|
||||
|
||||
```typescript
|
||||
const client = new CopilotClient({ logLevel: "debug" });
|
||||
```
|
||||
|
||||
**Common issues:**
|
||||
- `CLI not found` → Install CLI or set `cliPath`
|
||||
- `Not authenticated` → Run `copilot auth login` or provide `githubToken`
|
||||
- `Session not found` → Don't use session after `destroy()`
|
||||
- `Connection refused` → Check CLI process, enable `autoRestart`
|
||||
|
||||
---
|
||||
|
||||
## Key API Summary
|
||||
|
||||
| Language | Client | Session Create | Send | Stop |
|
||||
|----------|--------|---------------|------|------|
|
||||
| Node.js | `new CopilotClient()` | `client.createSession()` | `session.sendAndWait()` | `client.stop()` |
|
||||
| Python | `CopilotClient()` | `client.create_session()` | `session.send_and_wait()` | `client.stop()` |
|
||||
| Go | `copilot.NewClient(nil)` | `client.CreateSession()` | `session.SendAndWait()` | `client.Stop()` |
|
||||
| .NET | `new CopilotClient()` | `client.CreateSessionAsync()` | `session.SendAndWaitAsync()` | `client.DisposeAsync()` |
|
||||
|
||||
## References
|
||||
|
||||
- [GitHub Copilot SDK](https://github.com/github/copilot-sdk)
|
||||
- [Copilot CLI Installation](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli)
|
||||
- [MCP Protocol Specification](https://modelcontextprotocol.io)
|
||||
52
skills/fastapi-router-py/SKILL.md
Normal file
52
skills/fastapi-router-py/SKILL.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: fastapi-router-py
|
||||
description: Create FastAPI routers with CRUD operations, authentication dependencies, and proper response models. Use when building REST API endpoints, creating new routes, implementing CRUD operations, or adding authenticated endpoints in FastAPI applications.
|
||||
---
|
||||
|
||||
# FastAPI Router
|
||||
|
||||
Create FastAPI routers following established patterns with proper authentication, response models, and HTTP status codes.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Copy the template from [assets/template.py](assets/template.py) and replace placeholders:
|
||||
- `{{ResourceName}}` → PascalCase name (e.g., `Project`)
|
||||
- `{{resource_name}}` → snake_case name (e.g., `project`)
|
||||
- `{{resource_plural}}` → plural form (e.g., `projects`)
|
||||
|
||||
## Authentication Patterns
|
||||
|
||||
```python
|
||||
# Optional auth - returns None if not authenticated
|
||||
current_user: Optional[User] = Depends(get_current_user)
|
||||
|
||||
# Required auth - raises 401 if not authenticated
|
||||
current_user: User = Depends(get_current_user_required)
|
||||
```
|
||||
|
||||
## Response Models
|
||||
|
||||
```python
|
||||
@router.get("/items/{item_id}", response_model=Item)
|
||||
async def get_item(item_id: str) -> Item:
|
||||
...
|
||||
|
||||
@router.get("/items", response_model=list[Item])
|
||||
async def list_items() -> list[Item]:
|
||||
...
|
||||
```
|
||||
|
||||
## HTTP Status Codes
|
||||
|
||||
```python
|
||||
@router.post("/items", status_code=status.HTTP_201_CREATED)
|
||||
@router.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)
|
||||
```
|
||||
|
||||
## Integration Steps
|
||||
|
||||
1. Create router in `src/backend/app/routers/`
|
||||
2. Mount in `src/backend/app/main.py`
|
||||
3. Create corresponding Pydantic models
|
||||
4. Create service layer if needed
|
||||
5. Add frontend API functions
|
||||
137
skills/github-issue-creator/SKILL.md
Normal file
137
skills/github-issue-creator/SKILL.md
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
name: github-issue-creator
|
||||
description: Convert raw notes, error logs, voice dictation, or screenshots into crisp GitHub-flavored markdown issue reports. Use when the user pastes bug info, error messages, or informal descriptions and wants a structured GitHub issue. Supports images/GIFs for visual evidence.
|
||||
---
|
||||
|
||||
# GitHub Issue Creator
|
||||
|
||||
Transform messy input (error logs, voice notes, screenshots) into clean, actionable GitHub issues.
|
||||
|
||||
## Output Template
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
[One-line description of the issue]
|
||||
|
||||
## Environment
|
||||
- **Product/Service**:
|
||||
- **Region/Version**:
|
||||
- **Browser/OS**: (if relevant)
|
||||
|
||||
## Reproduction Steps
|
||||
1. [Step]
|
||||
2. [Step]
|
||||
3. [Step]
|
||||
|
||||
## Expected Behavior
|
||||
[What should happen]
|
||||
|
||||
## Actual Behavior
|
||||
[What actually happens]
|
||||
|
||||
## Error Details
|
||||
```
|
||||
[Error message/code if applicable]
|
||||
```
|
||||
|
||||
## Visual Evidence
|
||||
[Reference to attached screenshots/GIFs]
|
||||
|
||||
## Impact
|
||||
[Severity: Critical/High/Medium/Low + brief explanation]
|
||||
|
||||
## Additional Context
|
||||
[Any other relevant details]
|
||||
```
|
||||
|
||||
## Output Location
|
||||
|
||||
**Create issues as markdown files** in `/issues/` directory at the repo root. Use naming convention: `YYYY-MM-DD-short-description.md`
|
||||
|
||||
## Guidelines
|
||||
|
||||
**Be crisp**: No fluff. Every word should add value.
|
||||
|
||||
**Extract structure from chaos**: Voice dictation and raw notes often contain the facts buried in casual language. Pull them out.
|
||||
|
||||
**Infer missing context**: If user mentions "same project" or "the dashboard", use context from conversation or memory to fill in specifics.
|
||||
|
||||
**Placeholder sensitive data**: Use `[PROJECT_NAME]`, `[USER_ID]`, etc. for anything that might be sensitive.
|
||||
|
||||
**Match severity to impact**:
|
||||
- Critical: Service down, data loss, security issue
|
||||
- High: Major feature broken, no workaround
|
||||
- Medium: Feature impaired, workaround exists
|
||||
- Low: Minor inconvenience, cosmetic
|
||||
|
||||
**Image/GIF handling**: Reference attachments inline. Format: ``
|
||||
|
||||
## Examples
|
||||
|
||||
**Input (voice dictation)**:
|
||||
> so I was trying to deploy the agent and it just failed silently no error nothing the workflow ran but then poof gone from the list had to refresh and try again three times
|
||||
|
||||
**Output**:
|
||||
```markdown
|
||||
## Summary
|
||||
Agent deployment fails silently - no error displayed, agent disappears from list
|
||||
|
||||
## Environment
|
||||
- **Product/Service**: Azure AI Foundry
|
||||
- **Region/Version**: westus2
|
||||
|
||||
## Reproduction Steps
|
||||
1. Navigate to agent deployment
|
||||
2. Configure and deploy agent
|
||||
3. Observe workflow completes
|
||||
4. Check agent list
|
||||
|
||||
## Expected Behavior
|
||||
Agent appears in list with deployment status, errors shown if deployment fails
|
||||
|
||||
## Actual Behavior
|
||||
Agent disappears from list. No error message. Requires page refresh and retry.
|
||||
|
||||
## Impact
|
||||
**High** - Blocks agent deployment workflow, no feedback on failure cause
|
||||
|
||||
## Additional Context
|
||||
Required 3 retry attempts before successful deployment
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Input (error paste)**:
|
||||
> Error: PERMISSION_DENIED when publishing to Teams channel. Code: 403. Was working yesterday.
|
||||
|
||||
**Output**:
|
||||
```markdown
|
||||
## Summary
|
||||
403 PERMISSION_DENIED error when publishing to Teams channel
|
||||
|
||||
## Environment
|
||||
- **Product/Service**: Copilot Studio → Teams integration
|
||||
- **Region/Version**: [REGION]
|
||||
|
||||
## Reproduction Steps
|
||||
1. Configure agent for Teams channel
|
||||
2. Attempt to publish
|
||||
|
||||
## Expected Behavior
|
||||
Agent publishes successfully to Teams channel
|
||||
|
||||
## Actual Behavior
|
||||
Returns `PERMISSION_DENIED` with code 403
|
||||
|
||||
## Error Details
|
||||
```
|
||||
Error: PERMISSION_DENIED
|
||||
Code: 403
|
||||
```
|
||||
|
||||
## Impact
|
||||
**High** - Blocks Teams integration, regression from previous working state
|
||||
|
||||
## Additional Context
|
||||
Was working yesterday - possible permission/config change or service regression
|
||||
```
|
||||
325
skills/hosted-agents-v2-py/SKILL.md
Normal file
325
skills/hosted-agents-v2-py/SKILL.md
Normal file
@@ -0,0 +1,325 @@
|
||||
---
|
||||
name: hosted-agents-v2-py
|
||||
description: |
|
||||
Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition.
|
||||
Use when creating container-based agents that run custom code in Azure AI Foundry.
|
||||
Triggers: "ImageBasedHostedAgentDefinition", "hosted agent", "container agent",
|
||||
"create_version", "ProtocolVersionRecord", "AgentProtocol.RESPONSES".
|
||||
package: azure-ai-projects
|
||||
---
|
||||
|
||||
# Azure AI Hosted Agents (Python)
|
||||
|
||||
Build container-based hosted agents using `ImageBasedHostedAgentDefinition` from the Azure AI Projects SDK.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install azure-ai-projects>=2.0.0b3 azure-identity
|
||||
```
|
||||
|
||||
**Minimum SDK Version:** `2.0.0b3` or later required for hosted agent support.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before creating hosted agents:
|
||||
|
||||
1. **Container Image** - Build and push to Azure Container Registry (ACR)
|
||||
2. **ACR Pull Permissions** - Grant your project's managed identity `AcrPull` role on the ACR
|
||||
3. **Capability Host** - Account-level capability host with `enablePublicHostingEnvironment=true`
|
||||
4. **SDK Version** - Ensure `azure-ai-projects>=2.0.0b3`
|
||||
|
||||
## Authentication
|
||||
|
||||
Always use `DefaultAzureCredential`:
|
||||
|
||||
```python
|
||||
from azure.identity import DefaultAzureCredential
|
||||
from azure.ai.projects import AIProjectClient
|
||||
|
||||
credential = DefaultAzureCredential()
|
||||
client = AIProjectClient(
|
||||
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
|
||||
credential=credential
|
||||
)
|
||||
```
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### 1. Imports
|
||||
|
||||
```python
|
||||
import os
|
||||
from azure.identity import DefaultAzureCredential
|
||||
from azure.ai.projects import AIProjectClient
|
||||
from azure.ai.projects.models import (
|
||||
ImageBasedHostedAgentDefinition,
|
||||
ProtocolVersionRecord,
|
||||
AgentProtocol,
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Create Hosted Agent
|
||||
|
||||
```python
|
||||
client = AIProjectClient(
|
||||
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
|
||||
credential=DefaultAzureCredential()
|
||||
)
|
||||
|
||||
agent = client.agents.create_version(
|
||||
agent_name="my-hosted-agent",
|
||||
definition=ImageBasedHostedAgentDefinition(
|
||||
container_protocol_versions=[
|
||||
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
|
||||
],
|
||||
cpu="1",
|
||||
memory="2Gi",
|
||||
image="myregistry.azurecr.io/my-agent:latest",
|
||||
tools=[{"type": "code_interpreter"}],
|
||||
environment_variables={
|
||||
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
|
||||
"MODEL_NAME": "gpt-4o-mini"
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
print(f"Created agent: {agent.name} (version: {agent.version})")
|
||||
```
|
||||
|
||||
### 3. List Agent Versions
|
||||
|
||||
```python
|
||||
versions = client.agents.list_versions(agent_name="my-hosted-agent")
|
||||
for version in versions:
|
||||
print(f"Version: {version.version}, State: {version.state}")
|
||||
```
|
||||
|
||||
### 4. Delete Agent Version
|
||||
|
||||
```python
|
||||
client.agents.delete_version(
|
||||
agent_name="my-hosted-agent",
|
||||
version=agent.version
|
||||
)
|
||||
```
|
||||
|
||||
## ImageBasedHostedAgentDefinition Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `container_protocol_versions` | `list[ProtocolVersionRecord]` | Yes | Protocol versions the agent supports |
|
||||
| `image` | `str` | Yes | Full container image path (registry/image:tag) |
|
||||
| `cpu` | `str` | No | CPU allocation (e.g., "1", "2") |
|
||||
| `memory` | `str` | No | Memory allocation (e.g., "2Gi", "4Gi") |
|
||||
| `tools` | `list[dict]` | No | Tools available to the agent |
|
||||
| `environment_variables` | `dict[str, str]` | No | Environment variables for the container |
|
||||
|
||||
## Protocol Versions
|
||||
|
||||
The `container_protocol_versions` parameter specifies which protocols your agent supports:
|
||||
|
||||
```python
|
||||
from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol
|
||||
|
||||
# RESPONSES protocol - standard agent responses
|
||||
container_protocol_versions=[
|
||||
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
|
||||
]
|
||||
```
|
||||
|
||||
**Available Protocols:**
|
||||
| Protocol | Description |
|
||||
|----------|-------------|
|
||||
| `AgentProtocol.RESPONSES` | Standard response protocol for agent interactions |
|
||||
|
||||
## Resource Allocation
|
||||
|
||||
Specify CPU and memory for your container:
|
||||
|
||||
```python
|
||||
definition=ImageBasedHostedAgentDefinition(
|
||||
container_protocol_versions=[...],
|
||||
image="myregistry.azurecr.io/my-agent:latest",
|
||||
cpu="2", # 2 CPU cores
|
||||
memory="4Gi" # 4 GiB memory
|
||||
)
|
||||
```
|
||||
|
||||
**Resource Limits:**
|
||||
| Resource | Min | Max | Default |
|
||||
|----------|-----|-----|---------|
|
||||
| CPU | 0.5 | 4 | 1 |
|
||||
| Memory | 1Gi | 8Gi | 2Gi |
|
||||
|
||||
## Tools Configuration
|
||||
|
||||
Add tools to your hosted agent:
|
||||
|
||||
### Code Interpreter
|
||||
|
||||
```python
|
||||
tools=[{"type": "code_interpreter"}]
|
||||
```
|
||||
|
||||
### MCP Tools
|
||||
|
||||
```python
|
||||
tools=[
|
||||
{"type": "code_interpreter"},
|
||||
{
|
||||
"type": "mcp",
|
||||
"server_label": "my-mcp-server",
|
||||
"server_url": "https://my-mcp-server.example.com"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Multiple Tools
|
||||
|
||||
```python
|
||||
tools=[
|
||||
{"type": "code_interpreter"},
|
||||
{"type": "file_search"},
|
||||
{
|
||||
"type": "mcp",
|
||||
"server_label": "custom-tool",
|
||||
"server_url": "https://custom-tool.example.com"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Pass configuration to your container:
|
||||
|
||||
```python
|
||||
environment_variables={
|
||||
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
|
||||
"MODEL_NAME": "gpt-4o-mini",
|
||||
"LOG_LEVEL": "INFO",
|
||||
"CUSTOM_CONFIG": "value"
|
||||
}
|
||||
```
|
||||
|
||||
**Best Practice:** Never hardcode secrets. Use environment variables or Azure Key Vault.
|
||||
|
||||
## Complete Example
|
||||
|
||||
```python
|
||||
import os
|
||||
from azure.identity import DefaultAzureCredential
|
||||
from azure.ai.projects import AIProjectClient
|
||||
from azure.ai.projects.models import (
|
||||
ImageBasedHostedAgentDefinition,
|
||||
ProtocolVersionRecord,
|
||||
AgentProtocol,
|
||||
)
|
||||
|
||||
def create_hosted_agent():
|
||||
"""Create a hosted agent with custom container image."""
|
||||
|
||||
client = AIProjectClient(
|
||||
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
|
||||
credential=DefaultAzureCredential()
|
||||
)
|
||||
|
||||
agent = client.agents.create_version(
|
||||
agent_name="data-processor-agent",
|
||||
definition=ImageBasedHostedAgentDefinition(
|
||||
container_protocol_versions=[
|
||||
ProtocolVersionRecord(
|
||||
protocol=AgentProtocol.RESPONSES,
|
||||
version="v1"
|
||||
)
|
||||
],
|
||||
image="myregistry.azurecr.io/data-processor:v1.0",
|
||||
cpu="2",
|
||||
memory="4Gi",
|
||||
tools=[
|
||||
{"type": "code_interpreter"},
|
||||
{"type": "file_search"}
|
||||
],
|
||||
environment_variables={
|
||||
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
|
||||
"MODEL_NAME": "gpt-4o-mini",
|
||||
"MAX_RETRIES": "3"
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
print(f"Created hosted agent: {agent.name}")
|
||||
print(f"Version: {agent.version}")
|
||||
print(f"State: {agent.state}")
|
||||
|
||||
return agent
|
||||
|
||||
if __name__ == "__main__":
|
||||
create_hosted_agent()
|
||||
```
|
||||
|
||||
## Async Pattern
|
||||
|
||||
```python
|
||||
import os
|
||||
from azure.identity.aio import DefaultAzureCredential
|
||||
from azure.ai.projects.aio import AIProjectClient
|
||||
from azure.ai.projects.models import (
|
||||
ImageBasedHostedAgentDefinition,
|
||||
ProtocolVersionRecord,
|
||||
AgentProtocol,
|
||||
)
|
||||
|
||||
async def create_hosted_agent_async():
|
||||
"""Create a hosted agent asynchronously."""
|
||||
|
||||
async with DefaultAzureCredential() as credential:
|
||||
async with AIProjectClient(
|
||||
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
|
||||
credential=credential
|
||||
) as client:
|
||||
agent = await client.agents.create_version(
|
||||
agent_name="async-agent",
|
||||
definition=ImageBasedHostedAgentDefinition(
|
||||
container_protocol_versions=[
|
||||
ProtocolVersionRecord(
|
||||
protocol=AgentProtocol.RESPONSES,
|
||||
version="v1"
|
||||
)
|
||||
],
|
||||
image="myregistry.azurecr.io/async-agent:latest",
|
||||
cpu="1",
|
||||
memory="2Gi"
|
||||
)
|
||||
)
|
||||
return agent
|
||||
```
|
||||
|
||||
## Common Errors
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| `ImagePullBackOff` | ACR pull permission denied | Grant `AcrPull` role to project's managed identity |
|
||||
| `InvalidContainerImage` | Image not found | Verify image path and tag exist in ACR |
|
||||
| `CapabilityHostNotFound` | No capability host configured | Create account-level capability host |
|
||||
| `ProtocolVersionNotSupported` | Invalid protocol version | Use `AgentProtocol.RESPONSES` with version `"v1"` |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Version Your Images** - Use specific tags, not `latest` in production
|
||||
2. **Minimal Resources** - Start with minimum CPU/memory, scale up as needed
|
||||
3. **Environment Variables** - Use for all configuration, never hardcode
|
||||
4. **Error Handling** - Wrap agent creation in try/except blocks
|
||||
5. **Cleanup** - Delete unused agent versions to free resources
|
||||
|
||||
## Reference Links
|
||||
|
||||
- [Azure AI Projects SDK](https://pypi.org/project/azure-ai-projects/)
|
||||
- [Hosted Agents Documentation](https://learn.microsoft.com/azure/ai-services/agents/how-to/hosted-agents)
|
||||
- [Azure Container Registry](https://learn.microsoft.com/azure/container-registry/)
|
||||
303
skills/mcp-builder-ms/SKILL.md
Normal file
303
skills/mcp-builder-ms/SKILL.md
Normal file
@@ -0,0 +1,303 @@
|
||||
---
|
||||
name: mcp-builder
|
||||
description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP), Node/TypeScript (MCP SDK), or C#/.NET (Microsoft MCP SDK).
|
||||
---
|
||||
|
||||
# MCP Server Development Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.
|
||||
|
||||
---
|
||||
|
||||
## Microsoft MCP Ecosystem
|
||||
|
||||
Microsoft provides extensive MCP infrastructure for Azure and Foundry services. Understanding this ecosystem helps you decide whether to build custom servers or leverage existing ones.
|
||||
|
||||
### Server Types
|
||||
|
||||
| Type | Transport | Use Case | Example |
|
||||
|------|-----------|----------|---------|
|
||||
| **Local** | stdio | Desktop apps, single-user, local dev | Azure MCP Server via NPM/Docker |
|
||||
| **Remote** | Streamable HTTP | Cloud services, multi-tenant, Agent Service | `https://mcp.ai.azure.com` (Foundry) |
|
||||
|
||||
### Microsoft MCP Servers
|
||||
|
||||
Before building a custom server, check if Microsoft already provides one:
|
||||
|
||||
| Server | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| **Azure MCP** | Local | 48+ Azure services (Storage, KeyVault, Cosmos, SQL, etc.) |
|
||||
| **Foundry MCP** | Remote | `https://mcp.ai.azure.com` - Models, deployments, evals, agents |
|
||||
| **Fabric MCP** | Local | Microsoft Fabric APIs, OneLake, item definitions |
|
||||
| **Playwright MCP** | Local | Browser automation and testing |
|
||||
| **GitHub MCP** | Remote | `https://api.githubcopilot.com/mcp` |
|
||||
|
||||
**Full ecosystem:** See [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) for complete server catalog and patterns.
|
||||
|
||||
### When to Use Microsoft vs Custom
|
||||
|
||||
| Scenario | Recommendation |
|
||||
|----------|----------------|
|
||||
| Azure service integration | Use **Azure MCP Server** (48 services covered) |
|
||||
| AI Foundry agents/evals | Use **Foundry MCP** remote server |
|
||||
| Custom internal APIs | Build **custom server** (this guide) |
|
||||
| Third-party SaaS integration | Build **custom server** (this guide) |
|
||||
| Extending Azure MCP | Follow [Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md)
|
||||
|
||||
---
|
||||
|
||||
# Process
|
||||
|
||||
## 🚀 High-Level Workflow
|
||||
|
||||
Creating a high-quality MCP server involves four main phases:
|
||||
|
||||
### Phase 1: Deep Research and Planning
|
||||
|
||||
#### 1.1 Understand Modern MCP Design
|
||||
|
||||
**API Coverage vs. Workflow Tools:**
|
||||
Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools can be more convenient for specific tasks, while comprehensive coverage gives agents flexibility to compose operations. Performance varies by client—some clients benefit from code execution that combines basic tools, while others work better with higher-level workflows. When uncertain, prioritize comprehensive API coverage.
|
||||
|
||||
**Tool Naming and Discoverability:**
|
||||
Clear, descriptive tool names help agents find the right tools quickly. Use consistent prefixes (e.g., `github_create_issue`, `github_list_repos`) and action-oriented naming.
|
||||
|
||||
**Context Management:**
|
||||
Agents benefit from concise tool descriptions and the ability to filter/paginate results. Design tools that return focused, relevant data. Some clients support code execution which can help agents filter and process data efficiently.
|
||||
|
||||
**Actionable Error Messages:**
|
||||
Error messages should guide agents toward solutions with specific suggestions and next steps.
|
||||
|
||||
#### 1.2 Study MCP Protocol Documentation
|
||||
|
||||
**Navigate the MCP specification:**
|
||||
|
||||
Start with the sitemap to find relevant pages: `https://modelcontextprotocol.io/sitemap.xml`
|
||||
|
||||
Then fetch specific pages with `.md` suffix for markdown format (e.g., `https://modelcontextprotocol.io/specification/draft.md`).
|
||||
|
||||
Key pages to review:
|
||||
- Specification overview and architecture
|
||||
- Transport mechanisms (streamable HTTP, stdio)
|
||||
- Tool, resource, and prompt definitions
|
||||
|
||||
#### 1.3 Study Framework Documentation
|
||||
|
||||
**Language Selection:**
|
||||
|
||||
| Language | Best For | SDK |
|
||||
|----------|----------|-----|
|
||||
| **TypeScript** (recommended) | General MCP servers, broad compatibility | `@modelcontextprotocol/sdk` |
|
||||
| **Python** | Data/ML pipelines, FastAPI integration | `mcp` (FastMCP) |
|
||||
| **C#/.NET** | Azure/Microsoft ecosystem, enterprise | `Microsoft.Mcp.Core` |
|
||||
|
||||
**Transport Selection:**
|
||||
|
||||
| Transport | Use Case | Characteristics |
|
||||
|-----------|----------|-----------------|
|
||||
| **Streamable HTTP** | Remote servers, multi-tenant, Agent Service | Stateless, scalable, requires auth |
|
||||
| **stdio** | Local servers, desktop apps | Simple, single-user, no network |
|
||||
|
||||
**Load framework documentation:**
|
||||
|
||||
- **MCP Best Practices**: [📋 View Best Practices](./reference/mcp_best_practices.md) - Core guidelines
|
||||
|
||||
**For TypeScript (recommended):**
|
||||
- **TypeScript SDK**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
|
||||
- [⚡ TypeScript Guide](./reference/node_mcp_server.md) - TypeScript patterns and examples
|
||||
|
||||
**For Python:**
|
||||
- **Python SDK**: Use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
|
||||
- [🐍 Python Guide](./reference/python_mcp_server.md) - Python patterns and examples
|
||||
|
||||
**For C#/.NET (Microsoft ecosystem):**
|
||||
- [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) - C# patterns, Azure MCP architecture, command hierarchy
|
||||
|
||||
#### 1.4 Plan Your Implementation
|
||||
|
||||
**Understand the API:**
|
||||
Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.
|
||||
|
||||
**Tool Selection:**
|
||||
Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Implementation
|
||||
|
||||
#### 2.1 Set Up Project Structure
|
||||
|
||||
See language-specific guides for project setup:
|
||||
- [⚡ TypeScript Guide](./reference/node_mcp_server.md) - Project structure, package.json, tsconfig.json
|
||||
- [🐍 Python Guide](./reference/python_mcp_server.md) - Module organization, dependencies
|
||||
- [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) - C# project structure, command hierarchy
|
||||
|
||||
#### 2.2 Implement Core Infrastructure
|
||||
|
||||
Create shared utilities:
|
||||
- API client with authentication
|
||||
- Error handling helpers
|
||||
- Response formatting (JSON/Markdown)
|
||||
- Pagination support
|
||||
|
||||
#### 2.3 Implement Tools
|
||||
|
||||
For each tool:
|
||||
|
||||
**Input Schema:**
|
||||
- Use Zod (TypeScript) or Pydantic (Python)
|
||||
- Include constraints and clear descriptions
|
||||
- Add examples in field descriptions
|
||||
|
||||
**Output Schema:**
|
||||
- Define `outputSchema` where possible for structured data
|
||||
- Use `structuredContent` in tool responses (TypeScript SDK feature)
|
||||
- Helps clients understand and process tool outputs
|
||||
|
||||
**Tool Description:**
|
||||
- Concise summary of functionality
|
||||
- Parameter descriptions
|
||||
- Return type schema
|
||||
|
||||
**Implementation:**
|
||||
- Async/await for I/O operations
|
||||
- Proper error handling with actionable messages
|
||||
- Support pagination where applicable
|
||||
- Return both text content and structured data when using modern SDKs
|
||||
|
||||
**Annotations:**
|
||||
- `readOnlyHint`: true/false
|
||||
- `destructiveHint`: true/false
|
||||
- `idempotentHint`: true/false
|
||||
- `openWorldHint`: true/false
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Review and Test
|
||||
|
||||
#### 3.1 Code Quality
|
||||
|
||||
Review for:
|
||||
- No duplicated code (DRY principle)
|
||||
- Consistent error handling
|
||||
- Full type coverage
|
||||
- Clear tool descriptions
|
||||
|
||||
#### 3.2 Build and Test
|
||||
|
||||
**TypeScript:**
|
||||
- Run `npm run build` to verify compilation
|
||||
- Test with MCP Inspector: `npx @modelcontextprotocol/inspector`
|
||||
|
||||
**Python:**
|
||||
- Verify syntax: `python -m py_compile your_server.py`
|
||||
- Test with MCP Inspector
|
||||
|
||||
See language-specific guides for detailed testing approaches and quality checklists.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Create Evaluations
|
||||
|
||||
After implementing your MCP server, create comprehensive evaluations to test its effectiveness.
|
||||
|
||||
**Load [✅ Evaluation Guide](./reference/evaluation.md) for complete evaluation guidelines.**
|
||||
|
||||
#### 4.1 Understand Evaluation Purpose
|
||||
|
||||
Use evaluations to test whether LLMs can effectively use your MCP server to answer realistic, complex questions.
|
||||
|
||||
#### 4.2 Create 10 Evaluation Questions
|
||||
|
||||
To create effective evaluations, follow the process outlined in the evaluation guide:
|
||||
|
||||
1. **Tool Inspection**: List available tools and understand their capabilities
|
||||
2. **Content Exploration**: Use READ-ONLY operations to explore available data
|
||||
3. **Question Generation**: Create 10 complex, realistic questions
|
||||
4. **Answer Verification**: Solve each question yourself to verify answers
|
||||
|
||||
#### 4.3 Evaluation Requirements
|
||||
|
||||
Ensure each question is:
|
||||
- **Independent**: Not dependent on other questions
|
||||
- **Read-only**: Only non-destructive operations required
|
||||
- **Complex**: Requiring multiple tool calls and deep exploration
|
||||
- **Realistic**: Based on real use cases humans would care about
|
||||
- **Verifiable**: Single, clear answer that can be verified by string comparison
|
||||
- **Stable**: Answer won't change over time
|
||||
|
||||
#### 4.4 Output Format
|
||||
|
||||
Create an XML file with this structure:
|
||||
|
||||
```xml
|
||||
<evaluation>
|
||||
<qa_pair>
|
||||
<question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
|
||||
<answer>3</answer>
|
||||
</qa_pair>
|
||||
<!-- More qa_pairs... -->
|
||||
</evaluation>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Reference Files
|
||||
|
||||
## 📚 Documentation Library
|
||||
|
||||
Load these resources as needed during development:
|
||||
|
||||
### Core MCP Documentation (Load First)
|
||||
- **MCP Protocol**: Start with sitemap at `https://modelcontextprotocol.io/sitemap.xml`, then fetch specific pages with `.md` suffix
|
||||
- [📋 MCP Best Practices](./reference/mcp_best_practices.md) - Universal MCP guidelines including:
|
||||
- Server and tool naming conventions
|
||||
- Response format guidelines (JSON vs Markdown)
|
||||
- Pagination best practices
|
||||
- Transport selection (streamable HTTP vs stdio)
|
||||
- Security and error handling standards
|
||||
|
||||
### Microsoft MCP Documentation (For Azure/Foundry)
|
||||
- [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) - Microsoft-specific patterns including:
|
||||
- Azure MCP Server architecture (48+ Azure services)
|
||||
- C#/.NET command implementation patterns
|
||||
- Remote MCP with Foundry Agent Service
|
||||
- Authentication (Entra ID, OBO flow, Managed Identity)
|
||||
- Testing infrastructure with Bicep templates
|
||||
|
||||
### SDK Documentation (Load During Phase 1/2)
|
||||
- **Python SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
|
||||
- **TypeScript SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
|
||||
- **Microsoft MCP SDK**: See [Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) for C#/.NET
|
||||
|
||||
### Language-Specific Implementation Guides (Load During Phase 2)
|
||||
- [🐍 Python Implementation Guide](./reference/python_mcp_server.md) - Complete Python/FastMCP guide with:
|
||||
- Server initialization patterns
|
||||
- Pydantic model examples
|
||||
- Tool registration with `@mcp.tool`
|
||||
- Complete working examples
|
||||
- Quality checklist
|
||||
|
||||
- [⚡ TypeScript Implementation Guide](./reference/node_mcp_server.md) - Complete TypeScript guide with:
|
||||
- Project structure
|
||||
- Zod schema patterns
|
||||
- Tool registration with `server.registerTool`
|
||||
- Complete working examples
|
||||
- Quality checklist
|
||||
|
||||
- [🔷 Microsoft MCP Patterns](./reference/microsoft_mcp_patterns.md) - Complete C#/.NET guide with:
|
||||
- Command hierarchy (BaseCommand → GlobalCommand → SubscriptionCommand)
|
||||
- Naming conventions (`{Resource}{Operation}Command`)
|
||||
- Option handling with `.AsRequired()` / `.AsOptional()`
|
||||
- Azure Functions remote MCP deployment
|
||||
- Live test patterns with Bicep
|
||||
|
||||
### Evaluation Guide (Load During Phase 4)
|
||||
- [✅ Evaluation Guide](./reference/evaluation.md) - Complete evaluation creation guide with:
|
||||
- Question creation guidelines
|
||||
- Answer verification strategies
|
||||
- XML format specifications
|
||||
- Example questions and answers
|
||||
- Running an evaluation with the provided scripts
|
||||
121
skills/podcast-generation/SKILL.md
Normal file
121
skills/podcast-generation/SKILL.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
name: podcast-generation
|
||||
description: Generate AI-powered podcast-style audio narratives using Azure OpenAI's GPT Realtime Mini model via WebSocket. Use when building text-to-speech features, audio narrative generation, podcast creation from content, or integrating with Azure OpenAI Realtime API for real audio output. Covers full-stack implementation from React frontend to Python FastAPI backend with WebSocket streaming.
|
||||
---
|
||||
|
||||
# Podcast Generation with GPT Realtime Mini
|
||||
|
||||
Generate real audio narratives from text content using Azure OpenAI's Realtime API.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Configure environment variables for Realtime API
|
||||
2. Connect via WebSocket to Azure OpenAI Realtime endpoint
|
||||
3. Send text prompt, collect PCM audio chunks + transcript
|
||||
4. Convert PCM to WAV format
|
||||
5. Return base64-encoded audio to frontend for playback
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
```env
|
||||
AZURE_OPENAI_AUDIO_API_KEY=your_realtime_api_key
|
||||
AZURE_OPENAI_AUDIO_ENDPOINT=https://your-resource.cognitiveservices.azure.com
|
||||
AZURE_OPENAI_AUDIO_DEPLOYMENT=gpt-realtime-mini
|
||||
```
|
||||
|
||||
**Note**: Endpoint should NOT include `/openai/v1/` - just the base URL.
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### Backend Audio Generation
|
||||
|
||||
```python
|
||||
from openai import AsyncOpenAI
|
||||
import base64
|
||||
|
||||
# Convert HTTPS endpoint to WebSocket URL
|
||||
ws_url = endpoint.replace("https://", "wss://") + "/openai/v1"
|
||||
|
||||
client = AsyncOpenAI(
|
||||
websocket_base_url=ws_url,
|
||||
api_key=api_key
|
||||
)
|
||||
|
||||
audio_chunks = []
|
||||
transcript_parts = []
|
||||
|
||||
async with client.realtime.connect(model="gpt-realtime-mini") as conn:
|
||||
# Configure for audio-only output
|
||||
await conn.session.update(session={
|
||||
"output_modalities": ["audio"],
|
||||
"instructions": "You are a narrator. Speak naturally."
|
||||
})
|
||||
|
||||
# Send text to narrate
|
||||
await conn.conversation.item.create(item={
|
||||
"type": "message",
|
||||
"role": "user",
|
||||
"content": [{"type": "input_text", "text": prompt}]
|
||||
})
|
||||
|
||||
await conn.response.create()
|
||||
|
||||
# Collect streaming events
|
||||
async for event in conn:
|
||||
if event.type == "response.output_audio.delta":
|
||||
audio_chunks.append(base64.b64decode(event.delta))
|
||||
elif event.type == "response.output_audio_transcript.delta":
|
||||
transcript_parts.append(event.delta)
|
||||
elif event.type == "response.done":
|
||||
break
|
||||
|
||||
# Convert PCM to WAV (see scripts/pcm_to_wav.py)
|
||||
pcm_audio = b''.join(audio_chunks)
|
||||
wav_audio = pcm_to_wav(pcm_audio, sample_rate=24000)
|
||||
```
|
||||
|
||||
### Frontend Audio Playback
|
||||
|
||||
```javascript
|
||||
// Convert base64 WAV to playable blob
|
||||
const base64ToBlob = (base64, mimeType) => {
|
||||
const bytes = atob(base64);
|
||||
const arr = new Uint8Array(bytes.length);
|
||||
for (let i = 0; i < bytes.length; i++) arr[i] = bytes.charCodeAt(i);
|
||||
return new Blob([arr], { type: mimeType });
|
||||
};
|
||||
|
||||
const audioBlob = base64ToBlob(response.audio_data, 'audio/wav');
|
||||
const audioUrl = URL.createObjectURL(audioBlob);
|
||||
new Audio(audioUrl).play();
|
||||
```
|
||||
|
||||
## Voice Options
|
||||
|
||||
| Voice | Character |
|
||||
|-------|-----------|
|
||||
| alloy | Neutral |
|
||||
| echo | Warm |
|
||||
| fable | Expressive |
|
||||
| onyx | Deep |
|
||||
| nova | Friendly |
|
||||
| shimmer | Clear |
|
||||
|
||||
## Realtime API Events
|
||||
|
||||
- `response.output_audio.delta` - Base64 audio chunk
|
||||
- `response.output_audio_transcript.delta` - Transcript text
|
||||
- `response.done` - Generation complete
|
||||
- `error` - Handle with `event.error.message`
|
||||
|
||||
## Audio Format
|
||||
|
||||
- **Input**: Text prompt
|
||||
- **Output**: PCM audio (24kHz, 16-bit, mono)
|
||||
- **Storage**: Base64-encoded WAV
|
||||
|
||||
## References
|
||||
|
||||
- **Full architecture**: See [references/architecture.md](references/architecture.md) for complete stack design
|
||||
- **Code examples**: See [references/code-examples.md](references/code-examples.md) for production patterns
|
||||
- **PCM conversion**: Use [scripts/pcm_to_wav.py](scripts/pcm_to_wav.py) for audio format conversion
|
||||
58
skills/pydantic-models-py/SKILL.md
Normal file
58
skills/pydantic-models-py/SKILL.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: pydantic-models-py
|
||||
description: Create Pydantic models following the multi-model pattern with Base, Create, Update, Response, and InDB variants. Use when defining API request/response schemas, database models, or data validation in Python applications using Pydantic v2.
|
||||
---
|
||||
|
||||
# Pydantic Models
|
||||
|
||||
Create Pydantic models following the multi-model pattern for clean API contracts.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Copy the template from [assets/template.py](assets/template.py) and replace placeholders:
|
||||
- `{{ResourceName}}` → PascalCase name (e.g., `Project`)
|
||||
- `{{resource_name}}` → snake_case name (e.g., `project`)
|
||||
|
||||
## Multi-Model Pattern
|
||||
|
||||
| Model | Purpose |
|
||||
|-------|---------|
|
||||
| `Base` | Common fields shared across models |
|
||||
| `Create` | Request body for creation (required fields) |
|
||||
| `Update` | Request body for updates (all optional) |
|
||||
| `Response` | API response with all fields |
|
||||
| `InDB` | Database document with `doc_type` |
|
||||
|
||||
## camelCase Aliases
|
||||
|
||||
```python
|
||||
class MyModel(BaseModel):
|
||||
workspace_id: str = Field(..., alias="workspaceId")
|
||||
created_at: datetime = Field(..., alias="createdAt")
|
||||
|
||||
class Config:
|
||||
populate_by_name = True # Accept both snake_case and camelCase
|
||||
```
|
||||
|
||||
## Optional Update Fields
|
||||
|
||||
```python
|
||||
class MyUpdate(BaseModel):
|
||||
"""All fields optional for PATCH requests."""
|
||||
name: Optional[str] = Field(None, min_length=1)
|
||||
description: Optional[str] = None
|
||||
```
|
||||
|
||||
## Database Document
|
||||
|
||||
```python
|
||||
class MyInDB(MyResponse):
|
||||
"""Adds doc_type for Cosmos DB queries."""
|
||||
doc_type: str = "my_resource"
|
||||
```
|
||||
|
||||
## Integration Steps
|
||||
|
||||
1. Create models in `src/backend/app/models/`
|
||||
2. Export from `src/backend/app/models/__init__.py`
|
||||
3. Add corresponding TypeScript types
|
||||
613
skills/skill-creator-ms/SKILL.md
Normal file
613
skills/skill-creator-ms/SKILL.md
Normal file
@@ -0,0 +1,613 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
Guide for creating skills that extend AI agent capabilities, with emphasis on Azure SDKs and Microsoft Foundry.
|
||||
|
||||
> **Required Context:** When creating SDK or API skills, users MUST provide the SDK package name, documentation URL, or repository reference for the skill to be based on.
|
||||
|
||||
## About Skills
|
||||
|
||||
Skills are modular knowledge packages that transform general-purpose agents into specialized experts:
|
||||
|
||||
1. **Procedural knowledge** — Multi-step workflows for specific domains
|
||||
2. **SDK expertise** — API patterns, authentication, error handling for Azure services
|
||||
3. **Domain context** — Schemas, business logic, company-specific patterns
|
||||
4. **Bundled resources** — Scripts, references, templates for complex tasks
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Concise is Key
|
||||
|
||||
The context window is a shared resource. Challenge each piece: "Does this justify its token cost?"
|
||||
|
||||
**Default assumption: Agents are already capable.** Only add what they don't already know.
|
||||
|
||||
### 2. Fresh Documentation First
|
||||
|
||||
**Azure SDKs change constantly.** Skills should instruct agents to verify documentation:
|
||||
|
||||
```markdown
|
||||
## Before Implementation
|
||||
|
||||
Search `microsoft-docs` MCP for current API patterns:
|
||||
- Query: "[SDK name] [operation] python"
|
||||
- Verify: Parameters match your installed SDK version
|
||||
```
|
||||
|
||||
### 3. Degrees of Freedom
|
||||
|
||||
Match specificity to task fragility:
|
||||
|
||||
| Freedom | When | Example |
|
||||
|---------|------|---------|
|
||||
| **High** | Multiple valid approaches | Text guidelines |
|
||||
| **Medium** | Preferred pattern with variation | Pseudocode |
|
||||
| **Low** | Must be exact | Specific scripts |
|
||||
|
||||
### 4. Progressive Disclosure
|
||||
|
||||
Skills load in three levels:
|
||||
|
||||
1. **Metadata** (~100 words) — Always in context
|
||||
2. **SKILL.md body** (<5k words) — When skill triggers
|
||||
3. **References** (unlimited) — As needed
|
||||
|
||||
**Keep SKILL.md under 500 lines.** Split into reference files when approaching this limit.
|
||||
|
||||
---
|
||||
|
||||
## Skill Structure
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required)
|
||||
│ ├── YAML frontmatter (name, description)
|
||||
│ └── Markdown instructions
|
||||
└── Bundled Resources (optional)
|
||||
├── scripts/ — Executable code
|
||||
├── references/ — Documentation loaded as needed
|
||||
└── assets/ — Output resources (templates, images)
|
||||
```
|
||||
|
||||
### SKILL.md
|
||||
|
||||
- **Frontmatter**: `name` and `description`. The description is the trigger mechanism.
|
||||
- **Body**: Instructions loaded only after triggering.
|
||||
|
||||
### Bundled Resources
|
||||
|
||||
| Type | Purpose | When to Include |
|
||||
|------|---------|-----------------|
|
||||
| `scripts/` | Deterministic operations | Same code rewritten repeatedly |
|
||||
| `references/` | Detailed patterns | API docs, schemas, detailed guides |
|
||||
| `assets/` | Output resources | Templates, images, boilerplate |
|
||||
|
||||
**Don't include**: README.md, CHANGELOG.md, installation guides.
|
||||
|
||||
---
|
||||
|
||||
## Creating Azure SDK Skills
|
||||
|
||||
When creating skills for Azure SDKs, follow these patterns consistently.
|
||||
|
||||
### Skill Section Order
|
||||
|
||||
Follow this structure (based on existing Azure SDK skills):
|
||||
|
||||
1. **Title** — `# SDK Name`
|
||||
2. **Installation** — `pip install`, `npm install`, etc.
|
||||
3. **Environment Variables** — Required configuration
|
||||
4. **Authentication** — Always `DefaultAzureCredential`
|
||||
5. **Core Workflow** — Minimal viable example
|
||||
6. **Feature Tables** — Clients, methods, tools
|
||||
7. **Best Practices** — Numbered list
|
||||
8. **Reference Links** — Table linking to `/references/*.md`
|
||||
|
||||
### Authentication Pattern (All Languages)
|
||||
|
||||
Always use `DefaultAzureCredential`:
|
||||
|
||||
```python
|
||||
# Python
|
||||
from azure.identity import DefaultAzureCredential
|
||||
credential = DefaultAzureCredential()
|
||||
client = ServiceClient(endpoint, credential)
|
||||
```
|
||||
|
||||
```csharp
|
||||
// C#
|
||||
var credential = new DefaultAzureCredential();
|
||||
var client = new ServiceClient(new Uri(endpoint), credential);
|
||||
```
|
||||
|
||||
```java
|
||||
// Java
|
||||
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
|
||||
ServiceClient client = new ServiceClientBuilder()
|
||||
.endpoint(endpoint)
|
||||
.credential(credential)
|
||||
.buildClient();
|
||||
```
|
||||
|
||||
```typescript
|
||||
// TypeScript
|
||||
import { DefaultAzureCredential } from "@azure/identity";
|
||||
const credential = new DefaultAzureCredential();
|
||||
const client = new ServiceClient(endpoint, credential);
|
||||
```
|
||||
|
||||
**Never hardcode credentials. Use environment variables.**
|
||||
|
||||
### Standard Verb Patterns
|
||||
|
||||
Azure SDKs use consistent verbs across all languages:
|
||||
|
||||
| Verb | Behavior |
|
||||
|------|----------|
|
||||
| `create` | Create new; fail if exists |
|
||||
| `upsert` | Create or update |
|
||||
| `get` | Retrieve; error if missing |
|
||||
| `list` | Return collection |
|
||||
| `delete` | Succeed even if missing |
|
||||
| `begin` | Start long-running operation |
|
||||
|
||||
### Language-Specific Patterns
|
||||
|
||||
See `references/azure-sdk-patterns.md` for detailed patterns including:
|
||||
|
||||
- **Python**: `ItemPaged`, `LROPoller`, context managers, Sphinx docstrings
|
||||
- **.NET**: `Response<T>`, `Pageable<T>`, `Operation<T>`, mocking support
|
||||
- **Java**: Builder pattern, `PagedIterable`/`PagedFlux`, Reactor types
|
||||
- **TypeScript**: `PagedAsyncIterableIterator`, `AbortSignal`, browser considerations
|
||||
|
||||
### Example: Azure SDK Skill Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-creator
|
||||
description: |
|
||||
Azure AI Example SDK for Python. Use for [specific service features].
|
||||
Triggers: "example service", "create example", "list examples".
|
||||
---
|
||||
|
||||
# Azure AI Example SDK
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`bash
|
||||
pip install azure-ai-example
|
||||
\`\`\`
|
||||
|
||||
## Environment Variables
|
||||
|
||||
\`\`\`bash
|
||||
AZURE_EXAMPLE_ENDPOINT=https://<resource>.example.azure.com
|
||||
\`\`\`
|
||||
|
||||
## Authentication
|
||||
|
||||
\`\`\`python
|
||||
from azure.identity import DefaultAzureCredential
|
||||
from azure.ai.example import ExampleClient
|
||||
|
||||
credential = DefaultAzureCredential()
|
||||
client = ExampleClient(
|
||||
endpoint=os.environ["AZURE_EXAMPLE_ENDPOINT"],
|
||||
credential=credential
|
||||
)
|
||||
\`\`\`
|
||||
|
||||
## Core Workflow
|
||||
|
||||
\`\`\`python
|
||||
# Create
|
||||
item = client.create_item(name="example", data={...})
|
||||
|
||||
# List (pagination handled automatically)
|
||||
for item in client.list_items():
|
||||
print(item.name)
|
||||
|
||||
# Long-running operation
|
||||
poller = client.begin_process(item_id)
|
||||
result = poller.result()
|
||||
|
||||
# Cleanup
|
||||
client.delete_item(item_id)
|
||||
\`\`\`
|
||||
|
||||
## Reference Files
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| [references/tools.md](references/tools.md) | Tool integrations |
|
||||
| [references/streaming.md](references/streaming.md) | Event streaming patterns |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill Creation Process
|
||||
|
||||
1. **Gather SDK Context** — User provides SDK/API reference (REQUIRED)
|
||||
2. **Understand** — Research SDK patterns from official docs
|
||||
3. **Plan** — Identify reusable resources and product area category
|
||||
4. **Create** — Write SKILL.md in `.github/skills/<skill-name>/`
|
||||
5. **Categorize** — Create symlink in `skills/<language>/<category>/`
|
||||
6. **Test** — Create acceptance criteria and test scenarios
|
||||
7. **Document** — Update README.md skill catalog
|
||||
8. **Iterate** — Refine based on real usage
|
||||
|
||||
### Step 1: Gather SDK Context (REQUIRED)
|
||||
|
||||
**Before creating any SDK skill, the user MUST provide:**
|
||||
|
||||
| Required | Example | Purpose |
|
||||
|----------|---------|---------|
|
||||
| **SDK Package** | `azure-ai-agents`, `Azure.AI.OpenAI` | Identifies the exact SDK |
|
||||
| **Documentation URL** | `https://learn.microsoft.com/en-us/azure/ai-services/...` | Primary source of truth |
|
||||
| **Repository** (optional) | `Azure/azure-sdk-for-python` | For code patterns |
|
||||
|
||||
**Prompt the user if not provided:**
|
||||
```
|
||||
To create this skill, I need:
|
||||
1. The SDK package name (e.g., azure-ai-projects)
|
||||
2. The Microsoft Learn documentation URL or GitHub repo
|
||||
3. The target language (py/dotnet/ts/java)
|
||||
```
|
||||
|
||||
**Search official docs first:**
|
||||
```bash
|
||||
# Use microsoft-docs MCP to get current API patterns
|
||||
# Query: "[SDK name] [operation] [language]"
|
||||
# Verify: Parameters match the latest SDK version
|
||||
```
|
||||
|
||||
### Step 2: Understand the Skill
|
||||
|
||||
Gather concrete examples:
|
||||
|
||||
- "What SDK operations should this skill cover?"
|
||||
- "What triggers should activate this skill?"
|
||||
- "What errors do developers commonly encounter?"
|
||||
|
||||
| Example Task | Reusable Resource |
|
||||
|--------------|-------------------|
|
||||
| Same auth code each time | Code example in SKILL.md |
|
||||
| Complex streaming patterns | `references/streaming.md` |
|
||||
| Tool configurations | `references/tools.md` |
|
||||
| Error handling patterns | `references/error-handling.md` |
|
||||
|
||||
### Step 3: Plan Product Area Category
|
||||
|
||||
Skills are organized by **language** and **product area** in the `skills/` directory via symlinks.
|
||||
|
||||
**Product Area Categories:**
|
||||
|
||||
| Category | Description | Examples |
|
||||
|----------|-------------|----------|
|
||||
| `foundry` | AI Foundry, agents, projects, inference | `azure-ai-agents-py`, `azure-ai-projects-py` |
|
||||
| `data` | Storage, Cosmos DB, Tables, Data Lake | `azure-cosmos-py`, `azure-storage-blob-py` |
|
||||
| `messaging` | Event Hubs, Service Bus, Event Grid | `azure-eventhub-py`, `azure-servicebus-py` |
|
||||
| `monitoring` | OpenTelemetry, App Insights, Query | `azure-monitor-opentelemetry-py` |
|
||||
| `identity` | Authentication, DefaultAzureCredential | `azure-identity-py` |
|
||||
| `security` | Key Vault, secrets, keys, certificates | `azure-keyvault-py` |
|
||||
| `integration` | API Management, App Configuration | `azure-appconfiguration-py` |
|
||||
| `compute` | Batch, ML compute | `azure-compute-batch-java` |
|
||||
| `container` | Container Registry, ACR | `azure-containerregistry-py` |
|
||||
|
||||
**Determine the category** based on:
|
||||
1. Azure service family (Storage → `data`, Event Hubs → `messaging`)
|
||||
2. Primary use case (AI agents → `foundry`)
|
||||
3. Existing skills in the same service area
|
||||
|
||||
### Step 4: Create the Skill
|
||||
|
||||
**Location:** `.github/skills/<skill-name>/SKILL.md`
|
||||
|
||||
**Naming convention:**
|
||||
- `azure-<service>-<subservice>-<language>`
|
||||
- Examples: `azure-ai-agents-py`, `azure-cosmos-java`, `azure-storage-blob-ts`
|
||||
|
||||
**For Azure SDK skills:**
|
||||
|
||||
1. Search `microsoft-docs` MCP for current API patterns
|
||||
2. Verify against installed SDK version
|
||||
3. Follow the section order above
|
||||
4. Include cleanup code in examples
|
||||
5. Add feature comparison tables
|
||||
|
||||
**Write bundled resources first**, then SKILL.md.
|
||||
|
||||
**Frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name-py
|
||||
description: |
|
||||
Azure Service SDK for Python. Use for [specific features].
|
||||
Triggers: "service name", "create resource", "specific operation".
|
||||
---
|
||||
```
|
||||
|
||||
### Step 5: Categorize with Symlinks
|
||||
|
||||
After creating the skill in `.github/skills/`, create a symlink in the appropriate category:
|
||||
|
||||
```bash
|
||||
# Pattern: skills/<language>/<category>/<short-name> -> ../../../.github/skills/<full-skill-name>
|
||||
|
||||
# Example for azure-ai-agents-py in python/foundry:
|
||||
cd skills/python/foundry
|
||||
ln -s ../../../.github/skills/azure-ai-agents-py agents
|
||||
|
||||
# Example for azure-cosmos-db-py in python/data:
|
||||
cd skills/python/data
|
||||
ln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db
|
||||
```
|
||||
|
||||
**Symlink naming:**
|
||||
- Use short, descriptive names (e.g., `agents`, `cosmos`, `blob`)
|
||||
- Remove the `azure-` prefix and language suffix
|
||||
- Match existing patterns in the category
|
||||
|
||||
**Verify the symlink:**
|
||||
```bash
|
||||
ls -la skills/python/foundry/agents
|
||||
# Should show: agents -> ../../../.github/skills/azure-ai-agents-py
|
||||
```
|
||||
|
||||
### Step 6: Create Tests
|
||||
|
||||
**Every skill MUST have acceptance criteria and test scenarios.**
|
||||
|
||||
#### 6.1 Create Acceptance Criteria
|
||||
|
||||
**Location:** `.github/skills/<skill-name>/references/acceptance-criteria.md`
|
||||
|
||||
**Source materials** (in priority order):
|
||||
1. Official Microsoft Learn docs (via `microsoft-docs` MCP)
|
||||
2. SDK source code from the repository
|
||||
3. Existing reference files in the skill
|
||||
|
||||
**Format:**
|
||||
```markdown
|
||||
# Acceptance Criteria: <skill-name>
|
||||
|
||||
**SDK**: `package-name`
|
||||
**Repository**: https://github.com/Azure/azure-sdk-for-<language>
|
||||
**Purpose**: Skill testing acceptance criteria
|
||||
|
||||
---
|
||||
|
||||
## 1. Correct Import Patterns
|
||||
|
||||
### 1.1 Client Imports
|
||||
|
||||
#### ✅ CORRECT: Main Client
|
||||
\`\`\`python
|
||||
from azure.ai.mymodule import MyClient
|
||||
from azure.identity import DefaultAzureCredential
|
||||
\`\`\`
|
||||
|
||||
#### ❌ INCORRECT: Wrong Module Path
|
||||
\`\`\`python
|
||||
from azure.ai.mymodule.models import MyClient # Wrong - Client is not in models
|
||||
\`\`\`
|
||||
|
||||
## 2. Authentication Patterns
|
||||
|
||||
#### ✅ CORRECT: DefaultAzureCredential
|
||||
\`\`\`python
|
||||
credential = DefaultAzureCredential()
|
||||
client = MyClient(endpoint, credential)
|
||||
\`\`\`
|
||||
|
||||
#### ❌ INCORRECT: Hardcoded Credentials
|
||||
\`\`\`python
|
||||
client = MyClient(endpoint, api_key="hardcoded") # Security risk
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
**Critical patterns to document:**
|
||||
- Import paths (these vary significantly between Azure SDKs)
|
||||
- Authentication patterns
|
||||
- Client initialization
|
||||
- Async variants (`.aio` modules)
|
||||
- Common anti-patterns
|
||||
|
||||
#### 6.2 Create Test Scenarios
|
||||
|
||||
**Location:** `tests/scenarios/<skill-name>/scenarios.yaml`
|
||||
|
||||
```yaml
|
||||
config:
|
||||
model: gpt-4
|
||||
max_tokens: 2000
|
||||
temperature: 0.3
|
||||
|
||||
scenarios:
|
||||
- name: basic_client_creation
|
||||
prompt: |
|
||||
Create a basic example using the Azure SDK.
|
||||
Include proper authentication and client initialization.
|
||||
expected_patterns:
|
||||
- "DefaultAzureCredential"
|
||||
- "MyClient"
|
||||
forbidden_patterns:
|
||||
- "api_key="
|
||||
- "hardcoded"
|
||||
tags:
|
||||
- basic
|
||||
- authentication
|
||||
mock_response: |
|
||||
import os
|
||||
from azure.identity import DefaultAzureCredential
|
||||
from azure.ai.mymodule import MyClient
|
||||
|
||||
credential = DefaultAzureCredential()
|
||||
client = MyClient(
|
||||
endpoint=os.environ["AZURE_ENDPOINT"],
|
||||
credential=credential
|
||||
)
|
||||
# ... rest of working example
|
||||
```
|
||||
|
||||
**Scenario design principles:**
|
||||
- Each scenario tests ONE specific pattern or feature
|
||||
- `expected_patterns` — patterns that MUST appear
|
||||
- `forbidden_patterns` — common mistakes that must NOT appear
|
||||
- `mock_response` — complete, working code that passes all checks
|
||||
- `tags` — for filtering (`basic`, `async`, `streaming`, `tools`)
|
||||
|
||||
#### 6.3 Run Tests
|
||||
|
||||
```bash
|
||||
cd tests
|
||||
pnpm install
|
||||
|
||||
# Check skill is discovered
|
||||
pnpm harness --list
|
||||
|
||||
# Run in mock mode (fast, deterministic)
|
||||
pnpm harness <skill-name> --mock --verbose
|
||||
|
||||
# Run with Ralph Loop (iterative improvement)
|
||||
pnpm harness <skill-name> --ralph --mock --max-iterations 5 --threshold 85
|
||||
```
|
||||
|
||||
**Success criteria:**
|
||||
- All scenarios pass (100% pass rate)
|
||||
- No false positives (mock responses always pass)
|
||||
- Patterns catch real mistakes
|
||||
|
||||
### Step 7: Update Documentation
|
||||
|
||||
After creating the skill:
|
||||
|
||||
1. **Update README.md** — Add the skill to the appropriate language section in the Skill Catalog
|
||||
- Update total skill count (line ~73: `> N skills in...`)
|
||||
- Update Skill Explorer link count (line ~15: `Browse all N skills`)
|
||||
- Update language count table (lines ~77-83)
|
||||
- Update language section count (e.g., `> N skills • suffix: -py`)
|
||||
- Update category count (e.g., `<summary><strong>Foundry & AI</strong> (N skills)</summary>`)
|
||||
- Add skill row in alphabetical order within its category
|
||||
- Update test coverage summary (line ~622: `**N skills with N test scenarios**`)
|
||||
- Update test coverage table — update skill count, scenario count, and top skills for the language
|
||||
|
||||
2. **Regenerate GitHub Pages data** — Run the extraction script to update the docs site
|
||||
```bash
|
||||
cd docs-site && npx tsx scripts/extract-skills.ts
|
||||
```
|
||||
This updates `docs-site/src/data/skills.json` which feeds the Astro-based docs site.
|
||||
Then rebuild the docs site:
|
||||
```bash
|
||||
cd docs-site && npm run build
|
||||
```
|
||||
This outputs to `docs/` which is served by GitHub Pages.
|
||||
|
||||
3. **Verify AGENTS.md** — Ensure the skill count is accurate
|
||||
|
||||
---
|
||||
|
||||
## Progressive Disclosure Patterns
|
||||
|
||||
### Pattern 1: High-Level Guide with References
|
||||
|
||||
```markdown
|
||||
# SDK Name
|
||||
|
||||
## Quick Start
|
||||
[Minimal example]
|
||||
|
||||
## Advanced Features
|
||||
- **Streaming**: See [references/streaming.md](references/streaming.md)
|
||||
- **Tools**: See [references/tools.md](references/tools.md)
|
||||
```
|
||||
|
||||
### Pattern 2: Language Variants
|
||||
|
||||
```
|
||||
azure-service-skill/
|
||||
├── SKILL.md (overview + language selection)
|
||||
└── references/
|
||||
├── python.md
|
||||
├── dotnet.md
|
||||
├── java.md
|
||||
└── typescript.md
|
||||
```
|
||||
|
||||
### Pattern 3: Feature Organization
|
||||
|
||||
```
|
||||
azure-ai-agents/
|
||||
├── SKILL.md (core workflow)
|
||||
└── references/
|
||||
├── tools.md
|
||||
├── streaming.md
|
||||
├── async-patterns.md
|
||||
└── error-handling.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design Pattern References
|
||||
|
||||
| Reference | Contents |
|
||||
|-----------|----------|
|
||||
| `references/workflows.md` | Sequential and conditional workflows |
|
||||
| `references/output-patterns.md` | Templates and examples |
|
||||
| `references/azure-sdk-patterns.md` | Language-specific Azure SDK patterns |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
| Don't | Why |
|
||||
|-------|-----|
|
||||
| Create skill without SDK context | Users must provide package name/docs URL |
|
||||
| Put "when to use" in body | Body loads AFTER triggering |
|
||||
| Hardcode credentials | Security risk |
|
||||
| Skip authentication section | Agents will improvise poorly |
|
||||
| Use outdated SDK patterns | APIs change; search docs first |
|
||||
| Include README.md | Agents don't need meta-docs |
|
||||
| Deeply nest references | Keep one level deep |
|
||||
| Skip acceptance criteria | Skills without tests can't be validated |
|
||||
| Skip symlink categorization | Skills won't be discoverable by category |
|
||||
| Use wrong import paths | Azure SDKs have specific module structures |
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
Before completing a skill:
|
||||
|
||||
**Prerequisites:**
|
||||
- [ ] User provided SDK package name or documentation URL
|
||||
- [ ] Verified SDK patterns via `microsoft-docs` MCP
|
||||
|
||||
**Skill Creation:**
|
||||
- [ ] Description includes what AND when (trigger phrases)
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] Authentication uses `DefaultAzureCredential`
|
||||
- [ ] Includes cleanup/delete in examples
|
||||
- [ ] References organized by feature
|
||||
|
||||
**Categorization:**
|
||||
- [ ] Skill created in `.github/skills/<skill-name>/`
|
||||
- [ ] Symlink created in `skills/<language>/<category>/<short-name>`
|
||||
- [ ] Symlink points to `../../../.github/skills/<skill-name>`
|
||||
|
||||
**Testing:**
|
||||
- [ ] `references/acceptance-criteria.md` created with correct/incorrect patterns
|
||||
- [ ] `tests/scenarios/<skill-name>/scenarios.yaml` created
|
||||
- [ ] All scenarios pass (`pnpm harness <skill> --mock`)
|
||||
- [ ] Import paths documented precisely
|
||||
|
||||
**Documentation:**
|
||||
- [ ] README.md skill catalog updated
|
||||
- [ ] Instructs to search `microsoft-docs` MCP for current APIs
|
||||
Reference in New Issue
Block a user