Merge pull request #403 from microsoft/docs/01-intro-to-ai-agents

Update 01-dotnet-agent-framework

Author: koreyspace

.github/prompts/git-cherrypicking.prompt.md

@@ -0,0 +1,21 @@
+---
+description: 'Cherrypick a file deleted from the given commit between branches using Git.'
+mode: 'agent'
+---
+
+# Cherry-picking a File Between Branches Using Git
+
+Your goal is to cherry-pick a specific file deleted from a given commit between branches in a Git repository. Use the Git command line interface to accomplish this task.
+
+## Inputs
+
+- **Commit Hash**: $COMMIT - The hash of the commit from which to cherry-pick the file.
+- **File Path**: $FILE_PATH - The path of the file to be cherry-picked.
+
+If you don't have the commit hash or file path, please ask the user for these details.
+
+## Instructions
+
+1. **Identify the Commit**: Determine the commit hash from which you want to cherry-pick the file.
+2. **Cherry-pick the File**: Use the `git checkout` command to cherry-pick the specific file from the identified commit. If the file doesn't exist in the given commit, find the closest commit where the file exists.
+3. **Commit the Changes**: Ask the user to stage and commit the changes to finalize the cherry-pick.

01-intro-to-ai-agents/README.md

@@ -101,11 +101,14 @@ Agentic Frameworks allow developers to implement agentic patterns through code.
 
 In this course, we will explore the research-driven AutoGen framework and the production-ready Agent framework from Semantic Kernel.
 
-### Got More Questions about AI Agents?
+## Sample Codes
 
