Azure AI Agent Scaffolding Skill

Description

--- name: azd-ai-init description: Structure agent code for Azure's `azd ai` command. Use when users mention "azd ai", "azd init agent", "Foundry agent", "scaffold agent", "convert to azd", "update for azd", "upgrade to azd ai", "fix azd ai", "migrate to Foundry", or want to deploy, convert, update, fix, or upgrade an AI agent for Azure. model: claude-opus-4-5 --- # Azure AI Agent Scaffolding Skill This skill helps developers prepare their AI agent code for deployment to Azure AI Foundry using the `azd ai` extension of the Azure Developer CLI. ## When to Use This Skill Use this skill when a user wants to: - **Scaffold a new agent from scratch** (greenfield project with no existing code) - Convert existing agent code to the `azd ai` expected format - Scaffold a new Azure AI Foundry agent project from scratch - Structure their agent for deployment with `azd up` - Understand what files and configuration `azd ai` requires - Migrate from other agent frameworks to Azure AI Foundry hosted agents ## Core Workflow ### Step 1: Analyze the User's Current Project First, understand what the user has: 1. **Detect existing code**: Look for agent implementations (Python, TypeScript, etc.) 2. **Identify the agent framework**: LangGraph, Semantic Kernel, AutoGen, custom, etc. 3. **Find entry points**: main.py, index.ts, or other entry files 4. **Check for existing configuration**: azure.yaml, agent.yaml, Dockerfile, requirements.txt, package.json ### Step 2: Generate Required Files The `azd ai` extension expects a specific project structure: ``` project-root/ ├── azure.yaml # Project configuration (REQUIRED) ├── infra/ # Bicep infrastructure files (REQUIRED) │ ├── main.bicep │ ├── main.parameters.json │ └── core/ # Reusable Bicep modules │ └── ai/ │ └── ai-project.bicep └── src/ └── <AgentName>/ # Agent source folder (REQUIRED) ├── agent.yaml # Agent definition (REQUIRED) ├── Dockerfile # Container build file (REQUIRED) ├── main.py # Agent entry point └── requirements.txt ``` ### Step 3: Create Configuration Files #### azure.yaml (Project Root) This is the main project configuration file that defines services and infrastructure: ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json requiredVersions: extensions: azure.ai.agents: '>=0.1.0-preview' name: <project-name> services: <AgentName>: project: src/<AgentName> host: azure.ai.agent language: docker docker: remoteBuild: true config: container: resources: cpu: "1" memory: 2Gi scale: maxReplicas: 3 minReplicas: 1 deployments: - model: format: OpenAI name: gpt-4o-mini version: "2024-07-18" name: gpt-4o-mini sku: capacity: 10 name: GlobalStandard infra: provider: bicep path: ./infra ``` #### agent.yaml (Inside src/<AgentName>/) Defines the agent's metadata, protocols, and environment variables: ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml kind: hosted name: <AgentName> description: "<Brief description of what the agent does>" metadata: authors: - <author-name> example: - content: "<Example user prompt - always quote strings with special characters>" role: user tags: - <tag1> - <tag2> protocols: - protocol: responses version: v1 environment_variables: - name: FOUNDRY_PROJECT_ENDPOINT value: ${AZURE_AI_PROJECT_ENDPOINT} - name: FOUNDRY_MODEL_DEPLOYMENT_NAME value: gpt-4o-mini - name: APPLICATIONINSIGHTS_CONNECTION_STRING value: ${APPLICATIONINSIGHTS_CONNECTION_STRING} ``` **Note:** Set `FOUNDRY_MODEL_DEPLOYMENT_NAME` to match the deployment name in your `azure.yaml` (e.g., `gpt-4o-mini`). **⚠️ Environment Variable Naming:** The hosted agent platform injects variables with `FOUNDRY_` prefix. Your Python code must read `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL_DEPLOYMENT_NAME` (not `AZURE_*` prefixes). The `agent.yaml` maps Azure outputs to the expected names. **IMPORTANT YAML Formatting Rules:** - Always wrap `content:` and `description:` values in double quotes - Escape internal quotes with backslash: `"He said \"hello\""` - Strings with colons, commas, or special characters MUST be quoted #### Dockerfile Standard Python container for hosted agents: ```dockerfile FROM python:3.11-slim WORKDIR /app COPY ./ user_agent/ WORKDIR /app/user_agent RUN if [ -f requirements.txt ]; then \ pip install -r requirements.txt; \ else \ echo "No requirements.txt found"; \ fi EXPOSE 8088 ENV PORT=8088 CMD ["python", "main.py"] ``` For TypeScript/Node.js agents: ```dockerfile FROM node:20-slim WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . EXPOSE 8088 ENV PORT=8088 CMD ["node", "dist/main.js"] ``` ### Step 4: Adapt the Agent Code The agent code must use the Azure AI Agent Framework pattern to run as a hosted agent: ### Client Selection Guide | Scenario | Client Type | Notes | |----------|-------------|-------| | Local development with AI Services endpoint | `AzureOpenAIChatClient` | Uses ChatAgent pattern | | **Hosted agent deployment (azd up)** | `AzureAIAgentClient` | **Required** - Uses create_agent + from_agent_framework | | Foundry Project endpoint | `AzureAIAgentClient` | Requires FOUNDRY_* env vars | #### Python Example (using agent_framework) ```python import asyncio import os import logging from typing import Annotated from azure.identity.aio import DefaultAzureCredential from agent_framework.azure import AzureAIAgentClient from azure.ai.agentserver.agentframework import from_agent_framework from azure.monitor.opentelemetry import configure_azure_monitor from dotenv import load_dotenv load_dotenv(override=True) logger = logging.getLogger(__name__) if os.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING"): configure_azure_monitor(enable_live_metrics=True, logger_name="__main__") ENDPOINT = os.getenv("FOUNDRY_PROJECT_ENDPOINT", "") MODEL_DEPLOYMENT_NAME = os.getenv("FOUNDRY_MODEL_DEPLOYMENT_NAME", "") # Define your tools as functions with type annotations # IMPORTANT: Use simple strings in Annotated[], NOT Pydantic Field objects def my_tool( param1: Annotated[str, "Description of param1"], param2: Annotated[int, "Description of param2"] ) -> str: """Tool description that the model will see.""" # Tool implementation return "result" tools = [my_tool] async def run_server(): """Run the agent as an HTTP server.""" credential = DefaultAzureCredential() try: client = AzureAIAgentClient( project_endpoint=ENDPOINT, model_deployment_name=MODEL_DEPLOYMENT_NAME, credential=credential, ) agent = client.create_agent( name="<AgentName>", model=MODEL_DEPLOYMENT_NAME, instructions="<Your agent system instructions>", tools=tools, ) logger.info("Starting Agent HTTP Server...") await from_agent_framework(agent).run_async() finally: await credential.close() def main(): asyncio.run(run_server()) if __name__ == "__main__": main() ``` #### Required Python Dependencies (requirements.txt) ``` # Core agent packages agent-framework-azure-ai agent-framework-core azure-ai-agentserver-agentframework # Web server (required by agent server) uvicorn fastapi # Azure identity azure-identity # Environment python-dotenv # Monitoring azure-monitor-opentelemetry ``` ## Infrastructure (Bicep Files) **CRITICAL:** The `azd ai` extension requires infrastructure that provisions `Microsoft.CognitiveServices/accounts/projects` resources. The Bicep modules are complex (~300+ lines) and must be obtained from the official template. ### Getting the Infrastructure (Required) **Always use the official starter template for infrastructure:** ```bash # Option 1: Initialize a new project with infra included azd init -t Azure-Samples/azd-ai-starter-basic # Option 2: Copy infra to an existing project git clone --depth 1 https://github.com/Azure-Samples/azd-ai-starter-basic.git temp-starter cp -r temp-starter/infra ./infra rm -rf temp-starter ``` The official `infra/` folder contains: ``` infra/ ├── main.bicep # Main deployment orchestrator ├── main.parameters.json # Parameter mappings ├── abbreviations.json # Resource naming conventions └── core/ └── ai/ └── ai-project.bicep # AI Foundry provisioning module ``` ### What the Infrastructure Provisions The `core/ai/ai-project.bicep` module creates: - **Microsoft.CognitiveServices/accounts** - AI Services account (Foundry) - **Microsoft.CognitiveServices/accounts/projects** - Foundry project (nested resource) - **Container Registry** - For agent container images - **Application Insights** - Monitoring and logging - **Log Analytics Workspace** - Log storage - **Model Deployments** - GPT-4o, GPT-4o-mini, etc. - **Capability Host** - For hosted agents ### Required Bicep Outputs The main.bicep must output these environment variables for `azd ai` to work: ```bicep // Required outputs - azd ai uses these to locate resources output AZURE_RESOURCE_GROUP string = resourceGroupName output AZURE_AI_ACCOUNT_ID string = aiProject.outputs.accountId output AZURE_AI_PROJECT_ID string = aiProject.outputs.projectId output AZURE_AI_ACCOUNT_NAME string = aiProject.outputs.aiServicesAccountName output AZURE_AI_PROJECT_NAME string = aiProject.outputs.projectName // Endpoints output AZURE_AI_PROJECT_ENDPOINT string = aiProject.outputs.AZURE_AI_PROJECT_ENDPOINT output AZURE_OPENAI_ENDPOINT string = aiProject.outputs.AZURE_OPENAI_ENDPOINT output APPLICATIONINSIGHTS_CONNECTION_STRING string = aiProject.outputs.APPLICATIONINSIGHTS_CONNECTION_STRING // Container Registry output AZURE_CONTAINER_REGISTRY_ENDPOINT string = aiProject.outputs.dependentResources.registry.loginServer ``` **Note:** The `AZURE_AI_PROJECT_ID` must be in the format: ``` /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project} ``` Do NOT use `Microsoft.MachineLearningServices/workspaces` - this is a different resource type that won't work with `azd ai`. ### infra/main.parameters.json ## Model Deployment Configuration The `deployments` section in `azure.yaml` under each service's `config` defines the AI models: | Property | Description | Example | |----------|-------------|---------| | `name` | Deployment name | `gpt-4o-mini` | | `model.format` | Model provider | `OpenAI` | | `model.name` | Model identifier | `gpt-4o-mini` | | `model.version` | Model version | `2024-07-18` | | `sku.name` | SKU tier | `GlobalStandard` | | `sku.capacity` | Tokens per minute (thousands) | `10` | ### Available Models Common models for agents: - `gpt-4o` (version: `2024-08-06`) - `gpt-4o-mini` (version: `2024-07-18`) - `gpt-4-turbo` (version: `2024-04-09`) ## Region Requirements for Hosted Agents **IMPORTANT:** Hosted agents are only supported in specific Azure regions. ### Supported Regions (as of January 2026) - **North Central US** ✅ (Default in templates) The provided Bicep templates default to `northcentralus`. If you need to change the region, verify hosted agent support first. ## Deployment Commands After scaffolding, users deploy with: ```bash # Install the azd ai extension (if not installed) azd extension install azure.ai.agents # Login to Azure azd auth login # Initialize environment (creates .azure folder) azd init # Provision infrastructure and deploy agent azd up ``` Or step-by-step: ```bash azd provision # Create Azure resources azd deploy # Deploy the agent ``` ### Troubleshooting Deployment If `azd deploy` times out waiting for the container: 1. **Check container logs** in Azure Portal: - Go to the AI Foundry project - Navigate to Agents section - Check container status and logs 2. **Common issues:** - Missing dependencies in `requirements.txt` - Import errors in agent code - Agent not listening on port 8088 - Missing environment variables 3. **Test locally first:** ```bash cd src/YourAgent pip install -r requirements.txt python main.py ``` 4. **Verify the agent starts a server:** The agent must call `from_agent_framework(agent).run_async()` to start the HTTP server. ## Guidelines for Converting Existing Agents ### From LangGraph/LangChain 1. Keep the graph/chain logic intact 2. Wrap it in the `AzureAIAgentClient` pattern 3. Expose tools as annotated functions 4. Use `from_agent_framework(agent).run_async()` to serve ### From Semantic Kernel 1. Convert plugins to tool functions 2. Use the same agent hosting pattern 3. Map kernel functions to `tools` list ### From AutoGen 1. Extract agent logic into tool functions 2. Define single agent using `AzureAIAgentClient` 3. Multi-agent patterns may need restructuring ## Common Customizations ### Adding Environment Variables In `agent.yaml`: ```yaml environment_variables: - name: CUSTOM_VAR value: ${MY_ENV_VAR} ``` In `azure.yaml` under service config: ```yaml config: env: CUSTOM_VAR: "value" ``` ### Adding Azure Resources (Connections) For agents needing additional Azure services (search, storage, etc.), add to `azure.yaml`: ```yaml config: resources: - resource: search connectionName: my-search-connection - resource: storage connectionName: my-storage-connection ``` Available resource types: - `search` - Azure AI Search - `storage` - Azure Storage - `registry` - Azure Container Registry - `bing_grounding` - Bing Search - `bing_custom_grounding` - Bing Custom Search ### Scaling Configuration ```yaml config: container: resources: cpu: "2" memory: 4Gi scale: minReplicas: 1 maxReplicas: 10 ``` ## Greenfield Scaffolding (No Existing Code) When a user has no existing code and wants to create a new agent from scratch, generate a complete working project. ### Quick Start Template For users who say "create a new agent for azd ai" or "scaffold a new Foundry agent", generate this complete structure: #### 1. Create Project Structure ```bash mkdir -p my-agent/src/MyAgent my-agent/infra/core/ai ``` #### 2. azure.yaml (Project Root) ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json requiredVersions: extensions: azure.ai.agents: '>=0.1.0-preview' name: my-agent services: MyAgent: project: src/MyAgent host: azure.ai.agent language: docker docker: remoteBuild: true config: container: resources: cpu: "1" memory: 2Gi scale: maxReplicas: 3 minReplicas: 1 deployments: - model: format: OpenAI name: gpt-4o-mini version: "2024-07-18" name: gpt-4o-mini sku: capacity: 10 name: GlobalStandard infra: provider: bicep path: ./infra ``` #### 3. src/MyAgent/agent.yaml ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml kind: hosted name: MyAgent description: "A helpful assistant that can answer questions and perform tasks." metadata: authors: - developer example: - content: "Hello, what can you help me with?" role: user tags: - starter - assistant protocols: - protocol: responses version: v1 environment_variables: - name: FOUNDRY_PROJECT_ENDPOINT value: ${AZURE_AI_PROJECT_ENDPOINT} - name: FOUNDRY_MODEL_DEPLOYMENT_NAME value: gpt-4o-mini - name: APPLICATIONINSIGHTS_CONNECTION_STRING value: ${APPLICATIONINSIGHTS_CONNECTION_STRING} ``` #### 4. src/MyAgent/main.py ```python import asyncio import os import logging from typing import Annotated from azure.identity.aio import DefaultAzureCredential from agent_framework.azure import AzureAIAgentClient from azure.ai.agentserver.agentframework import from_agent_framework from azure.monitor.opentelemetry import configure_azure_monitor from dotenv import load_dotenv load_dotenv(override=True) logger = logging.getLogger(__name__) if os.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING"): configure_azure_monitor(enable_live_metrics=True, logger_name="__main__") ENDPOINT = os.getenv("FOUNDRY_PROJECT_ENDPOINT", "") MODEL_DEPLOYMENT_NAME = os.getenv("FOUNDRY_MODEL_DEPLOYMENT_NAME", "") # =========================================== # Define your tools here # =========================================== def greet( name: Annotated[str, "The name of the person to greet"] ) -> str: """Greet someone by name. Args: name: The person's name """ return f"Hello, {name}! Nice to meet you." def get_current_time() -> str: """Get the current date and time.""" from datetime import datetime return datetime.now().strftime("%Y-%m-%d %H:%M:%S") def calculate( expression: Annotated[str, "A mathematical expression to evaluate, e.g. '2 + 2'"] ) -> str: """Safely evaluate a mathematical expression. Args: expression: Math expression like '2 + 2' or '10 * 5' """ # Safe evaluation of basic math allowed_chars = set("0123456789+-*/(). ") if not all(c in allowed_chars for c in expression): return "Error: Invalid characters in expression" try: result = eval(expression) return f"{expression} = {result}" except Exception as e: return f"Error: {str(e)}" # Collect all tools tools = [greet, get_current_time, calculate] # =========================================== # Agent Server # =========================================== async def run_server(): """Run the agent as an HTTP server.""" credential = DefaultAzureCredential() try: client = AzureAIAgentClient( project_endpoint=ENDPOINT, model_deployment_name=MODEL_DEPLOYMENT_NAME, credential=credential, ) agent = client.create_agent( name="MyAgent", model=MODEL_DEPLOYMENT_NAME, instructions="""You are a helpful assistant. You can: - Greet people by name - Tell the current time - Perform basic math calculations Be friendly and helpful. Use the available tools when appropriate.""", tools=tools, ) logger.info("Starting MyAgent HTTP Server...") print("Starting MyAgent HTTP Server on port 8088...") await from_agent_framework(agent).run_async() finally: await credential.close() def main(): """Main entry point.""" asyncio.run(run_server()) if __name__ == "__main__": main() ``` #### 5. src/MyAgent/requirements.txt ``` # Core agent packages agent-framework-azure-ai agent-framework-core azure-ai-agentserver-agentframework # Web server (required by agent server) uvicorn fastapi # Azure identity azure-identity # Environment python-dotenv # Monitoring azure-monitor-opentelemetry ``` #### 6. src/MyAgent/Dockerfile ```dockerfile FROM python:3.11-slim WORKDIR /app COPY ./ user_agent/ WORKDIR /app/user_agent RUN pip install --no-cache-dir -r requirements.txt EXPOSE 8088 ENV PORT=8088 ENV PYTHONUNBUFFERED=1 CMD ["python", "main.py"] ``` #### 7. infra/main.bicep Use the standard Bicep template from the Infrastructure section above, or point users to clone from the starter template: ```bash # Alternative: Start from official template azd init -t Azure-Samples/azd-ai-starter-basic ``` #### 8. infra/main.parameters.json ```json { "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", "contentVersion": "1.0.0.0", "parameters": { "environmentName": { "value": "${AZURE_ENV_NAME}" }, "location": { "value": "${AZURE_LOCATION}" }, "aiDeploymentsLocation": { "value": "${AZURE_AI_DEPLOYMENTS_LOCATION}" }, "principalId": { "value": "${AZURE_PRINCIPAL_ID}" }, "principalType": { "value": "${AZURE_PRINCIPAL_TYPE}" }, "aiProjectDeploymentsJson": { "value": "${AI_PROJECT_DEPLOYMENTS}" }, "aiProjectConnectionsJson": { "value": "${AI_PROJECT_CONNECTIONS}" }, "aiProjectDependentResourcesJson": { "value": "${AI_PROJECT_DEPENDENT_RESOURCES}" }, "enableHostedAgents": { "value": "${ENABLE_HOSTED_AGENTS=true}" } } } ``` ### Final Project Structure ``` my-agent/ ├── azure.yaml ├── infra/ │ ├── main.bicep │ ├── main.parameters.json │ └── core/ │ └── ai/ │ └── ai-project.bicep └── src/ └── MyAgent/ ├── agent.yaml ├── Dockerfile ├── main.py └── requirements.txt ``` ### Deploy the Agent ```bash cd my-agent # Login to Azure azd auth login # Initialize environment (creates .azure folder) azd init # Deploy everything azd up ``` The agent will be live at the Azure AI Foundry endpoint shown in the output. --- ## Example: Complete Scaffolding Session (Existing Code) When a user says "prepare my calculator agent for azd ai": 1. **Analyze**: Find their `calculator.py` with add/multiply/divide functions 2. **Create structure**: - Create `src/CalculatorAgent/` directory - Move/adapt code to `main.py` - Create `agent.yaml` with metadata - Create `Dockerfile` - Create `requirements.txt` 3. **Create root configs**: - Create `azure.yaml` with service definition - Create `infra/` with Bicep files 4. **Provide next steps**: Tell user to run `azd up` ## References - [Azure Developer CLI Documentation](https://learn.microsoft.com/azure/developer/azure-developer-cli/) - [azd ai agent extension](https://github.com/Azure/azure-dev/tree/main/cli/azd/extensions/azure.ai.agents) - [Azure AI Foundry](https://ai.azure.com) - [Agent Framework Samples](https://github.com/azure-ai-foundry/foundry-samples) - [azd-ai-starter-basic template](https://github.com/Azure-Samples/azd-ai-starter-basic) ## YAML Validation Checklist **Before completing, always validate generated YAML files:** 1. **Quote all string values** that contain: - Colons (`:`) - Commas (`,`) - Special characters (`#`, `&`, `*`, `!`, `|`, `>`, `'`, `"`, `%`, `@`, `` ` ``) - Leading/trailing spaces 2. **Required quoting patterns:** ```yaml # CORRECT description: "A helpful agent that answers questions." content: "What is 2 + 2?" content: "Subject: Meeting - Let's discuss the project." # INCORRECT - will break parsing description: A helpful agent that answers questions. content: What is 2 + 2? content: Subject: Meeting - Let's discuss the project. ``` 3. **Escape internal quotes:** ```yaml content: "He said \"hello\" to everyone." ``` 4. **Validate YAML syntax** before finishing: ```bash # Python python -c "import yaml; yaml.safe_load(open('agent.yaml'))" # Node.js node -e "require('js-yaml').load(require('fs').readFileSync('agent.yaml'))" ``` 5. **Check for common errors:** - Inconsistent indentation (use 2 or 4 spaces, not tabs) - Missing quotes around values with special characters - Trailing whitespace - Missing required fields

Security Status