diff --git a/.github/skills/agents-v2-py/SKILL.md b/.github/skills/agents-v2-py/SKILL.md new file mode 100644 index 0000000..8405a3f --- /dev/null +++ b/.github/skills/agents-v2-py/SKILL.md @@ -0,0 +1,325 @@ +--- +name: agents-v2-py +description: | + Build container-based Foundry Agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. + Use when creating hosted agents that run custom code in Azure AI Foundry with your own container images. + Triggers: "ImageBasedHostedAgentDefinition", "hosted agent", "container agent", "Foundry Agent", + "create_version", "ProtocolVersionRecord", "AgentProtocol.RESPONSES", "custom agent image". +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://.services.ai.azure.com/api/projects/ +``` + +## 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/) diff --git a/.github/skills/agents-v2-py/references/acceptance-criteria.md b/.github/skills/agents-v2-py/references/acceptance-criteria.md new file mode 100644 index 0000000..9b49b29 --- /dev/null +++ b/.github/skills/agents-v2-py/references/acceptance-criteria.md @@ -0,0 +1,486 @@ +# Acceptance Criteria: hosted-agents-v2-py + +**SDK**: `azure-ai-projects` +**Minimum Version**: `>=2.0.0b3` +**Repository**: https://github.com/Azure/azure-sdk-for-python + +--- + +## 1. Correct Import Patterns + +### 1.1 Client and Model Imports + +#### ✅ CORRECT: All imports from azure.ai.projects + +```python +from azure.identity import DefaultAzureCredential +from azure.ai.projects import AIProjectClient +from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, +) +``` + +#### ✅ CORRECT: Async imports + +```python +from azure.identity.aio import DefaultAzureCredential +from azure.ai.projects.aio import AIProjectClient +from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, +) +``` + +### 1.2 Anti-Patterns (ERRORS) + +#### ❌ INCORRECT: Importing from azure.ai.agents + +```python +# WRONG - ImageBasedHostedAgentDefinition is NOT in azure.ai.agents +from azure.ai.agents.models import ImageBasedHostedAgentDefinition +``` + +#### ❌ INCORRECT: Importing from azure.ai.agents directly + +```python +# WRONG - These models are in azure.ai.projects.models +from azure.ai.agents import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, +) +``` + +#### ❌ INCORRECT: Wrong module path for AgentProtocol + +```python +# WRONG - AgentProtocol is in azure.ai.projects.models +from azure.ai.projects import AgentProtocol +``` + +#### ❌ INCORRECT: Using AgentsClient instead of AIProjectClient + +```python +# WRONG - Hosted agents use AIProjectClient, not AgentsClient +from azure.ai.agents import AgentsClient +``` + +--- + +## 2. Client Creation Patterns + +### 2.1 Correct Client Creation + +#### ✅ CORRECT: AIProjectClient with DefaultAzureCredential + +```python +import os +from azure.identity import DefaultAzureCredential +from azure.ai.projects import AIProjectClient + +client = AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=DefaultAzureCredential() +) +``` + +#### ✅ CORRECT: Async client with context manager + +```python +import os +from azure.identity.aio import DefaultAzureCredential +from azure.ai.projects.aio import AIProjectClient + +async with DefaultAzureCredential() as credential: + async with AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=credential + ) as client: + # Use client here + pass +``` + +### 2.2 Anti-Patterns (ERRORS) + +#### ❌ INCORRECT: Using AgentsClient for hosted agents + +```python +# WRONG - Hosted agents require AIProjectClient +from azure.ai.agents import AgentsClient + +client = AgentsClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=DefaultAzureCredential() +) +``` + +#### ❌ INCORRECT: Hardcoded credentials + +```python +# WRONG - Never hardcode credentials +client = AIProjectClient( + endpoint="https://myresource.services.ai.azure.com/api/projects/myproject", + credential=DefaultAzureCredential() +) +``` + +#### ❌ INCORRECT: Missing credential + +```python +# WRONG - credential is required +client = AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"] +) +``` + +--- + +## 3. Hosted Agent Creation Patterns + +### 3.1 Correct Agent Creation + +#### ✅ CORRECT: Basic hosted agent with ImageBasedHostedAgentDefinition + +```python +from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, +) + +agent = client.agents.create_version( + agent_name="my-hosted-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/my-agent:latest" + ) +) +``` + +#### ✅ CORRECT: Agent with resource allocation + +```python +agent = client.agents.create_version( + agent_name="my-hosted-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/my-agent:latest", + cpu="2", + memory="4Gi" + ) +) +``` + +#### ✅ CORRECT: Agent with tools and environment variables + +```python +agent = client.agents.create_version( + agent_name="my-hosted-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/my-agent:latest", + cpu="1", + memory="2Gi", + tools=[{"type": "code_interpreter"}], + environment_variables={ + "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"], + "MODEL_NAME": "gpt-4o-mini" + } + ) +) +``` + +### 3.2 Anti-Patterns (ERRORS) + +#### ❌ INCORRECT: Using create_agent instead of create_version + +```python +# WRONG - Hosted agents use create_version, not create_agent +agent = client.agents.create_agent( + name="wrong-agent-example", + definition=ImageBasedHostedAgentDefinition(...) +) +``` + +#### ❌ INCORRECT: Missing container_protocol_versions + +```python +# WRONG - container_protocol_versions is required +agent = client.agents.create_version( + agent_name="missing-protocol-agent", + definition=ImageBasedHostedAgentDefinition( + image="wrong.azurecr.io/incomplete-agent:latest" + ) +) +``` + +#### ❌ INCORRECT: Missing image parameter + +```python +# WRONG - image is required for ImageBasedHostedAgentDefinition +agent = client.agents.create_version( + agent_name="missing-image-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ] + ) +) +``` + +#### ❌ INCORRECT: Using wrong protocol enum + +```python +# WRONG - Must use AgentProtocol enum, not string +agent = client.agents.create_version( + agent_name="wrong-protocol-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol="responses", version="v1") + ], + image="wrong.azurecr.io/string-protocol-agent:latest" + ) +) +``` + +#### ❌ INCORRECT: Passing model parameter (not applicable to hosted agents) + +```python +# WRONG - Hosted agents don't take model parameter in definition +agent = client.agents.create_version( + agent_name="wrong-model-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[...], + image="wrong.azurecr.io/model-param-agent:latest", + model="gpt-4o-mini" # WRONG - use environment_variables instead + ) +) +``` + +--- + +## 4. Protocol Version Patterns + +### 4.1 Correct Protocol Configuration + +#### ✅ CORRECT: RESPONSES protocol with v1 + +```python +container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") +] +``` + +### 4.2 Anti-Patterns (ERRORS) + +#### ❌ INCORRECT: Using string instead of enum + +```python +# WRONG - protocol must be AgentProtocol enum +container_protocol_versions=[ + ProtocolVersionRecord(protocol="RESPONSES", version="v1") +] +``` + +#### ❌ INCORRECT: Empty protocol versions list + +```python +# WRONG - At least one protocol version required +container_protocol_versions=[] +``` + +#### ❌ INCORRECT: Missing version parameter + +```python +# WRONG - version is required +container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES) +] +``` + +--- + +## 5. Resource Allocation Patterns + +### 5.1 Correct Resource Specification + +#### ✅ CORRECT: String format for CPU and memory + +```python +ImageBasedHostedAgentDefinition( + container_protocol_versions=[...], + image="...", + cpu="1", # String format + memory="2Gi" # String format with unit +) +``` + +#### ✅ CORRECT: Higher resource allocation + +```python +ImageBasedHostedAgentDefinition( + container_protocol_versions=[...], + image="...", + cpu="4", + memory="8Gi" +) +``` + +### 5.2 Anti-Patterns (ERRORS) + +#### ❌ INCORRECT: Numeric values instead of strings + +```python +# WRONG - cpu and memory must be strings +ImageBasedHostedAgentDefinition( + container_protocol_versions=[...], + image="...", + cpu=1, # WRONG - must be string "1" + memory=2048 # WRONG - must be string "2Gi" +) +``` + +#### ❌ INCORRECT: Missing unit for memory + +```python +# WRONG - memory needs unit suffix (Gi, Mi) +ImageBasedHostedAgentDefinition( + container_protocol_versions=[...], + image="...", + memory="2" # WRONG - should be "2Gi" +) +``` + +--- + +## 6. Tools Configuration Patterns + +### 6.1 Correct Tools Specification + +#### ✅ CORRECT: Code interpreter tool + +```python +tools=[{"type": "code_interpreter"}] +``` + +#### ✅ CORRECT: Multiple tools + +```python +tools=[ + {"type": "code_interpreter"}, + {"type": "file_search"} +] +``` + +#### ✅ CORRECT: MCP tool with server configuration + +```python +tools=[ + { + "type": "mcp", + "server_label": "my-mcp-server", + "server_url": "https://my-mcp-server.example.com" + } +] +``` + +### 6.2 Anti-Patterns (ERRORS) + +#### ❌ INCORRECT: Using CodeInterpreterTool class + +```python +# WRONG - tools should be dict format for hosted agents +from azure.ai.agents.models import CodeInterpreterTool + +tools=[CodeInterpreterTool()] # WRONG for hosted agents +``` + +#### ❌ INCORRECT: String instead of dict + +```python +# WRONG - tools must be list of dicts +tools=["code_interpreter"] # WRONG +``` + +--- + +## 7. Environment Variables Patterns + +### 7.1 Correct Environment Variables + +#### ✅ CORRECT: Using os.environ + +```python +environment_variables={ + "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"], + "MODEL_NAME": "gpt-4o-mini" +} +``` + +### 7.2 Anti-Patterns (ERRORS) + +#### ❌ INCORRECT: Hardcoded secrets + +```python +# WRONG - Never hardcode secrets +environment_variables={ + "API_KEY": "sk-1234567890abcdef" # NEVER DO THIS +} +``` + +--- + +## 8. Agent Lifecycle Patterns + +### 8.1 Correct Lifecycle Management + +#### ✅ CORRECT: 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}") +``` + +#### ✅ CORRECT: Delete agent version + +```python +client.agents.delete_version( + agent_name="my-hosted-agent", + version=agent.version +) +``` + +### 8.2 Anti-Patterns (ERRORS) + +#### ❌ INCORRECT: Using delete_agent instead of delete_version + +```python +# WRONG - Use delete_version for hosted agent versions +client.agents.delete_agent(agent_id="wrong-delete-agent") +``` + +--- + +## Summary Checklist + +Before submitting code using hosted agents, verify: + +- [ ] Imports use `azure.ai.projects` (NOT `azure.ai.agents`) for hosted agent models +- [ ] Client is `AIProjectClient` (NOT `AgentsClient`) +- [ ] Uses `create_version` method (NOT `create_agent`) +- [ ] `ImageBasedHostedAgentDefinition` has required `container_protocol_versions` +- [ ] `ImageBasedHostedAgentDefinition` has required `image` parameter +- [ ] `ProtocolVersionRecord` uses `AgentProtocol` enum (NOT string) +- [ ] `cpu` and `memory` are strings with proper units +- [ ] `tools` is a list of dicts (NOT model classes) +- [ ] No hardcoded credentials or secrets +- [ ] Uses `DefaultAzureCredential` for authentication diff --git a/.github/workflows/skill-evaluation.yml b/.github/workflows/skill-evaluation.yml index f2338d4..12464cf 100644 --- a/.github/workflows/skill-evaluation.yml +++ b/.github/workflows/skill-evaluation.yml @@ -164,5 +164,5 @@ jobs: console.log(`::error::${message}`); } } - EOF + EOF fi diff --git a/README.md b/README.md index 4e5ad2c..8c7eb78 100644 --- a/README.md +++ b/README.md @@ -318,7 +318,7 @@ Coding agents like [Copilot CLI](https://github.com/features/copilot/cli) are po > 24 skills • suffix: `-ts`
-Foundry & AI (7 skills) +Foundry & AI (6 skills) | Skill | Description | |-------|-------------| @@ -328,7 +328,6 @@ Coding agents like [Copilot CLI](https://github.com/features/copilot/cli) are po | [azure-ai-translation-ts](.github/skills/azure-ai-translation-ts/) | Translation — text translation, transliteration, document batch. | | [azure-ai-voicelive-ts](.github/skills/azure-ai-voicelive-ts/) | Voice Live — real-time voice AI with WebSocket, Node.js or browser. | | [azure-search-documents-ts](.github/skills/azure-search-documents-ts/) | AI Search — vector/hybrid search, semantic ranking, knowledge bases. | -| [frontend-ui-dark-ts](.github/skills/frontend-ui-dark-ts/) | Frontend UI Dark — Vite + React + Tailwind + Framer Motion dark-themed UI design system. |
@@ -378,12 +377,13 @@ Coding agents like [Copilot CLI](https://github.com/features/copilot/cli) are po
-Monitoring & Frontend (4 skills) +Monitoring & Frontend (5 skills) | Skill | Description | |-------|-------------| | [azure-microsoft-playwright-testing-ts](.github/skills/azure-microsoft-playwright-testing-ts/) | Playwright Testing — scale browser tests, CI/CD integration. | | [azure-monitor-opentelemetry-ts](.github/skills/azure-monitor-opentelemetry-ts/) | OpenTelemetry — tracing, metrics, logs with Application Insights. | +| [frontend-ui-dark-ts](.github/skills/frontend-ui-dark-ts/) | Frontend UI Dark — Vite + React + Tailwind + Framer Motion dark-themed UI design system. | | [react-flow-node-ts](.github/skills/react-flow-node-ts/) | React Flow nodes — custom nodes with TypeScript, handles, Zustand. | | [zustand-store-ts](.github/skills/zustand-store-ts/) | Zustand stores — TypeScript, subscribeWithSelector, state/action separation. | diff --git a/docs-site-fixed-full.png b/docs-site-fixed-full.png new file mode 100644 index 0000000..fd10df8 Binary files /dev/null and b/docs-site-fixed-full.png differ diff --git a/docs-site/integration-filter-test.png b/docs-site/integration-filter-test.png new file mode 100644 index 0000000..efcca9c Binary files /dev/null and b/docs-site/integration-filter-test.png differ diff --git a/docs-site/public/og-image.png b/docs-site/public/og-image.png new file mode 100644 index 0000000..1670a20 Binary files /dev/null and b/docs-site/public/og-image.png differ diff --git a/docs-site/src/components/SkillsSection.tsx b/docs-site/src/components/SkillsSection.tsx index f3feb9a..455571a 100644 --- a/docs-site/src/components/SkillsSection.tsx +++ b/docs-site/src/components/SkillsSection.tsx @@ -138,7 +138,7 @@ export function SkillsSection({ skills }: SkillsSectionProps) {
+ + {title} @@ -42,7 +44,7 @@ const {
⌘K
Showing 133 skills

agent-framework-azure-ai-py

Python

Build Azure AI Foundry agents using the Microsoft Agent Framework Python SDK (agent-framework-azure-ai). Use when creating persistent agents with AzureAIAgentsProvider, using hosted tools (code interpreter, file search, web search), integrating MCP servers, managing conversation threads, or implementing streaming responses. Covers function tools, structured outputs, and multi-tool agents.

foundry

agents-v2-py

Python

Build container-based Foundry Agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. Use when creating hosted agents that run custom code in Azure AI Foundry with your own container images. Triggers: "ImageBasedHostedAgentDefinition", "hosted agent", "container agent", "Foundry Agent", "create_version", "ProtocolVersionRecord", "AgentProtocol.RESPONSES", "custom agent image". @@ -159,7 +159,7 @@

data

azure-storage-queue-py

Python

Azure Queue Storage SDK for Python. Use for reliable message queuing, task distribution, and asynchronous processing. Triggers: "queue storage", "QueueServiceClient", "QueueClient", "message queue", "dequeue".

data

azure-storage-queue-ts

TypeScript

Azure Queue Storage JavaScript/TypeScript SDK (@azure/storage-queue) for message queue operations. Use for sending, receiving, peeking, and deleting messages in queues. Supports visibility timeout, message encoding, and batch operations. Triggers: "queue storage", "@azure/storage-queue", "QueueServiceClient", "QueueClient", "send message", "receive message", "dequeue", "visibility timeout". -

data

azure-web-pubsub-ts

TypeScript

Build real-time messaging applications using Azure Web PubSub SDKs for JavaScript (@azure/web-pubsub, @azure/web-pubsub-client). Use when implementing WebSocket-based real-time features, pub/sub messaging, group chat, or live notifications.

messaging

fastapi-router-py

Python

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.

general

frontend-ui-dark-ts

TypeScript

Build dark-themed React applications using Tailwind CSS with custom theming, glassmorphism effects, and Framer Motion animations. Use when creating dashboards, admin panels, or data-rich interfaces with a refined dark aesthetic.

general

github-issue-creator

Core

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.

general

hosted-agents-v2-py

Python

Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. +

data

azure-web-pubsub-ts

TypeScript

Build real-time messaging applications using Azure Web PubSub SDKs for JavaScript (@azure/web-pubsub, @azure/web-pubsub-client). Use when implementing WebSocket-based real-time features, pub/sub messaging, group chat, or live notifications.

messaging

fastapi-router-py

Python

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.

general

frontend-ui-dark-ts

TypeScript

Build dark-themed React applications using Tailwind CSS with custom theming, glassmorphism effects, and Framer Motion animations. Use when creating dashboards, admin panels, or data-rich interfaces with a refined dark aesthetic.

frontend

github-issue-creator

Core

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.

general

hosted-agents-v2-py

Python

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". diff --git a/docs/og-image.png b/docs/og-image.png new file mode 100644 index 0000000..1670a20 Binary files /dev/null and b/docs/og-image.png differ diff --git a/factory-ai-homepage.png b/factory-ai-homepage.png new file mode 100644 index 0000000..f548ef9 Binary files /dev/null and b/factory-ai-homepage.png differ diff --git a/factory-dark-hero.png b/factory-dark-hero.png new file mode 100644 index 0000000..f22e18f Binary files /dev/null and b/factory-dark-hero.png differ diff --git a/full-page-screenshot.png b/full-page-screenshot.png new file mode 100644 index 0000000..91b3a8c Binary files /dev/null and b/full-page-screenshot.png differ diff --git a/install-bar-desktop.png b/install-bar-desktop.png new file mode 100644 index 0000000..476952f Binary files /dev/null and b/install-bar-desktop.png differ diff --git a/skills/typescript/frontend/frontend-ui-dark b/skills/typescript/frontend/frontend-ui-dark new file mode 120000 index 0000000..35d3d19 --- /dev/null +++ b/skills/typescript/frontend/frontend-ui-dark @@ -0,0 +1 @@ +../../../.github/skills/frontend-ui-dark-ts \ No newline at end of file diff --git a/tests/scenarios/agents-v2-py/scenarios.yaml b/tests/scenarios/agents-v2-py/scenarios.yaml new file mode 100644 index 0000000..29a709f --- /dev/null +++ b/tests/scenarios/agents-v2-py/scenarios.yaml @@ -0,0 +1,445 @@ +# Test scenarios for agents-v2-py skill evaluation +# Each scenario tests a specific usage pattern against acceptance criteria + +config: + model: gpt-4 + max_tokens: 2000 + temperature: 0.3 + +scenarios: + # Basic Client and Agent Creation + - name: basic_hosted_agent_creation + prompt: | + Create a hosted agent using ImageBasedHostedAgentDefinition with AIProjectClient. + Use DefaultAzureCredential for authentication and environment variables for configuration. + The agent should use a container image from Azure Container Registry. + expected_patterns: + - "from azure.ai.projects import AIProjectClient" + - "from azure.identity import DefaultAzureCredential" + - "from azure.ai.projects.models import" + - "ImageBasedHostedAgentDefinition" + - "ProtocolVersionRecord" + - "AgentProtocol" + - "create_version" + - "agent_name=" + - "container_protocol_versions" + - "image=" + forbidden_patterns: + - "from azure.ai.agents.models import ImageBasedHostedAgentDefinition" + - "from azure.ai.agents import AgentsClient" + - "create_agent(" + tags: + - basic + - client + - hosted-agent + mock_response: | + import os + from azure.identity import DefaultAzureCredential + from azure.ai.projects import AIProjectClient + from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, + ) + + 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") + ], + image="myregistry.azurecr.io/my-agent:latest" + ) + ) + + print(f"Created agent: {agent.name} (version: {agent.version})") + + # Protocol Version Configuration + - name: protocol_version_configuration + prompt: | + Create a hosted agent with properly configured container_protocol_versions. + Use ProtocolVersionRecord with AgentProtocol.RESPONSES and version "v1". + expected_patterns: + - "ProtocolVersionRecord" + - "AgentProtocol.RESPONSES" + - 'version="v1"' + - "container_protocol_versions=" + forbidden_patterns: + - 'protocol="RESPONSES"' + - 'protocol="responses"' + - "container_protocol_versions=[]" + tags: + - protocol + - configuration + mock_response: | + import os + from azure.identity import DefaultAzureCredential + from azure.ai.projects import AIProjectClient + from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, + ) + + client = AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=DefaultAzureCredential() + ) + + agent = client.agents.create_version( + agent_name="protocol-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/agent:v1" + ) + ) + + # Resource Allocation + - name: resource_allocation + prompt: | + Create a hosted agent with custom CPU and memory allocation. + Use 2 CPU cores and 4Gi of memory. CPU and memory should be string values. + expected_patterns: + - 'cpu="2"' + - 'memory="4Gi"' + - "ImageBasedHostedAgentDefinition" + forbidden_patterns: + - "cpu=2" + - "memory=4" + - 'memory="4"' + tags: + - resources + - configuration + mock_response: | + import os + from azure.identity import DefaultAzureCredential + from azure.ai.projects import AIProjectClient + from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, + ) + + client = AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=DefaultAzureCredential() + ) + + agent = client.agents.create_version( + agent_name="resource-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/agent:latest", + cpu="2", + memory="4Gi" + ) + ) + + # Tools Configuration + - name: tools_configuration + prompt: | + Create a hosted agent with code_interpreter tool enabled. + Tools should be specified as a list of dictionaries with "type" key. + expected_patterns: + - "tools=" + - '{"type": "code_interpreter"}' + - "ImageBasedHostedAgentDefinition" + forbidden_patterns: + - "CodeInterpreterTool()" + - "from azure.ai.agents.models import CodeInterpreterTool" + - 'tools=["code_interpreter"]' + tags: + - tools + - code-interpreter + mock_response: | + import os + from azure.identity import DefaultAzureCredential + from azure.ai.projects import AIProjectClient + from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, + ) + + client = AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=DefaultAzureCredential() + ) + + agent = client.agents.create_version( + agent_name="tools-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/agent:latest", + tools=[{"type": "code_interpreter"}] + ) + ) + + # Environment Variables + - name: environment_variables + prompt: | + Create a hosted agent with environment variables for configuration. + Include AZURE_AI_PROJECT_ENDPOINT and MODEL_NAME. Use os.environ for sensitive values. + expected_patterns: + - "environment_variables=" + - "AZURE_AI_PROJECT_ENDPOINT" + - "MODEL_NAME" + - "os.environ" + forbidden_patterns: + - 'API_KEY": "sk-' + - '"https://myresource' + tags: + - environment + - configuration + mock_response: | + import os + from azure.identity import DefaultAzureCredential + from azure.ai.projects import AIProjectClient + from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, + ) + + client = AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=DefaultAzureCredential() + ) + + agent = client.agents.create_version( + agent_name="env-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/agent:latest", + environment_variables={ + "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"], + "MODEL_NAME": "gpt-4o-mini" + } + ) + ) + + # Complete Example with All Options + - name: complete_hosted_agent + prompt: | + Create a complete hosted agent with all configuration options: + - Custom CPU and memory + - Code interpreter and file_search tools + - Environment variables + - Proper protocol version configuration + expected_patterns: + - "ImageBasedHostedAgentDefinition" + - "ProtocolVersionRecord" + - "AgentProtocol.RESPONSES" + - "cpu=" + - "memory=" + - "tools=" + - "environment_variables=" + - "create_version" + forbidden_patterns: + - "create_agent(" + - "from azure.ai.agents" + tags: + - complete + - advanced + mock_response: | + import os + from azure.identity import DefaultAzureCredential + from azure.ai.projects import AIProjectClient + from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, + ) + + client = AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=DefaultAzureCredential() + ) + + agent = client.agents.create_version( + agent_name="complete-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/complete-agent: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", + "LOG_LEVEL": "INFO" + } + ) + ) + + print(f"Created agent: {agent.name} (version: {agent.version})") + + # Async Pattern + - name: async_hosted_agent + prompt: | + Create a hosted agent using async/await pattern with proper context managers. + Use azure.ai.projects.aio for the async client and azure.identity.aio for credentials. + expected_patterns: + - "from azure.ai.projects.aio import AIProjectClient" + - "from azure.identity.aio import DefaultAzureCredential" + - "async with" + - "await client.agents.create_version" + - "async def" + forbidden_patterns: + - "from azure.ai.projects import AIProjectClient" + - "from azure.identity import DefaultAzureCredential" + tags: + - async + - advanced + mock_response: | + 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 + + # Agent Lifecycle Management + - name: agent_lifecycle + prompt: | + Show how to manage hosted agent lifecycle: list versions and delete a version. + Use list_versions and delete_version methods. + expected_patterns: + - "list_versions" + - "agent_name=" + - "delete_version" + - "version=" + forbidden_patterns: + - "delete_agent(" + tags: + - lifecycle + - management + mock_response: | + import os + from azure.identity import DefaultAzureCredential + from azure.ai.projects import AIProjectClient + from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, + ) + + client = AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=DefaultAzureCredential() + ) + + # Create agent + agent = client.agents.create_version( + agent_name="lifecycle-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/agent:latest" + ) + ) + + # List all versions + versions = client.agents.list_versions(agent_name="lifecycle-agent") + for version in versions: + print(f"Version: {version.version}, State: {version.state}") + + # Delete specific version + client.agents.delete_version( + agent_name="lifecycle-agent", + version=agent.version + ) + + # MCP Tool Configuration + - name: mcp_tool_configuration + prompt: | + Create a hosted agent with MCP tool configured for external service integration. + Include server_label and server_url in the MCP tool configuration. + expected_patterns: + - '"type": "mcp"' + - "server_label" + - "server_url" + - "tools=" + forbidden_patterns: + - "project_connection_id" + tags: + - tools + - mcp + - advanced + mock_response: | + import os + from azure.identity import DefaultAzureCredential + from azure.ai.projects import AIProjectClient + from azure.ai.projects.models import ( + ImageBasedHostedAgentDefinition, + ProtocolVersionRecord, + AgentProtocol, + ) + + client = AIProjectClient( + endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + credential=DefaultAzureCredential() + ) + + agent = client.agents.create_version( + agent_name="mcp-agent", + definition=ImageBasedHostedAgentDefinition( + container_protocol_versions=[ + ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1") + ], + image="myregistry.azurecr.io/mcp-agent:latest", + tools=[ + {"type": "code_interpreter"}, + { + "type": "mcp", + "server_label": "my-mcp-server", + "server_url": "https://my-mcp-server.example.com" + } + ] + ) + )