Merge branch 'dotnet:main' into main

Author: bigboybamo

.github/CODEOWNERS

@@ -55,7 +55,7 @@
 /docs/machine-learning/ @gewarren @luisquintanilla @JakeRadMSFT @dotnet/docs
 
 # The .NET Architecture Guide:
-/docs/architecture/ @nishanil @IEvangelist @dotnet/docs
+/docs/architecture/ @IEvangelist @dotnet/docs
 
 # .NET Orleans
 /docs/orleans/ @IEvangelist @dotnet/docs
@@ -120,9 +120,9 @@
 # Testing
 /docs/core/testing/ @IEvangelist @dotnet/docs
 # Tools
-/docs/core/tools/ @adegeo @dotnet/docs
+/docs/core/tools/ @meaghanlewis @dotnet/docs
 # Tutorials
-/docs/core/tutorials/ @BillWagner @dotnet/docs
+/docs/core/tutorials/ @meaghanlewis @dotnet/docs
 # What's new
 /docs/core/whats-new/ @dotnet/docs
 

.github/prompts/breaking-change.md

@@ -1,61 +1,98 @@
-When you're assigned an issue that's labeled "breaking-change", or when you're given a link to an issue with this prompt file as context and asked to create a new breaking change document, follow these guidelines:
+# Copilot-Optimized Instructions: Breaking Change Documentation
 
-The document should be in Markdown format.
+## When to use this prompt
 
-Ignore all breaking change documentation under https://github.com/dotnet/docs/tree/main/docs/framework/migration-guide - that's for legacy .NET Framework breaking changes. Modern .NET breaking changes live in the https://github.com/dotnet/docs/tree/main/docs/core/compatibility folder and its subfolders.
+- If assigned an issue labeled `breaking-change`  
+- If given a link to an issue referencing this prompt and asked to create a breaking change document
 
-Rephrase all content to be clear and concise, if necessary.
+## General rules
 
