azure-ai-foundry · nikhowlettMicrosoft · Oct 29, 2025 · Nov 4, 2025
diff --git a/samples/microsoft/python/migration/.dockerignore b/samples/microsoft/python/migration/.dockerignore
@@ -0,0 +1,13 @@
+# Docker-related files
+.env
+output/
+*.log
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# Migration output
+migration_*.json
+agent_*.json
diff --git a/samples/microsoft/python/migration/.env.example b/samples/microsoft/python/migration/.env.example
@@ -0,0 +1,53 @@
+# V1 to V2 Migration Environment Configuration
+# Copy this file to .env and fill in your values
+
+# Azure Project Configuration (choose one method)
+# Method 1: Project Endpoint
+PROJECT_ENDPOINT_URL=https://your-project-name.cognitiveservices.azure.com
+
+# Method 2: Project Connection String
+# PROJECT_CONNECTION_STRING=endpoint=https://your-project.cognitiveservices.azure.com;subscriptionid=your-sub-id;resourcegroupname=your-rg;projectname=your-project
+
+# Cosmos DB Configuration (optional - for Cosmos input/output)
+# COSMOS_DB_CONNECTION_STRING=AccountEndpoint=https://your-cosmos.documents.azure.com:443/;AccountKey=your-key==;
+# COSMOS_DB_DATABASE_NAME=assistants
+# COSMOS_DB_CONTAINER_NAME=v1_assistants
+
+# OpenAI v1 API Configuration (optional - for v1 API input)
+# ASSISTANT_API_BASE=https://api.openai.com/v1
+# ASSISTANT_API_KEY=sk-your-openai-key
+# ASSISTANT_API_VERSION=v1
+
+# Azure OpenAI v1 Configuration (optional - alternative to OpenAI)
+# ASSISTANT_API_BASE=https://your-aoai.openai.azure.com
+# ASSISTANT_API_KEY=your-azure-openai-key
+# ASSISTANT_API_VERSION=2024-02-15-preview
+
+# v2 API Configuration (optional - for v2 API output)
+# V2_API_BASE=https://your-v2-api.cognitiveservices.azure.com
+# V2_API_KEY=your-v2-api-key
+# V2_API_VERSION=2024-05-01-preview
+
+# Azure Authentication (optional - for service principal auth)
+# AZURE_TENANT_ID=your-tenant-id
+# AZURE_CLIENT_ID=your-client-id
+# AZURE_CLIENT_SECRET=your-client-secret
+# AZURE_SUBSCRIPTION_ID=your-subscription-id
+# AZURE_RESOURCE_GROUP=your-resource-group
+# AZURE_PROJECT_NAME=your-project-name
+
+# Example configurations for common scenarios:
+
+# Scenario 1: Migrate from Azure AI Project to v2 API
+# PROJECT_ENDPOINT_URL=https://myproject-eastus.cognitiveservices.azure.com
+# V2_API_BASE=https://myproject-v2-eastus.cognitiveservices.azure.com
+# V2_API_KEY=your-v2-key
+
+# Scenario 2: Migrate from OpenAI to Cosmos DB
+# ASSISTANT_API_BASE=https://api.openai.com/v1
+# ASSISTANT_API_KEY=sk-your-key
+# COSMOS_DB_CONNECTION_STRING=AccountEndpoint=https://...;AccountKey=...;
+
+# Scenario 3: Migrate from Cosmos DB to Azure AI Project v2
+# COSMOS_DB_CONNECTION_STRING=AccountEndpoint=https://...;AccountKey=...;
+# PROJECT_ENDPOINT_URL=https://myproject.cognitiveservices.azure.com
diff --git a/samples/microsoft/python/migration/Dockerfile b/samples/microsoft/python/migration/Dockerfile
@@ -0,0 +1,43 @@
+# Use Python 3.11 slim image
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    gnupg \
+    lsb-release \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Azure CLI
+RUN curl -sL https://aka.ms/InstallAzureCLIDeb | bash
+
+# Copy requirements file
+COPY requirements.txt .
+
+# Install Python dependencies from requirements.txt
+RUN pip install -r requirements.txt
+
+# Copy the migration script and supporting files
+COPY v1_to_v2_migration.py .
+COPY read_cosmos_data.py .
+
+# Create a non-root user for security
+RUN useradd -m -u 1000 migration && chown -R migration:migration /app
+
+# Create Azure CLI directory with proper permissions for the migration user
+RUN mkdir -p /home/migration/.azure && chown -R migration:migration /home/migration/.azure
+
+# Switch to migration user
+USER migration
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app
+ENV AZURE_CONFIG_DIR=/home/migration/.azure
+
+# Default command
+ENTRYPOINT ["python", "v1_to_v2_migration.py"]
+CMD ["--help"]
diff --git a/samples/microsoft/python/migration/README-Docker.md b/samples/microsoft/python/migration/README-Docker.md
@@ -0,0 +1,141 @@
+# V1 to V2 Agent Migration - Docker Container
+
+This directory contains the containerized version of the v1 to v2 agent migration script.
+
+## Quick Start
+
+### Prerequisites
+- Docker installed and running
+- Azure CLI installed and authenticated (`az login`)
+- Access to source data (Cosmos DB, API, or Project)
+
+### Build and Run
+
+#### Option 1: Using the helper scripts (Recommended)
+
+**Linux/macOS:**
+```bash
+# Make the script executable
+chmod +x run-migration.sh
+
+# Run migration with arguments
+./run-migration.sh --help
+./run-migration.sh --use-api --use-v2-api
+./run-migration.sh asst_abc123 --project-connection-string "eastus.api.azureml.ms;...;...;..."
+```
+
+**Windows:**
+```cmd
+# Run migration with arguments
+run-migration.bat --help
+run-migration.bat --use-api --use-v2-api
+run-migration.bat asst_abc123 --project-connection-string "eastus.api.azureml.ms;...;...;..."
+```
+
+#### Option 2: Using Docker directly
+
+```bash
+# Build the image
+docker build -t v1-to-v2-migration .
+
+# Run with arguments
+docker run --rm -it \
+  --network host \
+  -v ~/.azure:/home/migration/.azure:ro \
+  -v "$(pwd)/output:/app/output" \
+  -e COSMOS_CONNECTION_STRING \
+  v1-to-v2-migration --help
+```
+
+#### Option 3: Using Docker Compose
+
+```bash
+# Create .env file from example
+cp .env.example .env
+# Edit .env with your values
+
+# Run with Docker Compose
+docker-compose run --rm v1-to-v2-migration --help
+docker-compose run --rm v1-to-v2-migration --use-api --use-v2-api
+```
+
+## Configuration
+
+### Environment Variables
+
+The container supports all the same environment variables as the standalone script:
+
+- `COSMOS_CONNECTION_STRING`: Cosmos DB connection string
+- `AGENTS_HOST`: API host (default: eastus.api.azureml.ms)
+- `AGENTS_SUBSCRIPTION`: Azure subscription ID
+- `AGENTS_RESOURCE_GROUP`: Resource group for v1 API
+- `AGENTS_RESOURCE_GROUP_V2`: Resource group for v2 API
+- `AGENTS_WORKSPACE`: Workspace for v1 API
+- `AGENTS_WORKSPACE_V2`: Workspace for v2 API
+- `AGENTS_API_VERSION`: API version (default: 2025-05-15-preview)
+- `AZ_TOKEN`: Optional Azure token (will use Azure CLI if not provided)
+
+### Volume Mounts
+
+- `~/.azure:/home/migration/.azure:ro`: Azure CLI configuration (read-only)
+- `./output:/app/output`: Output directory for logs and results
+
+## Usage Examples
+
+### Test Tool Injection
+```bash
+# Test all tool types
+./run-migration.sh --add-test-function --add-test-mcp --add-test-computer --add-test-imagegen --add-test-azurefunction --use-api
+
+# Test specific tool combinations
+./run-migration.sh --add-test-mcp --add-test-computer --project-connection-string "eastus.api.azureml.ms;...;...;..."
+```
+
+### Migration Workflows
+```bash
+# Migrate all assistants from API to v2 API
+./run-migration.sh --use-api --use-v2-api
+
+# Migrate specific assistant from Cosmos DB to Cosmos DB
+./run-migration.sh asst_abc123
+
+# Migrate from project connection to v2 API
+./run-migration.sh --project-connection-string "eastus.api.azureml.ms;...;...;..." --use-v2-api
+```
+
+## Features
+
+✅ **Complete Migration Pipeline**: All 4 input methods, 2 output methods  
+✅ **Tool Testing**: 5 different test tool types for validation  
+✅ **Azure CLI Integration**: Automatic token management  
+✅ **Security**: Non-root user, read-only mounts  
+✅ **Cross-Platform**: Works on Linux, macOS, and Windows  
+✅ **Flexible Configuration**: Environment variables, volume mounts  
+✅ **Network Access**: Host networking for localhost v2 API access  
+
+## Troubleshooting
+
+### Docker Issues
+- Ensure Docker is running: `docker info`
+- Check image build: `docker images | grep v1-to-v2-migration`
+
+### Authentication Issues
+- Verify Azure CLI: `az account show`
+- Check token: `az account get-access-token --scope https://ai.azure.com/.default`
+
+### Network Issues
+- For localhost v2 API, ensure `--network host` is used
+- Check firewall settings for container network access
+
+### Permission Issues
+- Ensure Azure CLI config is readable: `ls -la ~/.azure`
+- Check output directory permissions: `ls -la ./output`
+
+## Development
+
+To modify the container:
+
+1. Edit the migration script: `v1_to_v2_migration.py`
+2. Update dependencies: `requirements.txt`
+3. Rebuild the image: `docker build -t v1-to-v2-migration .`
+4. Test changes: `./run-migration.sh --help`