-Join the [Azure AI Foundry Discord](https://aka.ms/ai-agents/discord) to meet with other learners, attend office hours and get your AI Agents questions answered.
+- Python: [Agent Framework](./code_samples/01-python-agent-framework.ipynb)
+- .NET: [Agent Framework](./code_samples/01-dotnet-agent-framework.md)
 
+## Got More Questions about AI Agents?
 
+Join the [Azure AI Foundry Discord](https://aka.ms/ai-agents/discord) to meet with other learners, attend office hours and get your AI Agents questions answered.
 
 ## Previous Lesson
 

01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs

@@ -1,26 +1,25 @@
 #!/usr/bin/dotnet run
 
-#:package Microsoft.Extensions.AI@9.9.1
-#:package Microsoft.Agents.AI.OpenAI@1.0.0-preview.251001.3
-#:package Microsoft.Agents.AI@1.0.0-preview.251001.3
-#:package DotNetEnv@3.1.1
+#:package Microsoft.Extensions.AI@9.*
+#:package Microsoft.Agents.AI.OpenAI@1.*-*
 
-using System;
-using System.ComponentModel;
 using System.ClientModel;
-using System.Collections.Generic;
-using Microsoft.Extensions.AI;
+using System.ComponentModel;
+
 using Microsoft.Agents.AI;
-using OpenAI;
-using DotNetEnv;
+using Microsoft.Extensions.AI;
 
-// Load environment variables from .env file (3 directories up)
-Env.Load("../../../.env");
+using OpenAI;
 
 // Tool Function: Random Destination Generator
+// This static method will be available to the agent as a callable tool
+// The [Description] attribute helps the AI understand when to use this function
+// This demonstrates how to create custom tools for AI agents
 [Description("Provides a random vacation destination.")]
 static string GetRandomDestination()
 {
+    // List of popular vacation destinations around the world
+    // The agent will randomly select from these options
     var destinations = new List<string>
     {
         "Paris, France",
@@ -34,38 +33,52 @@ static string GetRandomDestination()
         "Bangkok, Thailand",
         "Vancouver, Canada"
     };
+
+    // Generate random index and return selected destination
+    // Uses System.Random for simple random selection
     var random = new Random();
     int index = random.Next(destinations.Count);
     return destinations[index];
 }
 
 // Extract configuration from environment variables
-var github_endpoint = Environment.GetEnvironmentVariable("GITHUB_ENDPOINT") ?? throw new InvalidOperationException("GITHUB_ENDPOINT is not set.");
-var github_model_id = Environment.GetEnvironmentVariable("GITHUB_MODEL_ID") ?? "gpt-4o-mini";
-var github_token = Environment.GetEnvironmentVariable("GITHUB_TOKEN") ?? throw new InvalidOperationException("GITHUB_TOKEN is not set.");
+// Retrieve the GitHub Models API endpoint, defaults to https://models.github.ai/inference if not specified
+// Retrieve the model ID, defaults to openai/gpt-5-mini if not specified
+// Retrieve the GitHub token for authentication, throws exception if not specified
+var github_endpoint = Environment.GetEnvironmentVariable("GH_ENDPOINT") ?? "https://models.github.ai/inference";
+var github_model_id = Environment.GetEnvironmentVariable("GH_MODEL_ID") ?? "openai/gpt-5-mini";
+var github_token = Environment.GetEnvironmentVariable("GH_TOKEN") ?? throw new InvalidOperationException("GH_TOKEN is not set.");
 
 // Configure OpenAI Client Options
+// Create configuration options to point to GitHub Models endpoint
+// This redirects OpenAI client calls to GitHub's model inference service
 var openAIOptions = new OpenAIClientOptions()
 {
     Endpoint = new Uri(github_endpoint)
 };
 
 // Initialize OpenAI Client with GitHub Models Configuration
+// Create OpenAI client using GitHub token for authentication
+// Configure it to use GitHub Models endpoint instead of OpenAI directly
 var openAIClient = new OpenAIClient(new ApiKeyCredential(github_token), openAIOptions);
 
 // Create AI Agent with Travel Planning Capabilities
+// Initialize OpenAI client, get chat client for specified model, and create AI agent
+// Configure agent with travel planning instructions and random destination tool
+// The agent can now plan trips using the GetRandomDestination function
 AIAgent agent = openAIClient
     .GetChatClient(github_model_id)
     .CreateAIAgent(
         instructions: "You are a helpful AI Agent that can help plan vacations for customers at random destinations",
         tools: [AIFunctionFactory.Create(GetRandomDestination)]
     );
 
-// Execute Agent: Plan a Day Trip (Non-Streaming)
-Console.WriteLine(await agent.RunAsync("Plan me a day trip"));
-
-// Execute Agent: Plan a Day Trip (Streaming Response)
+// Execute Agent: Plan a Day Trip
+// Run the agent with streaming enabled for real-time response display
+// Shows the agent's thinking and response as it generates the content
+// Provides better user experience with immediate feedback
 await foreach (var update in agent.RunStreamingAsync("Plan me a day trip"))
 {
+    await Task.Delay(10);
     Console.Write(update);
 }

01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.md

@@ -4,7 +4,8 @@
 
 This notebook demonstrates how to build an intelligent travel planning agent using the Microsoft Agent Framework for .NET. The agent can automatically generate personalized day-trip itineraries for random destinations around the world.
 
-**Key Capabilities:**
+### Key Capabilities:
+
 - 🎲 **Random Destination Selection**: Uses a custom tool to pick vacation spots
 - 🗺️ **Intelligent Trip Planning**: Creates detailed day-by-day itineraries
 - 🔄 **Real-time Streaming**: Supports both immediate and streaming responses
@@ -13,18 +14,21 @@ This notebook demonstrates how to build an intelligent travel planning agent usi
 ## 🔧 Technical Architecture
 
 ### Core Technologies
+
 - **Microsoft Agent Framework**: Latest .NET implementation for AI agent development
 - **GitHub Models Integration**: Uses GitHub's AI model inference service
 - **OpenAI API Compatibility**: Leverages OpenAI client libraries with custom endpoints
 - **Secure Configuration**: Environment-based API key management
 
 ### Key Components
+
 1. **AIAgent**: The main agent orchestrator that handles conversation flow
 2. **Custom Tools**: `GetRandomDestination()` function available to the agent
 3. **Chat Client**: GitHub Models-backed conversation interface
 4. **Streaming Support**: Real-time response generation capabilities
 
 ### Integration Pattern
+
 ```mermaid
 graph LR
     A[User Request] --> B[AI Agent]
@@ -36,35 +40,68 @@ graph LR
 
 ## 🚀 Getting Started
 
-**Prerequisites:**
-- .NET 10.0 or higher
-- GitHub Models API access token
-- Environment variables configured in `.env` file
+### Prerequisites
+
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or higher
+- [GitHub Models API access token](https://docs.github.com/github-models/github-models-at-scale/using-your-own-api-keys-in-github-models)
 
-**Required Environment Variables:**
-```env
-GITHUB_TOKEN=your_github_token
-GITHUB_ENDPOINT=https://models.inference.ai.azure.com
-GITHUB_MODEL_ID=gpt-4o-mini
+### Required Environment Variables
+
+```bash
+# zsh/bash
+export GH_TOKEN=<your_github_token>
+export GH_ENDPOINT=https://models.github.ai/inference
+export GH_MODEL_ID=openai/gpt-5-mini
 ```
 
-Run the code sample below in sequence to see the travel agent in action!
+```powershell
+# PowerShell
+$env:GH_TOKEN = "<your_github_token>"
+$env:GH_ENDPOINT = "https://models.github.ai/inference"
+$env:GH_MODEL_ID = "openai/gpt-5-mini"
+```
+
+### Sample Code
 
----
+To run the code example,
 
-## .NET Single File App: AI Travel Agent Example
+```bash
+# zsh/bash
+chmod +x ./01-dotnet-agent-framework.cs
+./01-dotnet-agent-framework.cs
+```
 
-See `01-dotnet-agent-framework.cs` for the complete runnable code sample.
+Or using the dotnet CLI:
 
 ```bash
-dotnet run 01-dotnet-agent-framework.cs
+dotnet run ./01-dotnet-agent-framework.cs
 ```
 
-### Sample Code
+See [`01-dotnet-agent-framework.cs`](./01-dotnet-agent-framework.cs) for the complete code.
 
 ```csharp
+#!/usr/bin/dotnet run
+
+#:package Microsoft.Extensions.AI@9.*
+#:package Microsoft.Agents.AI.OpenAI@1.*-*
+
+using System.ClientModel;
+using System.ComponentModel;
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+using OpenAI;
+
+// Tool Function: Random Destination Generator
+// This static method will be available to the agent as a callable tool
+// The [Description] attribute helps the AI understand when to use this function
+// This demonstrates how to create custom tools for AI agents
+[Description("Provides a random vacation destination.")]
 static string GetRandomDestination()
 {
+    // List of popular vacation destinations around the world
+    // The agent will randomly select from these options
     var destinations = new List<string>
     {
         "Paris, France",
@@ -78,39 +115,53 @@ static string GetRandomDestination()
         "Bangkok, Thailand",
         "Vancouver, Canada"
     };
+
+    // Generate random index and return selected destination
+    // Uses System.Random for simple random selection
     var random = new Random();
     int index = random.Next(destinations.Count);
     return destinations[index];
 }
 
 // Extract configuration from environment variables
-var github_endpoint = Environment.GetEnvironmentVariable("GITHUB_ENDPOINT") ?? throw new InvalidOperationException("GITHUB_ENDPOINT is not set.");
-var github_model_id = Environment.GetEnvironmentVariable("GITHUB_MODEL_ID") ?? "gpt-4o-mini";
-var github_token = Environment.GetEnvironmentVariable("GITHUB_TOKEN") ?? throw new InvalidOperationException("GITHUB_TOKEN is not set.");
+// Retrieve the GitHub Models API endpoint, defaults to https://models.github.ai/inference if not specified
+// Retrieve the model ID, defaults to openai/gpt-5-mini if not specified
+// Retrieve the GitHub token for authentication, throws exception if not specified
+var github_endpoint = Environment.GetEnvironmentVariable("GH_ENDPOINT") ?? "https://models.github.ai/inference";
+var github_model_id = Environment.GetEnvironmentVariable("GH_MODEL_ID") ?? "openai/gpt-5-mini";
+var github_token = Environment.GetEnvironmentVariable("GH_TOKEN") ?? throw new InvalidOperationException("GH_TOKEN is not set.");
 
 // Configure OpenAI Client Options
+// Create configuration options to point to GitHub Models endpoint
+// This redirects OpenAI client calls to GitHub's model inference service
 var openAIOptions = new OpenAIClientOptions()
 {
     Endpoint = new Uri(github_endpoint)
 };
 
 // Initialize OpenAI Client with GitHub Models Configuration
+// Create OpenAI client using GitHub token for authentication
+// Configure it to use GitHub Models endpoint instead of OpenAI directly
 var openAIClient = new OpenAIClient(new ApiKeyCredential(github_token), openAIOptions);
 
 // Create AI Agent with Travel Planning Capabilities
+// Initialize OpenAI client, get chat client for specified model, and create AI agent
+// Configure agent with travel planning instructions and random destination tool
+// The agent can now plan trips using the GetRandomDestination function
 AIAgent agent = openAIClient
     .GetChatClient(github_model_id)
     .CreateAIAgent(
         instructions: "You are a helpful AI Agent that can help plan vacations for customers at random destinations",
         tools: [AIFunctionFactory.Create(GetRandomDestination)]
     );
 
-// Execute Agent: Plan a Day Trip (Non-Streaming)
-Console.WriteLine(await agent.RunAsync("Plan me a day trip"));
-
-// Execute Agent: Plan a Day Trip (Streaming Response)
+// Execute Agent: Plan a Day Trip
+// Run the agent with streaming enabled for real-time response display
+// Shows the agent's thinking and response as it generates the content
+// Provides better user experience with immediate feedback
 await foreach (var update in agent.RunStreamingAsync("Plan me a day trip"))
 {
+    await Task.Delay(10);
     Console.Write(update);
 }
 ```