-Describe previous behavior in past tense and new behavior in present tense.
+- **Format:** Use Markdown
+- **Scope:**  
+  - Ignore docs under [`docs/framework/migration-guide`](https://github.com/dotnet/docs/tree/main/docs/framework/migration-guide) (for legacy .NET Framework)  
+  - Document ONLY modern .NET breaking changes
+- **Writing style:**  
+  - Make content clear and concise  
+  - Previous behavior: **past tense**  
+  - New behavior: **present tense**
 
-The document should start with the following header, including --- characters. Placeholder text is shown in angle brackets.
+## Document structure
 
-   ---
-   title: "Breaking change - <A concise descriptive title of the breaking change>"
-   description: "Learn about the breaking change in <product/version without the preview number> where <very brief description>."
-   ms.date: <Today's date>
-   ai-usage: ai-assisted
-   ms.custom: <URL of the issue>
-   ---
+Start with this header (replace placeholders):
 
-After the header, include the following sections in this order. Use the description in parentheses as a guide for the content of each section.
+```
+---
+title: "Breaking change - <Concise descriptive title>"
+description: "Learn about the breaking change in <product/version without preview> where <brief description>."
+ms.date: <Today's date in MM/DD/YYYY format>
+ai-usage: ai-assisted
+ms.custom: <URL of the issue>
+---
+```
+> **Note:** Use today's date in the format MM/DD/YYYY. This date cannot be earlier than 9/29/2025.
 
-h1: "(The same title used in the document header, sans 'Breaking Change - ')"
+Then include these sections in this order:
 
-   (An introductory paragraph summarizing the breaking change. Include the major version but not the preview number.)
+### 1. H1 Title
 
-h2: Version introduced
+- Use the header title, **removing "Breaking change - "**.
 
-   (The version in which the breaking change was introduced. Include the preview number here, if given.)
+**Intro paragraph:**  
+Summarize the breaking change. Include the major version (omit preview number).
 
-h2: Previous behavior
+### 2. Version introduced
 
-   (A brief description of the behavior before the change, including an example code snippet if applicable.)
+- Version where change was introduced (include preview number if applicable).
 
-h2: New behavior
+### 3. Previous behavior
 
-   (A brief description of the behavior after the change, including an example code snippet if applicable.)
+- Briefly describe past behavior.
+- Include example code snippets if relevant.
 
-h2: Type of breaking change
+### 4. New behavior
 
-   If the type of breaking change is "behavioral change", add the following sentence (without the backticks): `This is a [behavioral change](../../categories.md#behavioral-change).`
+- Briefly describe new behavior.
+- Include example code snippets if relevant.
 
-   If the type of breaking change is "source incompatible" or "binary incompatible", add the following sentence (without the backticks): `This change can affect [source compatibility](../../categories.md#source-compatibility).` or `This change can affect [binary compatibility](../../categories.md#binary-compatibility).`
+### 5. Type of breaking change
 
-   If the issue lists multiple types of breaking changes, create a single sentence that links to each applicable type, such as "This is both a []() and []() change.". If there is no type of breaking change selected in the issue, write "TODO: Add type of breaking change."
+- If **behavioral change**:  
+  `This is a [behavioral change](../../categories.md#behavioral-change).`
+- If **source or binary incompatible**:  
+  `This change can affect [source compatibility](../../categories.md#source-incompatible) and/or [binary compatibility](../../categories.md#binary-incompatible).`
+- If multiple types:  
+  Link to each type in a single sentence.
+- If none specified:  
+  State "No specific type listed."
 
-h2: Reason for change
+### 6. Reason for change
 
-   (The complete reasoning behind the change, including any relevant links.)
+- Explain why the change was made.
+- Include relevant links.
 
-h2: Recommended action
+### 7. Recommended action
 
-   (A brief description of the action or actions that users should take, including example code snippets if applicable.)
+- Describe what users should do to adapt.
+- Include code examples if helpful.
 
-h2: Affected APIs
+### 8. Affected APIs
 
-   (A bullet list of APIs that are affected by the change. If there are no affected APIs (or "No response") write "None.". Use xref-style links as described in the copilot-instructions.md file. At the end of each doc ID, add "?displayProperty=fullName", for example "<xref:System.String?displayProperty=fullName>".)
+- Bullet list of affected APIs.
+- Use **xref-style links** as described in `copilot-instructions.md`.
+- If none: Write "None."
 
-Then, add the new document to the TOC file located at https://github.com/dotnet/docs/blob/main/docs/core/compatibility/toc.yml. Also add an entry to the index file under the appropriate area H2 heading in the https://github.com/dotnet/docs/blob/main/docs/core/compatibility/10.0.md file by adding a row to the table (create a new heading/table if it doesn't exist yet).
+## Final steps
 
-Next, create a pull request. In the description, include the text "Fixes #\<issue-number>", where "issue-number" is the GitHub issue number.
+- **Add the new doc to the [TOC file](https://github.com/dotnet/docs/blob/main/docs/core/compatibility/toc.yml).**
+- **Add an entry to the index file under the appropriate area H2 heading.**
+- **Create a pull request.**
+  - In the description, include: `Fixes #<issue-number>` (replace with the correct number).
+  - Request review on the pull request from the person who opened the issue.
+- Also check the relevant API docs, if applicable, and update them in the https://github.com/dotnet/dotnet-api-docs repo to reflect the breaking change.
+
+---
+
+**Copilot optimization notes:**  
+- All steps and formatting are condensed and clarified for rapid, accurate document drafting.
+- Section ordering and linking instructions are explicit for automation.
+- Xref/linking and PR closing instructions are surfaced for easy action.

.github/workflows/dependency-review.yml

@@ -24,4 +24,4 @@ jobs:
       - name: 'Checkout Repository'
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@595b5aeba73380359d98a5e087f648dbb0edce1b # v4.7.3
+        uses: actions/dependency-review-action@56339e523c0409420f6c2c9a2f4292bbb3c07dd3 # v4.8.0

.github/workflows/scorecards.yml

@@ -41,7 +41,7 @@ jobs:
           persist-credentials: false
 
       - name: "Run analysis"
-        uses: ossf/scorecard-action@05b42c624433fc40578a4040d5cf5e36ddca8cde # v2.4.2
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
         with:
           results_file: results.sarif
           results_format: sarif
@@ -71,6 +71,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@192325c86100d080feab897ff886c34abd4c83a3 # v3.29.5
+        uses: github/codeql-action/upload-sarif@3599b3baa15b485a2e49ef411a7a4bb2452e7f93 # v3.29.5
         with:
           sarif_file: results.sarif

.openpublishing.redirection.ai.json

@@ -9,10 +9,6 @@
             "redirect_url": "/dotnet/ai/microsoft-extensions-ai",
             "redirect_document_id": true
         },
-        {
-            "source_path_from_root": "/docs/ai/conceptual/agents.md",
-            "redirect_url": "/dotnet/ai"
-        },
         {
             "source_path_from_root": "/docs/ai/conceptual/evaluation-libraries.md",
             "redirect_url": "/dotnet/ai/evaluation/libraries",

docfx.json

@@ -365,8 +365,8 @@
                 "docs/core/project-sdk/**/**.md": "gewarren",
                 "docs/core/runtime-config/**/**.md": "gewarren",
                 "docs/core/testing/**/**.md": "IEvangelist",
-                "docs/core/tools/**/**.md": "adegeo",
-                "docs/core/tutorials/**/**.md": "billwagner",
+                "docs/core/tools/**/**.md": "meaghanlewis",
+                "docs/core/tutorials/**/**.md": "meaghanlewis",
                 "docs/core/versions/**/**.md": "billwagner",
                 "docs/core/whats-new/**/**.md": "gewarren",
                 "docs/csharp/**/*.*": "billwagner",
@@ -458,8 +458,8 @@
                 "docs/core/project-sdk/**/**.md": "gewarren",
                 "docs/core/runtime-config/**/**.md": "gewarren",
                 "docs/core/testing/**/**.md": "dapine",
-                "docs/core/tools/**/**.md": "adegeo",
-                "docs/core/tutorials/**/**.md": "wiwagn",
+                "docs/core/tools/**/**.md": "mosagie",
+                "docs/core/tutorials/**/**.md": "mosagie",
                 "docs/core/versions/**/**.md": "wiwagn",
                 "docs/core/whats-new/**/**.md": "gewarren",
                 "docs/csharp/**/*.*": "wiwagn",

docs/ai/conceptual/agents.md

@@ -0,0 +1,96 @@
+---
+title: Agents
+description: Introduction to agents
+author: luisquintanilla
+ms.author: luquinta
+ms.date: 10/01/2025
+ms.topic: concept-article
+---
+
+# Agents
+
+This article introduces the core concepts behind agents, why they matter, and how they fit into workflows, setting you up to get started building agents in .NET.
+
+## What are agents?
+
+**Agents are systems that accomplish objectives.**
+
+![Components of an agent](../media/agents/agent-components.png)
+
+Agents become more capable when equipped with the following:
+
+- **Reasoning and decision-making**: Powered by LLMs, search algorithms, or planning and decision-making systems.
+- **Tool usage**: Access to Model Context Protocol (MCP) servers, code execution, and external APIs.
+- **Context awareness**: Informed by chat history, threads, vector stores, enterprise data, or knowledge graphs.
+
+These capabilities allow agents to operate more autonomously, adaptively, and intelligently.
+
+## What are workflows?
+
+As objectives grow in complexity, they need to be broken down into manageable steps. That's where workflows come in.
+
+**Workflows define the sequence of steps required to achieve an objective.**
+
+Imagine you're launching a new feature on your business website. If it's a simple update, you might go from idea to production in a few hours. But for more complex initiatives, the process might include:
+
+- Requirement gathering
+- Design and architecture
+- Implementation
+- Testing
+- Deployment
+
+A few important observations:
+
+- Each step might contain subtasks.
+- Different specialists might own different phases.
+- Progress isn’t always linear. Bugs found during testing might send you back to implementation.
+- Success depends on planning, orchestration, and communication across stakeholders.
+
+### Agents + workflows = agentic workflows
+
+Workflows don't require agents, but agents can supercharge them.
+
+When agents are equipped with reasoning, tools, and context, they can optimize workflows.
+
+This is the foundation of multi-agent systems, where agents collaborate within workflows to achieve complex goals.
+
+### Workflow orchestration
+
+Agentic workflows can be orchestrated in a variety of ways. The following are a few of the most common:
+
+- [Sequential](#sequential)
+- [Concurrent](#concurrent)
+- [Handoff](#handoff)
+- [Group chat](#group-chat)
+
+#### Sequential
+
+Agents process tasks one after another, passing results forward.
+
+![Sequential agent orchestration: Task Input → Agent A → Agent B → Agent C → Final Output](../media/agents/sequential-workflow.png)
+
+#### Concurrent
+
+Agents work in parallel, each handling different aspects of the task.
+
+![Concurrent agent orchestration: Task Input → Agents A, B, C → Aggregate Results → Final Output](../media/agents/concurrent-workflow.png)
+
+#### Handoff
+
+Responsibility shifts from one agent to another based on conditions or outcomes.
+
+![Handoff orchestration: Task Input → Agent A Decision → Agent B or Agent A → Agent B Decision → Agent C or Agent B → Final Output](../media/agents/handoff-workflow.png)
+
+#### Group chat
+
+Agents collaborate in a shared conversation, exchanging insights in real-time.
+
+![Group chat orchestration: User and Agents A, B, C collaborate via GroupChat to produce final output](../media/agents/groupchat-workflow.png)
+
+## How can I get started building agents in .NET?
+
+The building blocks in <xref:Microsoft.Extensions.AI> and <xref:Microsoft.Extensions.VectorData> supply the foundations for agents by providing modular components for AI models, tools, and data.
+
+These components serve as the foundation for Microsoft Agent Framework.
+
+For more information, see [Microsoft Agent Framework](/agent-framework/overview/agent-framework-overview).

docs/ai/evaluation/snippets/evaluate-ai-responses/TestAI.csproj

@@ -11,14 +11,14 @@
   <ItemGroup>
     <PackageReference Include="Azure.AI.OpenAI" Version="2.1.0" />
     <PackageReference Include="Azure.Identity" Version="1.16.0" />
-    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" Version="9.9.0" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" Version="9.9.1" />
     <PackageReference Include="Microsoft.Extensions.AI.Evaluation" Version="9.9.0" />
     <PackageReference Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="9.9.0" />
     <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.4.0-preview.1.25207.5" />
     <PackageReference Include="Microsoft.Extensions.Configuration" Version="9.0.9" />
     <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="9.0.9" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
-    <PackageReference Include="MSTest" Version="3.10.4" />
+    <PackageReference Include="MSTest" Version="3.11.0" />
   </ItemGroup>
 
   <ItemGroup>

docs/ai/how-to/snippets/hosted-app-auth/hosted-app-auth.csproj

@@ -11,9 +11,9 @@
     <PackageReference Include="Azure.AI.OpenAI" Version="2.1.0" />
     <PackageReference Include="Azure.Identity" Version="1.16.0" />
     <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.9" />
-    <PackageReference Include="Microsoft.Extensions.AI" Version="9.9.0" />
+    <PackageReference Include="Microsoft.Extensions.AI" Version="9.9.1" />
     <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.4.0-preview.1.25207.5" />
-    <PackageReference Include="Microsoft.Extensions.Azure" Version="1.12.0" />
+    <PackageReference Include="Microsoft.Extensions.Azure" Version="1.13.0" />
   </ItemGroup>
 
 </Project>

docs/ai/index.yml

@@ -27,6 +27,8 @@ landingContent:
             url: overview.md
           - text: Microsoft.Extensions.AI libraries
             url: microsoft-extensions-ai.md
+          - text: Microsoft Agent Framework
+            url: /agent-framework/overview/agent-framework-overview?toc=/dotnet/ai/toc.json&bc=/dotnet/ai/toc.json
       - linkListType: get-started
         links:
           - text: Connect to and prompt an AI model