Merge pull request #53216 from MicrosoftDocs/NEW-genaiops

JamesJBarnett · web-flow · commit 4760fc271992 · 2026-01-26T13:18:25.000-07:00
New module on prompt versioning, part of GenAIOps path
diff --git a/learn-pr/paths/operationalize-gen-ai-apps/index.yml b/learn-pr/paths/operationalize-gen-ai-apps/index.yml
@@ -28,6 +28,7 @@ subjects:
 - natural-language-processing
 modules:
 - learn.wwl.plan-prepare-genaiops
+- learn.wwl.prompt-versioning-genaiops
 - learn.evaluate-generative-ai-apps
 - learn.wwl.monitor-generative-ai-app
 - learn.wwl.tracing-generative-ai-app
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/1-introduction.yml b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/1-introduction.yml
@@ -0,0 +1,15 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.prompt-versioning-genaiops.introduction
+title: Introduction
+metadata:
+  title: Introduction
+  description: "Introduction to prompt versioning for GenAIOps"
+  ms.date: 01/07/2026
+  author: madiepev
+  ms.author: madiepev
+  ms.topic: unit
+  ms.custom:
+  - N/A
+durationInMinutes: 3
+content: |
+  [!include[](includes/1-introduction.md)]
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/2-version-control-for-prompts.yml b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/2-version-control-for-prompts.yml
@@ -0,0 +1,15 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.prompt-versioning-genaiops.version-control-for-prompts
+title: Apply version control to prompts
+metadata:
+  title: Apply version control to prompts
+  description: "Learn why prompts need version control and how DevOps practices apply to prompt management"
+  ms.date: 01/26/2026
+  author: madiepev
+  ms.author: madiepev
+  ms.topic: unit
+  ms.custom:
+  - N/A
+durationInMinutes: 5
+content: |
+  [!include[](includes/2-version-control-for-prompts.md)]
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/3-foundry-agents-prompt-versioning.yml b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/3-foundry-agents-prompt-versioning.yml
@@ -0,0 +1,15 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.prompt-versioning-genaiops.foundry-agents-prompt-versioning
+title: Understand Microsoft Foundry agents and prompt versioning
+metadata:
+  title: Understand Microsoft Foundry agents and prompt versioning
+  description: "Learn how prompts integrate with Microsoft Foundry agent definitions and how to version agents using Git tags"
+  ms.date: 01/26/2026
+  author: madiepev
+  ms.author: madiepev
+  ms.topic: unit
+  ms.custom:
+  - N/A
+durationInMinutes: 7
+content: |
+  [!include[](includes/3-foundry-agents-prompt-versioning.md)]
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/4-github-repository-structure.yml b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/4-github-repository-structure.yml
@@ -0,0 +1,15 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.prompt-versioning-genaiops.github-repository-structure
+title: Organize prompts in GitHub repositories
+metadata:
+  title: Organize prompts in GitHub repositories
+  description: "Learn how to organize prompts in GitHub repositories with proper folder structure, file formats, and naming conventions"
+  ms.date: 01/26/2026
+  author: madiepev
+  ms.author: madiepev
+  ms.topic: unit
+  ms.custom:
+  - N/A
+durationInMinutes: 10
+content: |
+  [!include[](includes/4-github-repository-structure.md)]
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/5-prompt-workflow-development.yml b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/5-prompt-workflow-development.yml
@@ -0,0 +1,15 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.prompt-versioning-genaiops.prompt-workflow-development
+title: Develop safe prompt deployment workflows
+metadata:
+  title: Develop safe prompt deployment workflows
+  description: "Learn to develop workflows for testing and deploying prompts safely through development, validation, and production stages"
+  ms.date: 01/26/2026
+  author: madiepev
+  ms.author: madiepev
+  ms.topic: unit
+  ms.custom:
+  - N/A
+durationInMinutes: 8
+content: |
+  [!include[](includes/5-prompt-workflow-development.md)]
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/6-exercise.yml b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/6-exercise.yml
@@ -0,0 +1,15 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.prompt-versioning-genaiops.exercise
+title: Exercise - Develop prompt and agent versions
+metadata:
+  title: Exercise - Develop prompt and agent versions
+  description: "Deploy multiple agent versions in Microsoft Foundry and track them using GitHub version control"
+  ms.date: 01/26/2026
+  author: madiepev
+  ms.author: madiepev
+  ms.topic: unit
+  ms.custom:
+  - N/A
+durationInMinutes: 15
+content: |
+  [!include[](includes/6-exercise.md)]
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/6-knowledge-check.yml b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/6-knowledge-check.yml
@@ -0,0 +1,50 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.prompt-versioning-genaiops.knowledge-check
+title: Knowledge check
+metadata:
+  title: Knowledge check
+  description: "Knowledge check for prompt versioning module"
+  ms.date: 01/26/2026
+  author: madiepev
+  ms.author: madiepev
+  ms.topic: unit
+  ms.custom:
+  - N/A
+  module_assessment: true
+durationInMinutes: 3
+quiz:
+  title: ""
+  questions:
+  - content: "What happens when you create or update an agent in Microsoft Foundry?"
+    choices:
+    - content: "The existing agent version is overwritten with no history."
+      isCorrect: false
+      explanation: "Incorrect. Microsoft Foundry preserves agent version history."
+    - content: "A new agent version is created automatically, whether you use the portal or the Python SDK."
+      isCorrect: true
+      explanation: "Correct. Microsoft Foundry creates a new version whenever you create or update an agent, maintaining version history."
+    - content: "Version numbers must be manually assigned in your code."
+      isCorrect: false
+      explanation: "Incorrect. Microsoft Foundry automatically assigns incremental version numbers."
+  - content: "In a proper prompt workflow, what should happen before a prompt change reaches production?"
+    choices:
+    - content: "Changes should be deployed immediately to get real user feedback."
+      isCorrect: false
+      explanation: "Incorrect. Deploying directly to production skips critical validation steps."
+    - content: "Changes should be tested in development, validated in staging, reviewed by the team, and then deployed with monitoring."
+      isCorrect: true
+      explanation: "Correct. This systematic approach ensures changes are validated at each stage before impacting users."
+    - content: "Only the person who wrote the prompt needs to approve it."
+      isCorrect: false
+      explanation: "Incorrect. Team review provides valuable perspective and catches issues the author might miss."
+  - content: "What do Git tags provide for agent deployments?"
+    choices:
+    - content: "They automatically deploy agents to production."
+      isCorrect: false
+      explanation: "Incorrect. Git tags mark versions but don't trigger deployments by themselves."
+    - content: "They create a traceable relationship between repository versions and deployed agents, simplifying debugging and rollback."
+      isCorrect: true
+      explanation: "Correct. Git tags enable you to quickly identify which repository state corresponds to any deployed agent version."
+    - content: "They replace the need for commit messages."
+      isCorrect: false
+      explanation: "Incorrect. Tags complement commit messages by marking specific deployment milestones."
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/7-summary.yml b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/7-summary.yml
@@ -0,0 +1,15 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.prompt-versioning-genaiops.summary
+title: Summary
+metadata:
+  title: Summary
+  description: "Summary of prompt versioning for GenAIOps"
+  ms.date: 01/07/2026
+  author: madiepev
+  ms.author: madiepev
+  ms.topic: unit
+  ms.custom:
+  - N/A
+durationInMinutes: 2
+content: |
+  [!include[](includes/7-summary.md)]
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/1-introduction.md b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/1-introduction.md
@@ -0,0 +1,12 @@
+
+Quick prompt changes that break AI agents in production are hard to debug. Many teams struggle with managing prompt versions safely, leading to unexpected behavior, and difficult rollbacks.
+
+## Scenario
+
+Consider a customer service team at a software company that uses Microsoft Foundry to power their AI chat agent. Last month, someone updated the agent's system prompt to sound more friendly, but it caused the agent to give inconsistent responses to technical questions. The team couldn't figure out exactly what changed or quickly revert to the previous working version. Customer satisfaction dropped, and it took days to manually recreate a stable prompt from memory.
+
+This scenario illustrates multiple challenges: lack of version control, missing approval workflows, inadequate testing, and poor knowledge management. These problems could be prevented with proper prompt versioning using GitHub, where changes are tracked, tested, and deployed systematically.
+
+## What you learn
+
+In this module, you learn how to work with GitHub and Microsoft Foundry to version and deploy AI agent prompts. You explore one approach for organizing your repository structure for collaboration. While multiple organizational strategies exist, this example demonstrates core concepts you can adapt to your needs. You also learn how to develop a safe workflow for testing and deploying prompt changes.
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/2-version-control-for-prompts.md b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/2-version-control-for-prompts.md
@@ -0,0 +1,49 @@
+Prompt changes in production AI systems require the same systematic management approach as traditional software code changes.
+
+In the customer service team scenario, someone updated the agent's system prompt without any tracking or approval process. The team couldn't identify what changed, who made the change, or how to quickly restore the working version. This chaos could be prevented with proper version control.
+
+Here, you learn why prompts are production-critical assets, how established DevOps practices apply to prompt management, and what problems arise without systematic version control.
+
+## Understand why prompts need the same care as code
+
+Every prompt you write in Microsoft Foundry becomes a live configuration controlling how your AI system behaves. When users interact with your agent, your prompt shapes every response: affecting accuracy, tone, safety, and even cost.
+
+Unlike traditional software where code goes through compilation and testing, prompt changes take effect instantly. Change one word, and you immediately change how thousands of users experience your system. These factors make prompts production-critical assets that deserve the same careful management as any other system component.
+
+## Apply Development Operations (DevOps) practices for prompt management
+
+Software teams solved similar challenges decades ago. Here's how established Development Operations (DevOps) practices translate to prompt management:
+
+| DevOps Practices | Traditional Software | For AI Prompts |
+|-----------------|---------------------|----------------|
+| **Source control and versioning** | Track every change to files with complete history, so you can see what changed, when, and why | Version every prompt iteration so you can compare changes, understand evolution, and revert when needed. Instead of editing prompts directly in Foundry, you store them in GitHub with full change history |
+| **Code reviews and team validation** | Require team approval before changes reach production to catch issues early | Review prompt changes before deployment to verify they maintain accuracy, safety, and brand voice. Multiple eyes on changes prevent "small tweaks" from breaking system behavior |
+| **Environment separation** | Test changes in isolated environments before they affect real users | Validate prompt changes in development environments before deploying to production. Environment separation prevents untested prompts from reaching customers |
+| **Roll back capabilities** | Quickly revert to previous working versions when problems arise | Restore previous prompt versions instantly when issues occur. No more reconstructing prompts from memory during outages |
+
+## Identify what goes wrong without proper management
+
+Without proper management, predictable failures emerge:
+
+> [!WARNING]
+> These common failures can severely harm your AI system's reliability and user trust.
+
+- **Silent degradation**: A "harmless" wording change reduces accuracy across scenarios, but you don't notice until users complain
+- **Environment drift**: Development works perfectly, but production behaves differently because someone updated the prompt in one environment but not the other  
+- **Crisis recovery**: Production breaks, but you can't restore the working version because changes weren't tracked
+- **Lost knowledge**: Months later, you remove "unnecessary" instructions that were critical safety measures
+
+## Achieve systematic prompt operations
+
+Version control transforms prompt chaos into systematic operations:
+
+- **Intentional changes**: Every modification goes through review and validation
+- **Traceable problems**: When issues arise, you can see exactly what changed and when
+- **Instant recovery**: Roll back to working versions in seconds, not hours
+- **Team coordination**: Everyone works from the same prompt versions across all environments
+- **Audit trail**: Complete history of who changed what and why
+
+> [!TIP]
+> This systematic approach gives you confidence to iterate quickly while maintaining reliability. Changes become improvements, not risks.
+
+Now that you understand why version control matters for prompts, you're ready to explore how Microsoft Foundry manages agent versions and how your prompts integrate with agent definitions.
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/3-foundry-agents-prompt-versioning.md b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/3-foundry-agents-prompt-versioning.md
@@ -0,0 +1,105 @@
+Prompts in Microsoft Foundry exist as part of agent definitions, where each agent combines a language model with system instructions that define its behavior.
+
+In the customer service scenario, the team's agent prompt controlled how the system responded to customer inquiries. When they modified that prompt to sound more casual, they changed a core component of the agent definition, but without understanding how to version and track those changes properly.
+
+Here, you learn how prompts integrate with Microsoft Foundry agent architecture, how to deploy agents programmatically with the Python SDK, and how to compare different agent versions in the portal.
+
+## Understand Microsoft Foundry agents
+
+Microsoft Foundry agents are AI-powered assistants that combine large language models with custom instructions to perform specific tasks. Each agent consists of several key components:
+
+| Component | Purpose | Example |
+|-----------|---------|---------|
+| **Agent definition** | Identifies the agent with name and metadata | `trail-guide` with version number |
+| **System instructions** | The prompt that defines agent behavior and capabilities | Instructions for trail recommendations and safety guidance |
+| **Model selection** | The underlying AI model powering responses | GPT-4.1 or other available models |
+| **Tool integrations** | Optional connections to external services or data | Weather APIs, trail databases |
+
+The system instructions, your prompt, represent the most frequently changed component. While you rarely modify the model or tools, you continuously refine prompts to improve accuracy, add capabilities, or adjust tone.
+
+## Recognize how prompts define agent behavior
+
+Your prompt serves as the agent's operational manual. Consider how different prompts create different agent behaviors:
+
+**Version 1 - Basic functionality:**
+```
+You are a trail guide assistant. Help users find hiking trails and provide basic safety advice.
+```
+
+**Version 2 - Enhanced capabilities:**
+```
+You are an experienced trail guide assistant. Help users discover hiking trails matched to their experience level. Provide personalized recommendations based on their preferences, fitness level, and available time. Include essential safety guidance and gear recommendations.
+```
+
+**Version 3 - Production-ready:**
+```
+You are an expert trail guide assistant with deep knowledge of hiking safety and trail conditions. When helping users plan hikes:
+
+1. Assess their experience level and fitness
+2. Consider weather and seasonal factors
+3. Recommend appropriate trails with difficulty ratings
+4. Provide comprehensive gear lists
+5. Include safety protocols and emergency contacts
+6. Suggest alternative options for different conditions
+
+Always prioritize user safety and provide actionable, specific guidance.
+```
+
+> [!NOTE]
+> Each version maintains the same agent name and configuration but delivers progressively enhanced user experiences through prompt refinement.
+
+## Deploy agents programmatically
+
+Microsoft Foundry creates a new agent version whenever you create or update an agent, whether through the portal interface or the Python SDK. The SDK approach enables better version control integration by storing prompts in files that Git can track:
+
+```python
+from azure.ai.projects import AIProjectClient
+from azure.identity import DefaultAzureCredential
+
+# Initialize client
+project_client = AIProjectClient.from_connection_string(
+    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
+    credential=DefaultAzureCredential()
+)
+
+# Read prompt from version-controlled file
+with open('prompts/v1_instructions.txt', 'r') as f:
+    instructions = f.read().strip()
+
+# Create agent with versioned prompt
+agent = project_client.agents.create_agent(
+    model=os.environ["MODEL_NAME"],
+    name=os.environ["AGENT_NAME"],
+    instructions=instructions
+)
+
+print(f"Agent created (id: {agent.id}, version: 1)")
+```
+
+This approach separates prompt content from deployment code:
+
+- **Prompt files** (`v1_instructions.txt`, `v2_instructions.txt`) contain the system instructions
+- **Deployment script** (`trail_guide_agent.py`) reads and deploys the prompt
+- **Version control** tracks changes to both prompts and deployment configurations
+
+> [!NOTE]
+> This approach separates prompts into dedicated files, but organizations use different strategies based on their needs:
+> - **Embedded prompts**: Store prompts directly in Python scripts as strings. Simple for small teams but harder to review prompt-only changes.
+> - **Separate files**: Store prompts in `.txt` or `.md` files (shown here). Better for nontechnical reviewers and clearer version history.
+> - **Configuration management**: Store prompts in YAML or JSON with metadata. Good for complex deployments with multiple environments.
+> 
+> Consider your team's technical expertise, review processes, and deployment complexity when choosing an approach.
+
+## Evaluate version comparison workflows
+
+When you deploy multiple agent versions, you gain powerful comparison capabilities:
+
+- **Test identical scenarios** across versions to measure improvement
+- **Compare responses** to the same user questions
+- **Identify regressions** where newer versions perform worse
+- **Document evolution** showing how prompts developed over time
+
+You can switch between deployed agent versions through both the Microsoft Foundry portal and the Python SDK. In the portal, select different versions and observe how the same input produces different outputs. Through the SDK, list all agent versions programmatically to automate comparison workflows. This directly demonstrates prompt impact on behavior.
+
+Now that you understand how Microsoft Foundry manages agent versions, you're ready to explore how to organize these prompts and deployment scripts in a GitHub repository.
+
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/4-github-repository-structure.md b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/4-github-repository-structure.md
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/5-prompt-workflow-development.md b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/5-prompt-workflow-development.md
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/6-exercise.md b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/6-exercise.md
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/7-summary.md b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/includes/7-summary.md
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/index.yml b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/index.yml
diff --git a/learn-pr/wwl-data-ai/prompt-versioning-genaiops/media/launch-exercise.png b/learn-pr/wwl-data-ai/prompt-versioning-genaiops/media/launch-exercise.png
