.NET: Address Feedback on StateBag feature branch PR (#3910)

* Address Feedback on statebag feature branch PR

* Update dotnet/src/Microsoft.Agents.AI.DurableTask/CHANGELOG.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Address PR comments

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

.github/copilot-instructions.md

@@ -1,69 +1,19 @@
 # GitHub Copilot Instructions
 
-This repository contains both Python and C# code.
-All python code resides under the `python/` directory.
-All C# code resides under the `dotnet/` directory.
+Microsoft Agent Framework - a multi-language framework for building, orchestrating, and deploying AI agents.
 
-The purpose of the code is to provide a framework for building AI agents.
+## Repository Structure
 
-When contributing to this repository, please follow these guidelines:
+- `python/` - Python implementation → see [python/AGENTS.md](../python/AGENTS.md)
+- `dotnet/` - C#/.NET implementation → see [dotnet/AGENTS.md](../dotnet/AGENTS.md)
+- `docs/` - Design documents and architectural decision records
 
-## C# Code Guidelines
+## Architectural Decision Records (ADRs)
 
-Here are some general guidelines that apply to all code.
+ADRs in `docs/decisions/` capture significant design decisions and their rationale. They document considered alternatives, trade-offs, and the reasoning behind choices.
 
-- The top of all *.cs files should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.`
-- All public methods and classes should have XML documentation comments.
-- After adding, modifying or deleting code, run `dotnet build`, and then fix any reported build errors.
-- After adding or modifying code, run `dotnet format` to automatically fix any formatting errors.
+**Templates:**
+- `adr-template.md` - Full template with detailed sections
+- `adr-short-template.md` - Abbreviated template for simpler decisions
 
-### C# Sample Code Guidelines
-
-Sample code is located in the `dotnet/samples` directory.
-
-When adding a new sample, follow these steps:
-
-- The sample should be a standalone .net project in one of the subdirectories of the samples directory.
-- The directory name should be the same as the project name.
-- The directory should contain a README.md file that explains what the sample does and how to run it.
-- The README.md file should follow the same format as other samples.
-- The csproj file should match the directory name.
-- The csproj file should be configured in the same way as other samples.
-- The project should preferably contain a single Program.cs file that contains all the sample code.
-- The sample should be added to the solution file in the samples directory.
-- The sample should be tested to ensure it works as expected.
-- A reference to the new samples should be added to the README.md file in the parent directory of the new sample.
-
-The sample code should follow these guidelines:
-
-- Configuration settings should be read from environment variables, e.g. `var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");`.
-- Environment variables should use upper snake_case naming convention.
-- Secrets should not be hardcoded in the code or committed to the repository.
-- The code should be well-documented with comments explaining the purpose of each step.
-- The code should be simple and to the point, avoiding unnecessary complexity.
-- Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions".
-- Ensure that all private classes are sealed
-- Use the Async suffix on the name of all async methods that return a Task or ValueTask.
-- Prefer defining variables using types rather than var, to help users understand the types involved.
-- Follow the patterns in the samples in the same directories where new samples are being added.
-- The structure of the sample should be as follows:
-  - The top of the Program.cs should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.`
-  - Then add a comment describing what the sample is demonstrating.
-  - Then add the necessary using statements.
-  - Then add the main code logic.
-  - Finally, add any helper methods or classes at the bottom of the file.
-
-### C# Unit Test Guidelines
-
-Unit tests are located in the `dotnet/tests` directory in projects with a `.UnitTests.csproj` suffix.
-
-Unit tests should follow these guidelines:
-
-- Use `this.` for accessing class members
-- Add Arrange, Act and Assert comments for each test
-- Ensure that all private classes, that are not subclassed, are sealed
-- Use the Async suffix on the name of all async methods
-- Use the Moq library for mocking objects where possible
-- Validate that each test actually tests the target behavior, e.g. we should not have tests that creates a mock, calls the mock and then verifies that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway.
-- Avoid adding excessive comments to tests. Instead favour clear easy to understand code.
-- Follow the patterns in the unit tests in the same project or classes to which new tests are being added
+When proposing architectural changes, create an ADR to capture options considered and the decision rationale. See [docs/decisions/README.md](../docs/decisions/README.md) for the full process.

.github/workflows/python-check-coverage.py

@@ -30,9 +30,11 @@ from dataclasses import dataclass
 # =============================================================================
 ENFORCED_MODULES: set[str] = {
     "packages.azure-ai.agent_framework_azure_ai",
+    "packages.core.agent_framework",
+    "packages.core.agent_framework._workflows",
+    "packages.purview.agent_framework_purview",
     # Add more modules here as coverage improves:
-    # "packages.core.agent_framework",
-    # "packages.core.agent_framework._workflows",
+    # "packages.azure-ai-search.agent_framework_azure_ai_search",
     # "packages.anthropic.agent_framework_anthropic",
 }
 

.github/workflows/python-code-quality.yml

@@ -12,13 +12,13 @@ env:
   UV_CACHE_DIR: /tmp/.uv-cache
 
 jobs:
-  pre-commit:
-    name: Checks
+  pre-commit-hooks:
+    name: Pre-commit Hooks
     if: "!cancelled()"
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.14"]
+        python-version: ["3.10"]
     runs-on: ubuntu-latest
     continue-on-error: true
     defaults:
@@ -37,16 +37,106 @@ jobs:
           python-version: ${{ matrix.python-version }}
           os: ${{ runner.os }}
         env:
-          # Configure a constant location for the uv cache
           UV_CACHE_DIR: /tmp/.uv-cache
       - uses: actions/cache@v5
         with:
-          path: ~/.cache/pre-commit
-          key: pre-commit|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
-      - uses: pre-commit/action@v3.0.1
-        name: Run Pre-Commit Hooks
+          path: ~/.cache/prek
+          key: prek|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
+      - uses: j178/prek-action@v1
+        name: Run Pre-commit Hooks (excluding poe-check)
+        env:
+          SKIP: poe-check
         with:
-          extra_args: --config python/.pre-commit-config.yaml --all-files
+          extra-args: --cd python --all-files
+
+  package-checks:
+    name: Package Checks
+    if: "!cancelled()"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    defaults:
+      run:
+        working-directory: ./python
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          UV_CACHE_DIR: /tmp/.uv-cache
+      - name: Run fmt, lint, pyright in parallel across packages
+        run: uv run poe check-packages
+
+  samples-markdown:
+    name: Samples & Markdown
+    if: "!cancelled()"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    defaults:
+      run:
+        working-directory: ./python
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          UV_CACHE_DIR: /tmp/.uv-cache
+      - name: Run samples lint
+        run: uv run poe samples-lint
+      - name: Run samples syntax check
+        run: uv run poe samples-syntax
+      - name: Run markdown code lint
+        run: uv run poe markdown-code-lint
+
+  mypy:
+    name: Mypy Checks
+    if: "!cancelled()"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    defaults:
+      run:
+        working-directory: ./python
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          UV_CACHE_DIR: /tmp/.uv-cache
       - name: Run Mypy
         env:
           GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref || github.base_ref || 'main' }}

.github/workflows/python-merge-tests.yml

@@ -96,8 +96,7 @@ jobs:
         uses: ./.github/actions/azure-functions-integration-setup
         id: azure-functions-setup
       - name: Test with pytest
-        timeout-minutes: 10
-        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout 900 --retries 3 --retry-delay 10
+        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
         working-directory: ./python
       - name: Test core samples
         timeout-minutes: 10
@@ -153,8 +152,8 @@ jobs:
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
       - name: Test with pytest
-        timeout-minutes: 10
-        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist loadfile --dist worksteal --timeout 300 --retries 3 --retry-delay 10
+        timeout-minutes: 15
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
         working-directory: ./python
       - name: Test Azure AI samples
         timeout-minutes: 10

.gitignore

@@ -199,8 +199,6 @@ temp*/
 .tmp/
 .temp/
 
-agents.md
-
 # AI
 .claude/
 WARP.md

README.md

@@ -53,7 +53,7 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 ### ✨ **Highlights**
 
 - **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities
-  - [Python workflows](./python/samples/getting_started/workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/Workflows/)
+  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/Workflows/)
 - **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
   - [Labs directory](./python/packages/lab/)
 - **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
@@ -73,11 +73,11 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 - **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
   - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
 - **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
-  - [Python observability](./python/samples/getting_started/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/AgentOpenTelemetry/)
+  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/AgentOpenTelemetry/)
 - **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
-  - [Python examples](./python/samples/getting_started/agents/) | [.NET examples](./dotnet/samples/GettingStarted/AgentProviders/)
+  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/GettingStarted/AgentProviders/)
 - **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
-  - [Python middleware](./python/samples/getting_started/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/)
+  - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/)
 
 ### 💬 **We want your feedback!**
 
@@ -108,7 +108,7 @@ async def main():
         # api_version=os.environ["AZURE_OPENAI_API_VERSION"],
         # api_key=os.environ["AZURE_OPENAI_API_KEY"],  # Optional if using AzureCliCredential
         credential=AzureCliCredential(), # Optional, if using api_key
-    ).create_agent(
+    ).as_agent(
         name="HaikuBot",
         instructions="You are an upbeat assistant that writes beautifully.",
     )
@@ -131,7 +131,7 @@ using OpenAI;
 // Replace the <apikey> with your OpenAI API key.
 var agent = new OpenAIClient("<apikey>")
     .GetOpenAIResponseClient("gpt-4o-mini")
-    .CreateAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+    .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
@@ -150,7 +150,7 @@ var agent = new OpenAIClient(
     new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"),
     new OpenAIClientOptions() { Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1") })
     .GetOpenAIResponseClient("gpt-4o-mini")
-    .CreateAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+    .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
@@ -159,9 +159,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 
 ### Python
 
-- [Getting Started with Agents](./python/samples/getting_started/agents): basic agent creation and tool usage
-- [Chat Client Examples](./python/samples/getting_started/chat_client): direct chat client usage patterns
-- [Getting Started with Workflows](./python/samples/getting_started/workflows): basic workflow creation and integration with agents
+- [Getting Started with Agents](./python/samples/01-get-started): progressive tutorial from hello-world to hosting
+- [Agent Concepts](./python/samples/02-agents): deep-dive samples by topic (tools, middleware, providers, etc.)
+- [Getting Started with Workflows](./python/samples/03-workflows): workflow creation and integration with agents
 
 ### .NET
 

agent-samples/README.md

@@ -1,3 +1,3 @@
 # Declarative Agents
 
-This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/getting_started/declarative/).
+This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/02-agents/declarative/).

docs/decisions/0012-python-typeddict-options.md

@@ -126,4 +126,4 @@ response = await client.get_response(
 
 Chosen option: **"Option 2: TypedDict with Generic Type Parameters"**, because it provides full type safety, excellent IDE support with autocompletion, and allows users to extend provider-specific options for their use cases. Extended this Generic to ChatAgents in order to also properly type the options used in agent construction and run methods.
 
-See [typed_options.py](../../python/samples/getting_started/chat_client/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.
+See [typed_options.py](../../python/samples/02-agents/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.

docs/decisions/0015-agent-run-context.md

@@ -0,0 +1,147 @@
+---
+status: proposed
+contact: westey-m
+date: 2026-01-27
+deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub, lokitoth, alliscode, taochenosu, moonbox3
+consulted: 
+informed: 
+---
+
+# AgentRunContext for Agent Run
+
+## Context and Problem Statement
+
+During an agent run, various components involved in the execution (middleware, filters, tools, nested agents, etc.) may need access to contextual information about the current run, such as:
+
+1. The agent that is executing the run
+2. The session associated with the run
+3. The request messages passed to the agent
+4. The run options controlling the agent's behavior
+
+Additionally, some components may need to modify this context during execution, for example:
+
+- Replacing the session with a different one
+- Modifying the request messages before they reach the agent core
+- Updating or replacing the run options entirely
+
+Currently, there is no standardized way to access or modify this context from arbitrary code that executes during an agent run, especially from deeply nested call stacks where the context is not explicitly passed.
+
+## Sample Scenario
+
+When using an Agent as an AIFunction developers may want to pass context from the parent agent run to the child agent run. For example, the developer may want to copy chat history to the child agent, or share the same session across both agents.
+
+To enable these scenarios, we need a way to access the parent agent run context, including e.g. the parent agent itself, the parent agent session, and the parent run options from function tool calls.
+
+```csharp
+    public static AIFunction AsAIFunctionWithSessionPropagation(this ChatClientAgent agent, AIFunctionFactoryOptions? options = null)
+    {
+        Throw.IfNull(agent);
+
+        [Description("Invoke an agent to retrieve some information.")]
+        async Task<string> InvokeAgentAsync(
+            [Description("Input query to invoke the agent.")] string query,
+            CancellationToken cancellationToken)
+        {
+            // Get the session from the parent agent and pass it to the child agent.
+            var session = AIAgent.CurrentRunContext?.Session;
+
+            // Alternatively, the developer may want to create a new session but copy over the chat history from the parent agent.
+            // var parentChatHistory = AIAgent.CurrentRunContext?.Session?.GetService<IList<ChatMessage>>();
+            // if (parentChatHistory != null)
+            // {
+            //     var chp = new InMemoryChatHistoryProvider();
+            //     foreach (var message in parentChatHistory)
+            //     {
+            //         chp.Add(message);
+            //     }
+            //     session = agent.GetNewSession(chp);
+            // }
+
+            var response = await agent.RunAsync(query, session: session, cancellationToken: cancellationToken).ConfigureAwait(false);
+            return response.Text;
+        }
+
+        options ??= new();
+        options.Name ??= SanitizeAgentName(agent.Name);
+        options.Description ??= agent.Description;
+
+        return AIFunctionFactory.Create(InvokeAgentAsync, options);
+    }
+```
+
+## Decision Drivers
+
+- Components executing during an agent run need access to run context without explicit parameter passing through every layer
+- Context should flow naturally across async calls without manual propagation
+- The design should allow modification of context properties by agent decorators (e.g., replacing options or session)
+- Solution should be consistent with patterns used in similar frameworks (e.g., `FunctionInvokingChatClient.CurrentContext` `HttpContext.Current`, `Activity.Current`)
+
+## Considered Options
+
+- **Option 1**: Pass context explicitly through all method signatures
+- **Option 2**: Use `AsyncLocal<T>` to provide ambient context accessible anywhere during the run
+- **Option 3**: Use a combination of explicit parameters for `RunCoreAsync` and `AsyncLocal<T>` for ambient access
+
+## Decision Outcome
+
+Chosen option: **Option 3** - Combination of explicit parameters and AsyncLocal ambient access.
+
+This approach provides the best of both worlds:
+
+1. **Explicit parameters are passed to `RunCoreAsync`**: The core agent implementation receives the parameters explicitly, making it clear what data is available and enabling easy unit testing. Any modification of these in a decorator will require calling `RunAsync` on the inner agent with the updated parameters, which would result in the inner agent creating a new `AgentRunContext` instance.
+
+   ```csharp
+    public async Task<AgentResponse> RunAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+
+        CurrentRunContext = new(this, session, messages as IReadOnlyCollection<ChatMessage> ?? messages.ToList(), options);
+        return await this.RunCoreAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
+    }
+   ```
+
+2. **`AsyncLocal<AgentRunContext?>` for ambient access**: The context is stored in an `AsyncLocal<T>` field, making it accessible from any code executing during the agent run via a static property.
+
+    The main scenario for this is to allow deeply nested components (e.g., tools, chat client middleware) to access the context without needing to pass it through every method signature. These are external components that cannot easily be modified to accept additional parameters. For internal components, we prefer passing any parameters explicitly.
+
+   ```csharp
+   public static AgentRunContext? CurrentRunContext
+   {
+       get => s_currentContext.Value;
+       protected set => s_currentContext.Value = value;
+   }
+   ```
+
+### AgentRunContext Design
+
+The `AgentRunContext` class encapsulates all run-related state:
+
+```csharp
+public class AgentRunContext
+{
+    public AgentRunContext(
+        AIAgent agent,
+        AgentSession? session,
+        IReadOnlyCollection<ChatMessage> requestMessages,
+        AgentRunOptions? agentRunOptions)
+
+    public AIAgent Agent { get; }
+    public AgentSession? Session { get; }
+    public IReadOnlyCollection<ChatMessage> RequestMessages { get; }
+    public AgentRunOptions? RunOptions { get; }
+}
+```
+
+Key design decisions:
+
+- **All properties are read-only**: While some of the sub-properties on the provided properties (like `AgentRunOptions.AllowBackgroundResponses`) may be mutable, the `AgentRunContext` itself is immutable and we want to discourage anyone modifying the values in the context.  Modifying the context is unlikely to result in the desired behavior, as the values will typically already have been used by the time any custom code accesses them.
+
+### Benefits
+
+1. **Ambient Access**: Any code executing during the run can access context via `AIAgent.CurrentRunContext` without needing explicit parameters
+2. **Async Flow**: `AsyncLocal<T>` automatically flows across async/await boundaries
+3. **Modifiability**: Components can modify or replace session, messages, or options as needed
+4. **Testability**: The explicit parameter to `RunCoreAsync` makes unit testing straightforward

dotnet/AGENTS.md

@@ -0,0 +1,66 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in the .NET codebase.
+
+## Build, Test, and Lint Commands
+
+```bash
+# From dotnet/ directory
+dotnet build              # Build all projects
+dotnet test               # Run all tests
+dotnet format             # Auto-fix formatting
+
+# Build/test a specific project (preferred for isolated changes)
+dotnet build src/Microsoft.Agents.AI.<Package>
+dotnet test tests/Microsoft.Agents.AI.<Package>.UnitTests
+
+# Run a single test
+dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"
+```
+
+**Note**: Changes to core packages (`Microsoft.Agents.AI`, `Microsoft.Agents.AI.Abstractions`) affect dependent projects - run checks across the entire solution. For isolated changes, build/test only the affected project to save time.
+
+## Project Structure
+
+```
+dotnet/
+├── src/
+│   ├── Microsoft.Agents.AI/              # Core AI agent abstractions
+│   ├── Microsoft.Agents.AI.Abstractions/ # Shared abstractions and interfaces
+│   ├── Microsoft.Agents.AI.OpenAI/       # OpenAI provider
+│   ├── Microsoft.Agents.AI.AzureAI/      # Azure AI provider
+│   ├── Microsoft.Agents.AI.Anthropic/    # Anthropic provider
+│   ├── Microsoft.Agents.AI.Workflows/    # Workflow orchestration
+│   └── ...                               # Other packages
+├── samples/                              # Sample applications
+└── tests/                                # Unit and integration tests
+```
+
+### External Dependencies
+
+The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extensions.AI.Abstractions` (external NuGet packages) using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, and `AIContent`.
+
+## Key Conventions
+
+- **Copyright header**: `// Copyright (c) Microsoft. All rights reserved.` at top of all `.cs` files
+- **XML docs**: Required for all public methods and classes
+- **Async**: Use `Async` suffix for methods returning `Task`/`ValueTask`
+- **Private classes**: Should be `sealed` unless subclassed
+- **Config**: Read from environment variables with `UPPER_SNAKE_CASE` naming
+- **Tests**: Add Arrange/Act/Assert comments; use Moq for mocking
+
+## Sample Structure
+
+1. Copyright header: `// Copyright (c) Microsoft. All rights reserved.`
+2. Description comment explaining what the sample demonstrates
+3. Using statements
+4. Main code logic
+5. Helper methods at bottom
+
+Configuration via environment variables (never hardcode secrets). Keep samples simple and focused.
+
+When adding a new sample:
+- Create a standalone project in `samples/` with matching directory and project names
+- Include a README.md explaining what the sample does and how to run it
+- Add the project to the solution file
+- Reference the sample in the parent directory's README.md

dotnet/Directory.Packages.props

@@ -33,18 +33,18 @@
     <!-- Newtonsoft.Json -->
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
     <!-- System.* -->
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.2" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.3" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
     <PackageVersion Include="System.ClientModel" Version="1.8.1" />
     <PackageVersion Include="System.CodeDom" Version="10.0.0" />
     <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.2" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.3" />
     <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.0" />
     <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
     <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.1" />
-    <PackageVersion Include="System.Text.Json" Version="10.0.2" />
-    <PackageVersion Include="System.Threading.Channels" Version="10.0.2" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.3" />
+    <PackageVersion Include="System.Threading.Channels" Version="10.0.3" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
     <PackageVersion Include="System.Net.Security" Version="4.3.2" />
     <!-- OpenTelemetry -->
@@ -61,9 +61,9 @@
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.2.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.2.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.2.0-preview.1.26063.2" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.3.0" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
@@ -71,11 +71,11 @@
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.2" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.3" />
     <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.2" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.3" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
@@ -89,7 +89,7 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.67.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
     <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.18" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.23" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.0" />

dotnet/agent-framework-dotnet.slnx

@@ -81,7 +81,7 @@
     <Project Path="samples/GettingStarted/Agents/Agent_Step04_UsingFunctionToolsWithApprovals/Agent_Step04_UsingFunctionToolsWithApprovals.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Agent_Step05_StructuredOutput.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step06_PersistedConversations/Agent_Step06_PersistedConversations.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step07_3rdPartyThreadStorage/Agent_Step07_3rdPartyThreadStorage.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step07_3rdPartyChatHistoryStorage/Agent_Step07_3rdPartyChatHistoryStorage.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step08_Observability/Agent_Step08_Observability.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step09_DependencyInjection/Agent_Step09_DependencyInjection.csproj" />
     <Project Path="samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/Agent_Step10_AsMcpTool.csproj" />
@@ -131,6 +131,7 @@
     <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
     <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
     <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/AgentWithMemory/">
     <File Path="samples/GettingStarted/AgentWithMemory/README.md" />

dotnet/agent-framework-release.slnf

@@ -25,6 +25,7 @@
       "src\\Microsoft.Agents.AI.Purview\\Microsoft.Agents.AI.Purview.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Declarative\\Microsoft.Agents.AI.Workflows.Declarative.csproj",
+      "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
       "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
       "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj"
     ]

dotnet/nuget/nuget-package.props

@@ -2,9 +2,9 @@
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
     <VersionPrefix>1.0.0</VersionPrefix>
-    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260128.1</PackageVersion>
-    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260128.1</PackageVersion>
-    <GitTag>1.0.0-preview.260128.1</GitTag>
+    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260212.1</PackageVersion>
+    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260212.1</PackageVersion>
+    <GitTag>1.0.0-preview.260212.1</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/A2AClientServer/A2AClient/Program.cs

@@ -42,7 +42,7 @@ public static class Program
         // Create the Host agent
         var hostAgent = new HostClientAgent(loggerFactory);
         await hostAgent.InitializeAgentAsync(modelId, apiKey, agentUrls!.Split(";"));
-        AgentSession session = await hostAgent.Agent!.GetNewSessionAsync(cancellationToken);
+        AgentSession session = await hostAgent.Agent!.CreateSessionAsync(cancellationToken);
         try
         {
             while (true)

dotnet/samples/A2AClientServer/A2AServer/HostAgentFactory.cs

@@ -14,7 +14,10 @@ internal static class HostAgentFactory
 {
     internal static async Task<(AIAgent, AgentCard)> CreateFoundryHostAgentAsync(string agentType, string model, string endpoint, string assistantId, IList<AITool>? tools = null)
     {
-        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());
         PersistentAgent persistentAgent = await persistentAgentsClient.Administration.GetAgentAsync(assistantId);
 
         AIAgent agent = await persistentAgentsClient

dotnet/samples/AGUIClientServer/AGUIClient/Program.cs

@@ -88,7 +88,7 @@ public static class Program
             description: "AG-UI Client Agent",
             tools: [changeBackground, readClientClimateSensors]);
 
-        AgentSession session = await agent.GetNewSessionAsync(cancellationToken);
+        AgentSession session = await agent.CreateSessionAsync(cancellationToken);
         List<ChatMessage> messages = [new(ChatRole.System, "You are a helpful assistant.")];
         try
         {

dotnet/samples/AGUIClientServer/AGUIDojoServer/ChatClientAgentFactory.cs

@@ -24,6 +24,9 @@ internal static class ChatClientAgentFactory
         string endpoint = configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
         s_deploymentName = configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
         s_azureOpenAIClient = new AzureOpenAIClient(
             new Uri(endpoint),
             new DefaultAzureCredential());

dotnet/samples/AGUIClientServer/AGUIServer/Program.cs

@@ -19,6 +19,9 @@ string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new In
 string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
 // Create the AI agent with tools
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 var agent = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/AGUIWebChat/Server/Program.cs

@@ -19,6 +19,9 @@ string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new In
 string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
 // Create the AI agent
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient azureOpenAIClient = new(
     new Uri(endpoint),
     new DefaultAzureCredential());

dotnet/samples/Durable/Agents/AzureFunctions/01_SingleAgent/Program.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable IDE0002 // Simplify Member Access
+
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -17,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Set up an AI agent following the standard Microsoft Agent Framework pattern.
 const string JokerName = "Joker";

dotnet/samples/Durable/Agents/AzureFunctions/02_AgentOrchestration_Chaining/FunctionTriggers.cs

@@ -19,7 +19,7 @@ public static class FunctionTriggers
     public static async Task<string> RunOrchestrationAsync([OrchestrationTrigger] TaskOrchestrationContext context)
     {
         DurableAIAgent writer = context.GetAgent("WriterAgent");
-        AgentSession writerSession = await writer.GetNewSessionAsync();
+        AgentSession writerSession = await writer.CreateSessionAsync();
 
         AgentResponse<TextResponse> initial = await writer.RunAsync<TextResponse>(
             message: "Write a concise inspirational sentence about learning.",

dotnet/samples/Durable/Agents/AzureFunctions/02_AgentOrchestration_Chaining/Program.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable IDE0002 // Simplify Member Access
+
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -17,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Single agent used by the orchestration to demonstrate sequential calls on the same session.
 const string WriterName = "WriterAgent";

dotnet/samples/Durable/Agents/AzureFunctions/03_AgentOrchestration_Concurrency/Program.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable IDE0002 // Simplify Member Access
+
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -17,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Two agents used by the orchestration to demonstrate concurrent execution.
 const string PhysicistName = "PhysicistAgent";

dotnet/samples/Durable/Agents/AzureFunctions/04_AgentOrchestration_Conditionals/FunctionTriggers.cs

@@ -21,7 +21,7 @@ public static class FunctionTriggers
 
         // Get the spam detection agent
         DurableAIAgent spamDetectionAgent = context.GetAgent("SpamDetectionAgent");
-        AgentSession spamSession = await spamDetectionAgent.GetNewSessionAsync();
+        AgentSession spamSession = await spamDetectionAgent.CreateSessionAsync();
 
         // Step 1: Check if the email is spam
         AgentResponse<DetectionResult> spamDetectionResponse = await spamDetectionAgent.RunAsync<DetectionResult>(
@@ -43,7 +43,7 @@ public static class FunctionTriggers
 
         // Generate and send response for legitimate email
         DurableAIAgent emailAssistantAgent = context.GetAgent("EmailAssistantAgent");
-        AgentSession emailSession = await emailAssistantAgent.GetNewSessionAsync();
+        AgentSession emailSession = await emailAssistantAgent.CreateSessionAsync();
 
         AgentResponse<EmailResponse> emailAssistantResponse = await emailAssistantAgent.RunAsync<EmailResponse>(
             message:

dotnet/samples/Durable/Agents/AzureFunctions/04_AgentOrchestration_Conditionals/Program.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable IDE0002 // Simplify Member Access
+
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -17,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Two agents used by the orchestration to demonstrate conditional logic.
 const string SpamDetectionName = "SpamDetectionAgent";

dotnet/samples/Durable/Agents/AzureFunctions/05_AgentOrchestration_HITL/FunctionTriggers.cs

@@ -24,7 +24,7 @@ public static class FunctionTriggers
 
         // Get the writer agent
         DurableAIAgent writerAgent = context.GetAgent("WriterAgent");
-        AgentSession writerSession = await writerAgent.GetNewSessionAsync();
+        AgentSession writerSession = await writerAgent.CreateSessionAsync();
 
         // Set initial status
         context.SetCustomStatus($"Starting content generation for topic: {input.Topic}");

dotnet/samples/Durable/Agents/AzureFunctions/05_AgentOrchestration_HITL/Program.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable IDE0002 // Simplify Member Access
+
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -17,9 +19,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Single agent used by the orchestration to demonstrate human-in-the-loop workflow.
 const string WriterName = "WriterAgent";

dotnet/samples/Durable/Agents/AzureFunctions/06_LongRunningTools/FunctionTriggers.cs

@@ -20,7 +20,7 @@ public static class FunctionTriggers
 
         // Get the writer agent
         DurableAIAgent writerAgent = context.GetAgent("Writer");
-        AgentSession writerSession = await writerAgent.GetNewSessionAsync();
+        AgentSession writerSession = await writerAgent.CreateSessionAsync();
 
         // Set initial status
         context.SetCustomStatus($"Starting content generation for topic: {input.Topic}");

dotnet/samples/Durable/Agents/AzureFunctions/06_LongRunningTools/Program.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable IDE0002 // Simplify Member Access
+
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -21,9 +23,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Agent used by the orchestration to write content.
 const string WriterAgentName = "Writer";

dotnet/samples/Durable/Agents/AzureFunctions/07_AgentAsMcpTool/Program.cs

@@ -5,6 +5,8 @@
 // generate a remote MCP endpoint for the app at /runtime/webhooks/mcp with a agent-specific
 // query tool name.
 
+#pragma warning disable IDE0002 // Simplify Member Access
+
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -23,9 +25,12 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Define three AI agents we are going to use in this application.
 AIAgent agent1 = client.GetChatClient(deploymentName).AsAIAgent("You are good at telling jokes.", "Joker");

dotnet/samples/Durable/Agents/AzureFunctions/08_ReliableStreaming/FunctionTriggers.cs

@@ -95,7 +95,7 @@ public sealed class FunctionTriggers
         AIAgent agentProxy = durableClient.AsDurableAgentProxy(context, "TravelPlanner");
 
         // Create a new agent session
-        AgentSession session = await agentProxy.GetNewSessionAsync(cancellationToken);
+        AgentSession session = await agentProxy.CreateSessionAsync(cancellationToken);
         string agentSessionId = session.GetService<AgentSessionId>().ToString();
 
         this._logger.LogInformation("Creating new agent session: {AgentSessionId}", agentSessionId);

dotnet/samples/Durable/Agents/AzureFunctions/08_ReliableStreaming/Program.cs

@@ -8,6 +8,8 @@
 // This pattern is inspired by OpenAI's background mode for the Responses API, which allows clients
 // to disconnect and reconnect to ongoing agent responses without losing messages.
 
+#pragma warning disable IDE0002 // Simplify Member Access
+
 using Azure;
 using Azure.AI.OpenAI;
 using Azure.Identity;
@@ -38,9 +40,12 @@ int redisStreamTtlMinutes = int.TryParse(
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Travel Planner agent instructions - designed to produce longer responses for demonstrating streaming.
 const string TravelPlannerName = "TravelPlanner";

dotnet/samples/Durable/Agents/ConsoleApps/01_SingleAgent/Program.cs

@@ -25,9 +25,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Set up an AI agent following the standard Microsoft Agent Framework pattern.
 const string JokerName = "Joker";
@@ -61,7 +64,7 @@ Console.WriteLine("Enter a message for the Joker agent (or 'exit' to quit):");
 Console.WriteLine();
 
 // Create a session for the conversation
-AgentSession session = await agentProxy.GetNewSessionAsync();
+AgentSession session = await agentProxy.CreateSessionAsync();
 
 while (true)
 {

dotnet/samples/Durable/Agents/ConsoleApps/02_AgentOrchestration_Chaining/Program.cs

@@ -29,9 +29,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Single agent used by the orchestration to demonstrate sequential calls on the same session.
 const string WriterName = "WriterAgent";
@@ -47,7 +50,7 @@ AIAgent writerAgent = client.GetChatClient(deploymentName).AsAIAgent(WriterInstr
 static async Task<string> RunOrchestratorAsync(TaskOrchestrationContext context)
 {
     DurableAIAgent writer = context.GetAgent("WriterAgent");
-    AgentSession writerSession = await writer.GetNewSessionAsync();
+    AgentSession writerSession = await writer.CreateSessionAsync();
 
     AgentResponse<TextResponse> initial = await writer.RunAsync<TextResponse>(
         message: "Write a concise inspirational sentence about learning.",

dotnet/samples/Durable/Agents/ConsoleApps/03_AgentOrchestration_Concurrency/Program.cs

@@ -29,9 +29,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Two agents used by the orchestration to demonstrate concurrent execution.
 const string PhysicistName = "PhysicistAgent";

dotnet/samples/Durable/Agents/ConsoleApps/04_AgentOrchestration_Conditionals/Program.cs

@@ -28,9 +28,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Spam detection agent
 const string SpamDetectionAgentName = "SpamDetectionAgent";
@@ -56,7 +59,7 @@ static async Task<string> RunOrchestratorAsync(TaskOrchestrationContext context,
 {
     // Get the spam detection agent
     DurableAIAgent spamDetectionAgent = context.GetAgent(SpamDetectionAgentName);
-    AgentSession spamSession = await spamDetectionAgent.GetNewSessionAsync();
+    AgentSession spamSession = await spamDetectionAgent.CreateSessionAsync();
 
     // Step 1: Check if the email is spam
     AgentResponse<DetectionResult> spamDetectionResponse = await spamDetectionAgent.RunAsync<DetectionResult>(
@@ -78,7 +81,7 @@ static async Task<string> RunOrchestratorAsync(TaskOrchestrationContext context,
 
     // Generate and send response for legitimate email
     DurableAIAgent emailAssistantAgent = context.GetAgent(EmailAssistantAgentName);
-    AgentSession emailSession = await emailAssistantAgent.GetNewSessionAsync();
+    AgentSession emailSession = await emailAssistantAgent.CreateSessionAsync();
 
     AgentResponse<EmailResponse> emailAssistantResponse = await emailAssistantAgent.RunAsync<EmailResponse>(
         message:

dotnet/samples/Durable/Agents/ConsoleApps/05_AgentOrchestration_HITL/Program.cs

@@ -29,9 +29,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Single agent used by the orchestration to demonstrate human-in-the-loop workflow.
 const string WriterName = "WriterAgent";
@@ -48,7 +51,7 @@ static async Task<object> RunOrchestratorAsync(TaskOrchestrationContext context,
 {
     // Get the writer agent
     DurableAIAgent writerAgent = context.GetAgent("WriterAgent");
-    AgentSession writerSession = await writerAgent.GetNewSessionAsync();
+    AgentSession writerSession = await writerAgent.CreateSessionAsync();
 
     // Set initial status
     context.SetCustomStatus($"Starting content generation for topic: {input.Topic}");

dotnet/samples/Durable/Agents/ConsoleApps/06_LongRunningTools/Program.cs

@@ -30,9 +30,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Agent used by the orchestration to write content.
 const string WriterAgentName = "Writer";
@@ -59,7 +62,7 @@ static async Task<object> RunOrchestratorAsync(TaskOrchestrationContext context,
 {
     // Get the writer agent
     DurableAIAgent writerAgent = context.GetAgent(WriterAgentName);
-    AgentSession writerSession = await writerAgent.GetNewSessionAsync();
+    AgentSession writerSession = await writerAgent.CreateSessionAsync();
 
     // Set initial status
     context.SetCustomStatus($"Starting content generation for topic: {input.Topic}");
@@ -299,7 +302,7 @@ Console.WriteLine("Enter a topic for the Publisher agent to write about (or 'exi
 Console.WriteLine();
 
 // Create a session for the conversation
-AgentSession session = await agentProxy.GetNewSessionAsync();
+AgentSession session = await agentProxy.CreateSessionAsync();
 
 using CancellationTokenSource cts = new();
 Console.CancelKeyPress += (sender, e) =>

dotnet/samples/Durable/Agents/ConsoleApps/07_ReliableStreaming/Program.cs

@@ -38,9 +38,12 @@ string dtsConnectionString = Environment.GetEnvironmentVariable("DURABLE_TASK_SC
 
 // Use Azure Key Credential if provided, otherwise use Azure CLI Credential.
 string? azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY");
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient client = !string.IsNullOrEmpty(azureOpenAiKey)
     ? new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(azureOpenAiKey))
-    : new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential());
+    : new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Travel Planner agent instructions - designed to produce longer responses for demonstrating streaming.
 const string TravelPlannerName = "TravelPlanner";
@@ -305,7 +308,7 @@ if (string.IsNullOrWhiteSpace(prompt) || prompt.Equals("exit", StringComparison.
 }
 
 // Create a new agent session
-AgentSession session = await agentProxy.GetNewSessionAsync();
+AgentSession session = await agentProxy.CreateSessionAsync();
 AgentSessionId sessionId = session.GetService<AgentSessionId>();
 string conversationId = sessionId.ToString();
 

dotnet/samples/GettingStarted/A2A/A2AAgent_AsFunctionTools/Program.cs

@@ -26,9 +26,12 @@ AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
 AIAgent a2aAgent = agentCard.AsAIAgent();
 
 // Create the main agent, and provide the a2a agent skills as a function tools.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(
         instructions: "You are a helpful assistant that helps people with travel planning.",

dotnet/samples/GettingStarted/A2A/A2AAgent_PollingForTaskCompletion/Program.cs

@@ -16,7 +16,7 @@ AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
 // Create an instance of the AIAgent for an existing A2A agent specified by the agent card.
 AIAgent agent = agentCard.AsAIAgent();
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 // Start the initial run with a long-running task.
 AgentResponse response = await agent.RunAsync("Conduct a comprehensive analysis of quantum computing applications in cryptography, including recent breakthroughs, implementation challenges, and future roadmap. Please include diagrams and visual representations to illustrate complex concepts.", session);

dotnet/samples/GettingStarted/AGUI/Step01_GettingStarted/Client/Program.cs

@@ -20,7 +20,7 @@ AIAgent agent = chatClient.AsAIAgent(
     name: "agui-client",
     description: "AG-UI Client Agent");
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 List<ChatMessage> messages =
 [
     new(ChatRole.System, "You are a helpful assistant.")

dotnet/samples/GettingStarted/AGUI/Step01_GettingStarted/Server/Program.cs

@@ -19,6 +19,9 @@ string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
     ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
 // Create the AI agent
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 ChatClient chatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/GettingStarted/AGUI/Step02_BackendTools/Client/Program.cs

@@ -20,7 +20,7 @@ AIAgent agent = chatClient.AsAIAgent(
     name: "agui-client",
     description: "AG-UI Client Agent");
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 List<ChatMessage> messages =
 [
     new(ChatRole.System, "You are a helpful assistant.")

dotnet/samples/GettingStarted/AGUI/Step02_BackendTools/Server/Program.cs

@@ -74,6 +74,9 @@ AITool[] tools =
 ];
 
 // Create the AI agent with tools
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 ChatClient chatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/GettingStarted/AGUI/Step03_FrontendTools/Client/Program.cs

@@ -33,7 +33,7 @@ AIAgent agent = chatClient.AsAIAgent(
     description: "AG-UI Client Agent",
     tools: frontendTools);
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 List<ChatMessage> messages =
 [
     new(ChatRole.System, "You are a helpful assistant.")

dotnet/samples/GettingStarted/AGUI/Step03_FrontendTools/Server/Program.cs

@@ -19,6 +19,9 @@ string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
     ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
 
 // Create the AI agent
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 ChatClient chatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/Program.cs

@@ -52,6 +52,9 @@ AITool[] tools = [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(Approv
 #pragma warning restore MEAI001
 
 // Create base agent
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 ChatClient openAIChatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Client/Program.cs

@@ -30,7 +30,7 @@ JsonSerializerOptions jsonOptions = new(JsonSerializerDefaults.Web)
 };
 StatefulAgent<AgentState> agent = new(baseAgent, jsonOptions, new AgentState());
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 List<ChatMessage> messages =
 [
     new(ChatRole.System, "You are a helpful recipe assistant.")

dotnet/samples/GettingStarted/AGUI/Step05_StateManagement/Server/Program.cs

@@ -29,6 +29,9 @@ string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
 var jsonOptions = app.Services.GetRequiredService<IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions>>().Value;
 
 // Create base agent
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 ChatClient chatClient = new AzureOpenAIClient(
         new Uri(endpoint),
         new DefaultAzureCredential())

dotnet/samples/GettingStarted/AgentOpenTelemetry/Program.cs

@@ -110,7 +110,10 @@ static async Task<string> GetWeatherAsync([Description("The location to get the
     return $"The weather in {location} is cloudy with a high of 15°C.";
 }
 
-using var instrumentedChatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+using var instrumentedChatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
     .GetChatClient(deploymentName)
         .AsIChatClient() // Converts a native OpenAI SDK ChatClient into a Microsoft.Extensions.AI.IChatClient
         .AsBuilder()
@@ -128,7 +131,7 @@ var agent = new ChatClientAgent(instrumentedChatClient,
     .UseOpenTelemetry(SourceName, configure: (cfg) => cfg.EnableSensitiveData = true) // enable telemetry at the agent level
     .Build();
 
-var session = await agent.GetNewSessionAsync();
+var session = await agent.CreateSessionAsync();
 
 appLogger.LogInformation("Agent created successfully with ID: {AgentId}", agent.Id);
 

dotnet/samples/GettingStarted/AgentProviders/Agent_With_Anthropic/Program.cs

@@ -17,11 +17,14 @@ string? apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY");
 const string JokerInstructions = "You are good at telling jokes.";
 const string JokerName = "JokerAgent";
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 using AnthropicClient client = (resource is null)
     ? new AnthropicClient() { ApiKey = apiKey ?? throw new InvalidOperationException("ANTHROPIC_API_KEY is required when no ANTHROPIC_RESOURCE is provided") }  // If no resource is provided, use Anthropic public API
     : (apiKey is not null)
         ? new AnthropicFoundryClient(new AnthropicFoundryApiKeyCredentials(apiKey, resource)) // If an apiKey is provided, use Foundry with ApiKey authentication
-        : new AnthropicFoundryClient(new AnthropicFoundryIdentityTokenCredentials(new AzureCliCredential(), resource, ["https://ai.azure.com/.default"])); // Otherwise, use Foundry with Azure TokenCredential authentication
+        : new AnthropicFoundryClient(new AnthropicFoundryIdentityTokenCredentials(new DefaultAzureCredential(), resource, ["https://ai.azure.com/.default"])); // Otherwise, use Foundry with Azure TokenCredential authentication
 
 AIAgent agent = client.AsAIAgent(model: deploymentName, instructions: JokerInstructions, name: JokerName);
 

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureAIAgentsPersistent/Program.cs

@@ -13,7 +13,10 @@ const string JokerName = "Joker";
 const string JokerInstructions = "You are good at telling jokes.";
 
 // Get a client to create/retrieve server side agents with.
-var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());
 
 // You can create a server side persistent agent with the Azure.AI.Agents.Persistent SDK.
 var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
@@ -31,7 +34,7 @@ AIAgent agent2 = await persistentAgentsClient.CreateAIAgentAsync(
     instructions: JokerInstructions);
 
 // You can then invoke the agent like any other AIAgent.
-AgentSession session = await agent1.GetNewSessionAsync();
+AgentSession session = await agent1.CreateSessionAsync();
 Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate.", session));
 
 // Cleanup for sample purposes.

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureAIProject/Program.cs

@@ -13,7 +13,10 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_D
 const string JokerName = "JokerAgent";
 
 // Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
-var aiProjectClient = new AIProjectClient(new Uri(endpoint), new AzureCliCredential());
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
 
 // Define the agent you want to create. (Prompt Agent in this case)
 var agentVersionCreationOptions = new AgentVersionCreationOptions(new PromptAgentDefinition(model: deploymentName) { Instructions = "You are good at telling jokes." });
@@ -40,7 +43,7 @@ var latestAgentVersion = jokerAgentLatest.GetService<AgentVersion>()!;
 Console.WriteLine($"Latest agent version id: {latestAgentVersion.Id}");
 
 // Once you have the AIAgent, you can invoke it like any other AIAgent.
-AgentSession session = await jokerAgentLatest.GetNewSessionAsync();
+AgentSession session = await jokerAgentLatest.CreateSessionAsync();
 Console.WriteLine(await jokerAgentLatest.RunAsync("Tell me a joke about a pirate.", session));
 
 // This will use the same session to continue the conversation.

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureFoundryModel/Program.cs

@@ -19,8 +19,11 @@ var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_MODEL_DEPLOYMENT")
 var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri(endpoint) };
 
 // Create the OpenAI client with either an API key or Azure CLI credential.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 OpenAIClient client = string.IsNullOrWhiteSpace(apiKey)
-    ? new OpenAIClient(new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"), clientOptions)
+    ? new OpenAIClient(new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"), clientOptions)
     : new OpenAIClient(new ApiKeyCredential(apiKey), clientOptions);
 
 AIAgent agent = client

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Program.cs

@@ -10,9 +10,12 @@ using OpenAI.Chat;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetChatClient(deploymentName)
      .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIResponses/Program.cs

@@ -10,9 +10,12 @@ using OpenAI.Responses;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetResponsesClient(deploymentName)
      .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 

dotnet/samples/GettingStarted/AgentProviders/Agent_With_CustomImplementation/Program.cs

@@ -6,6 +6,7 @@
 
 using System.Runtime.CompilerServices;
 using System.Text.Json;
+using System.Text.Json.Serialization;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using SampleApp;
@@ -28,16 +29,28 @@ namespace SampleApp
     {
         public override string? Name => "UpperCaseParrotAgent";
 
-        public override ValueTask<AgentSession> GetNewSessionAsync(CancellationToken cancellationToken = default)
+        public readonly ChatHistoryProvider ChatHistoryProvider = new InMemoryChatHistoryProvider();
+
+        protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
             => new(new CustomAgentSession());
 
-        public override ValueTask<AgentSession> DeserializeSessionAsync(JsonElement serializedSession, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
-            => new(new CustomAgentSession(serializedSession, jsonSerializerOptions));
+        protected override ValueTask<JsonElement> SerializeSessionCoreAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+        {
+            if (session is not CustomAgentSession typedSession)
+            {
+                throw new ArgumentException($"The provided session is not of type {nameof(CustomAgentSession)}.", nameof(session));
+            }
+
+            return new(JsonSerializer.SerializeToElement(typedSession, jsonSerializerOptions));
+        }
+
+        protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+            => new(serializedState.Deserialize<CustomAgentSession>(jsonSerializerOptions)!);
 
         protected override async Task<AgentResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
         {
             // Create a session if the user didn't supply one.
-            session ??= await this.GetNewSessionAsync(cancellationToken);
+            session ??= await this.CreateSessionAsync(cancellationToken);
 
             if (session is not CustomAgentSession typedSession)
             {
@@ -45,18 +58,15 @@ namespace SampleApp
             }
 
             // Get existing messages from the store
-            var invokingContext = new ChatHistoryProvider.InvokingContext(messages);
-            var storeMessages = await typedSession.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
+            var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
+            var userAndChatHistoryMessages = await this.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
 
             // Clone the input messages and turn them into response messages with upper case text.
             List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
 
             // Notify the session of the input and output messages.
-            var invokedContext = new ChatHistoryProvider.InvokedContext(messages, storeMessages)
-            {
-                ResponseMessages = responseMessages
-            };
-            await typedSession.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, userAndChatHistoryMessages, responseMessages);
+            await this.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
 
             return new AgentResponse
             {
@@ -69,7 +79,7 @@ namespace SampleApp
         protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
         {
             // Create a session if the user didn't supply one.
-            session ??= await this.GetNewSessionAsync(cancellationToken);
+            session ??= await this.CreateSessionAsync(cancellationToken);
 
             if (session is not CustomAgentSession typedSession)
             {
@@ -77,18 +87,15 @@ namespace SampleApp
             }
 
             // Get existing messages from the store
-            var invokingContext = new ChatHistoryProvider.InvokingContext(messages);
-            var storeMessages = await typedSession.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
+            var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
+            var userAndChatHistoryMessages = await this.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
 
             // Clone the input messages and turn them into response messages with upper case text.
             List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
 
             // Notify the session of the input and output messages.
-            var invokedContext = new ChatHistoryProvider.InvokedContext(messages, storeMessages)
-            {
-                ResponseMessages = responseMessages
-            };
-            await typedSession.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, userAndChatHistoryMessages, responseMessages);
+            await this.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
 
             foreach (var message in responseMessages)
             {
@@ -130,12 +137,16 @@ namespace SampleApp
         /// <summary>
         /// A session type for our custom agent that only supports in memory storage of messages.
         /// </summary>
-        internal sealed class CustomAgentSession : InMemoryAgentSession
+        internal sealed class CustomAgentSession : AgentSession
         {
-            internal CustomAgentSession() { }
+            internal CustomAgentSession()
+            {
+            }
 
-            internal CustomAgentSession(JsonElement serializedSessionState, JsonSerializerOptions? jsonSerializerOptions = null)
-                : base(serializedSessionState, jsonSerializerOptions) { }
+            [JsonConstructor]
+            internal CustomAgentSession(AgentSessionStateBag stateBag) : base(stateBag)
+            {
+            }
         }
     }
 }

dotnet/samples/GettingStarted/AgentProviders/Agent_With_OpenAIAssistants/Program.cs

@@ -33,7 +33,7 @@ AIAgent agent2 = await assistantClient.CreateAIAgentAsync(
     instructions: JokerInstructions);
 
 // You can invoke the agent like any other AIAgent.
-AgentSession session = await agent1.GetNewSessionAsync();
+AgentSession session = await agent1.CreateSessionAsync();
 Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate.", session));
 
 // Cleanup for sample purposes.

dotnet/samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Program.cs

@@ -26,11 +26,11 @@ AIAgent agent = new AnthropicClient { ApiKey = apiKey }
     .AsAIAgent(model: model, instructions: AssistantInstructions, name: AssistantName, tools: [tool]);
 
 // Non-streaming agent interaction with function tools.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", session));
 
 // Streaming agent interaction with function tools.
-session = await agent.GetNewSessionAsync();
+session = await agent.CreateSessionAsync();
 await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("What is the weather like in Amsterdam?", session))
 {
     Console.WriteLine(update);

dotnet/samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Anthropic\Microsoft.Agents.AI.Anthropic.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Program.cs

@@ -0,0 +1,127 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use Anthropic-managed Skills with an AI agent.
+// Skills are pre-built capabilities provided by Anthropic that can be used with the Claude API.
+// This sample shows how to:
+// 1. List available Anthropic-managed skills
+// 2. Use the pptx skill to create PowerPoint presentations
+// 3. Download and save generated files
+
+using Anthropic;
+using Anthropic.Core;
+using Anthropic.Models.Beta;
+using Anthropic.Models.Beta.Files;
+using Anthropic.Models.Beta.Messages;
+using Anthropic.Models.Beta.Skills;
+using Anthropic.Services;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+string apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") ?? throw new InvalidOperationException("ANTHROPIC_API_KEY is not set.");
+// Skills require Claude 4.5 models (Sonnet 4.5, Haiku 4.5, or Opus 4.5)
+string model = Environment.GetEnvironmentVariable("ANTHROPIC_MODEL") ?? "claude-sonnet-4-5-20250929";
+
+// Create the Anthropic client
+AnthropicClient anthropicClient = new() { ApiKey = apiKey };
+
+// List available Anthropic-managed skills (optional - API may not be available in all regions)
+Console.WriteLine("Available Anthropic-managed skills:");
+try
+{
+    SkillListPage skills = await anthropicClient.Beta.Skills.List(
+        new SkillListParams { Source = "anthropic", Betas = [AnthropicBeta.Skills2025_10_02] });
+
+    foreach (var skill in skills.Items)
+    {
+        Console.WriteLine($"  {skill.Source}: {skill.ID} (version: {skill.LatestVersion})");
+    }
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"  (Skills listing not available: {ex.Message})");
+}
+
+Console.WriteLine();
+
+// Define the pptx skill - the SDK handles all beta flags and container configuration automatically
+// when using AsAITool(), so no manual RawRepresentationFactory configuration is needed.
+BetaSkillParams pptxSkill = new()
+{
+    Type = BetaSkillParamsType.Anthropic,
+    SkillID = "pptx",
+    Version = "latest"
+};
+
+// Create an agent with the pptx skill enabled.
+// Skills require extended thinking and higher max tokens for complex file generation.
+// The SDK's AsAITool() handles beta flags and container config automatically.
+ChatClientAgent agent = anthropicClient.Beta.AsAIAgent(
+    model: model,
+    instructions: "You are a helpful agent for creating PowerPoint presentations.",
+    tools: [pptxSkill.AsAITool()],
+    clientFactory: (chatClient) => chatClient
+        .AsBuilder()
+        .ConfigureOptions(options =>
+        {
+            options.RawRepresentationFactory = (_) => new MessageCreateParams()
+            {
+                Model = model,
+                MaxTokens = 20000,
+                Messages = [],
+                Thinking = new BetaThinkingConfigParam(
+                    new BetaThinkingConfigEnabled(budgetTokens: 10000))
+            };
+        })
+        .Build());
+
+Console.WriteLine("Creating a presentation about renewable energy...\n");
+
+// Run the agent with a request to create a presentation
+AgentResponse response = await agent.RunAsync("Create a simple 3-slide presentation about renewable energy sources. Include a title slide, a slide about solar energy, and a slide about wind energy.");
+
+Console.WriteLine("#### Agent Response ####");
+Console.WriteLine(response.Text);
+
+// Display any reasoning/thinking content
+List<TextReasoningContent> reasoningContents = response.Messages.SelectMany(m => m.Contents.OfType<TextReasoningContent>()).ToList();
+if (reasoningContents.Count > 0)
+{
+    Console.WriteLine("\n#### Agent Reasoning ####");
+    Console.WriteLine($"\e[92m{string.Join("\n", reasoningContents.Select(c => c.Text))}\e[0m");
+}
+
+// Collect generated files from CodeInterpreterToolResultContent outputs
+List<HostedFileContent> hostedFiles = response.Messages
+    .SelectMany(m => m.Contents.OfType<CodeInterpreterToolResultContent>())
+    .Where(c => c.Outputs is not null)
+    .SelectMany(c => c.Outputs!.OfType<HostedFileContent>())
+    .ToList();
+
+if (hostedFiles.Count > 0)
+{
+    Console.WriteLine("\n#### Generated Files ####");
+    foreach (HostedFileContent file in hostedFiles)
+    {
+        Console.WriteLine($"  FileId: {file.FileId}");
+
+        // Download the file using the Anthropic Files API
+        using HttpResponse fileResponse = await anthropicClient.Beta.Files.Download(
+            file.FileId,
+            new FileDownloadParams { Betas = ["files-api-2025-04-14"] });
+
+        // Save the file to disk
+        string fileName = $"presentation_{file.FileId.Substring(0, 8)}.pptx";
+        using FileStream fileStream = File.Create(fileName);
+        Stream contentStream = await fileResponse.ReadAsStream();
+        await contentStream.CopyToAsync(fileStream);
+
+        Console.WriteLine($"  Saved to: {fileName}");
+    }
+}
+
+Console.WriteLine("\nToken usage:");
+Console.WriteLine($"Input: {response.Usage?.InputTokenCount}, Output: {response.Usage?.OutputTokenCount}");
+if (response.Usage?.AdditionalCounts is not null)
+{
+    Console.WriteLine($"Additional: {string.Join(", ", response.Usage.AdditionalCounts)}");
+}

dotnet/samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/README.md

@@ -0,0 +1,119 @@
+# Using Anthropic Skills with agents
+
+This sample demonstrates how to use Anthropic-managed Skills with AI agents. Skills are pre-built capabilities provided by Anthropic that can be used with the Claude API.
+
+## What this sample demonstrates
+
+- Listing available Anthropic-managed skills
+- Creating an AI agent with Anthropic Claude Skills support using the simplified `AsAITool()` approach
+- Using the pptx skill to create PowerPoint presentations
+- Downloading and saving generated files to disk
+- Handling agent responses with generated content
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10.0 SDK or later
+- Anthropic API key configured
+- Access to Anthropic Claude models with Skills support
+
+**Note**: This sample uses Anthropic Claude models with Skills. Skills are a beta feature. For more information, see [Anthropic documentation](https://docs.anthropic.com/).
+
+Set the following environment variables:
+
+```powershell
+$env:ANTHROPIC_API_KEY="your-anthropic-api-key"  # Replace with your Anthropic API key
+$env:ANTHROPIC_MODEL="your-anthropic-model"  # Replace with your Anthropic model (e.g., claude-sonnet-4-5-20250929)
+```
+
+## Run the sample
+
+Navigate to the AgentWithAnthropic sample directory and run:
+
+```powershell
+cd dotnet\samples\GettingStarted\AgentWithAnthropic
+dotnet run --project .\Agent_Anthropic_Step04_UsingSkills
+```
+
+## Available Anthropic Skills
+
+Anthropic provides several managed skills that can be used with the Claude API:
+
+- `pptx` - Create PowerPoint presentations
+- `xlsx` - Create Excel spreadsheets
+- `docx` - Create Word documents
+- `pdf` - Create and analyze PDF documents
+
+You can list available skills using the Anthropic SDK:
+
+```csharp
+SkillListPage skills = await anthropicClient.Beta.Skills.List(
+    new SkillListParams { Source = "anthropic", Betas = [AnthropicBeta.Skills2025_10_02] });
+
+foreach (var skill in skills.Items)
+{
+    Console.WriteLine($"{skill.Source}: {skill.ID} (version: {skill.LatestVersion})");
+}
+```
+
+## Expected behavior
+
+The sample will:
+
+1. List all available Anthropic-managed skills
+2. Create an agent with the pptx skill enabled
+3. Run the agent with a request to create a presentation
+4. Display the agent's response text
+5. Download any generated files and save them to disk
+6. Display token usage statistics
+
+## Code highlights
+
+### Simplified skill configuration
+
+The Anthropic SDK handles all beta flags and container configuration automatically when using `AsAITool()`:
+
+```csharp
+// Define the pptx skill
+BetaSkillParams pptxSkill = new()
+{
+    Type = BetaSkillParamsType.Anthropic,
+    SkillID = "pptx",
+    Version = "latest"
+};
+
+// Create an agent - the SDK handles beta flags automatically!
+ChatClientAgent agent = anthropicClient.Beta.AsAIAgent(
+    model: model,
+    instructions: "You are a helpful agent for creating PowerPoint presentations.",
+    tools: [pptxSkill.AsAITool()]);
+```
+
+**Note**: No manual `RawRepresentationFactory`, `Betas`, or `Container` configuration is needed. The SDK automatically adds the required beta headers (`skills-2025-10-02`, `code-execution-2025-08-25`) and configures the container with the skill.
+
+### Handling generated files
+
+Generated files are returned as `HostedFileContent` within `CodeInterpreterToolResultContent`:
+
+```csharp
+// Collect generated files from response
+List<HostedFileContent> hostedFiles = response.Messages
+    .SelectMany(m => m.Contents.OfType<CodeInterpreterToolResultContent>())
+    .Where(c => c.Outputs is not null)
+    .SelectMany(c => c.Outputs!.OfType<HostedFileContent>())
+    .ToList();
+
+// Download and save each file
+foreach (HostedFileContent file in hostedFiles)
+{
+    using HttpResponse fileResponse = await anthropicClient.Beta.Files.Download(
+        file.FileId,
+        new FileDownloadParams { Betas = ["files-api-2025-04-14"] });
+
+    string fileName = $"presentation_{file.FileId.Substring(0, 8)}.pptx";
+    await using FileStream fileStream = File.Create(fileName);
+    Stream contentStream = await fileResponse.ReadAsStream();
+    await contentStream.CopyToAsync(fileStream);
+}
+```

dotnet/samples/GettingStarted/AgentWithAnthropic/README.md

@@ -29,6 +29,7 @@ To use Anthropic with Azure Foundry, you can check the sample [AgentProviders/Ag
 |[Running a simple agent](./Agent_Anthropic_Step01_Running/)|This sample demonstrates how to create and run a basic agent with Anthropic Claude|
 |[Using reasoning with an agent](./Agent_Anthropic_Step02_Reasoning/)|This sample demonstrates how to use extended thinking/reasoning capabilities with Anthropic Claude agents|
 |[Using function tools with an agent](./Agent_Anthropic_Step03_UsingFunctionTools/)|This sample demonstrates how to use function tools with an Anthropic Claude agent|
+|[Using Skills with an agent](./Agent_Anthropic_Step04_UsingSkills/)|This sample demonstrates how to use Anthropic-managed Skills (e.g., pptx) with an Anthropic Claude agent|
 
 ## Running the samples from the console
 

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/Program.cs

@@ -20,7 +20,10 @@ var embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_E
 // Replace this with a vector store implementation of your choice that can persist the chat history long term.
 VectorStore vectorStore = new InMemoryVectorStore(new InMemoryVectorStoreOptions()
 {
-    EmbeddingGenerator = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+    // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+    // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+    // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+    EmbeddingGenerator = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
         .GetEmbeddingClient(embeddingDeploymentName)
         .AsIEmbeddingGenerator()
 });
@@ -28,33 +31,38 @@ VectorStore vectorStore = new InMemoryVectorStore(new InMemoryVectorStoreOptions
 // Create the agent and add the ChatHistoryMemoryProvider to store chat messages in the vector store.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new ChatHistoryMemoryProvider(
+        AIContextProviders = [new ChatHistoryMemoryProvider(
             vectorStore,
             collectionName: "chathistory",
             vectorDimensions: 3072,
-            // Configure the scope values under which chat messages will be stored.
-            // In this case, we are using a fixed user ID and a unique session ID for each new session.
-            storageScope: new() { UserId = "UID1", SessionId = Guid.NewGuid().ToString() },
-            // Configure the scope which would be used to search for relevant prior messages.
-            // In this case, we are searching for any messages for the user across all sessions.
-            searchScope: new() { UserId = "UID1" }))
+            // Callback to configure the initial state of the ChatHistoryMemoryProvider.
+            // The ChatHistoryMemoryProvider stores its state in the AgentSession and this callback
+            // will be called whenever the ChatHistoryMemoryProvider cannot find existing state in the session,
+            // typically the first time it is used with a new session.
+            session => new ChatHistoryMemoryProvider.State(
+                // Configure the scope values under which chat messages will be stored.
+                // In this case, we are using a fixed user ID and a unique session ID for each new session.
+                storageScope: new() { UserId = "UID1", SessionId = Guid.NewGuid().ToString() },
+                // Configure the scope which would be used to search for relevant prior messages.
+                // In this case, we are searching for any messages for the user across all sessions.
+                searchScope: new() { UserId = "UID1" }))]
     });
 
 // Start a new session for the agent conversation.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 // Run the agent with the session that stores conversation history in the vector store.
 Console.WriteLine(await agent.RunAsync("I like jokes about Pirates. Tell me a joke about a pirate.", session));
 
 // Start a second session. Since we configured the search scope to be across all sessions for the user,
 // the agent should remember that the user likes pirate jokes.
-AgentSession? session2 = await agent.GetNewSessionAsync();
+AgentSession? session2 = await agent.CreateSessionAsync();
 
 // Run the agent with the second session.
 Console.WriteLine(await agent.RunAsync("Tell me a joke that I might like.", session2));

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/Program.cs

@@ -24,27 +24,31 @@ using HttpClient mem0HttpClient = new();
 mem0HttpClient.BaseAddress = new Uri(mem0ServiceUri);
 mem0HttpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Token", mem0ApiKey);
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions()
     {
         ChatOptions = new() { Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details." },
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(ctx.SerializedState.ValueKind is not JsonValueKind.Null and not JsonValueKind.Undefined
-            // If each session should have its own Mem0 scope, you can create a new id per session here:
-            // ? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() })
-            // In this case we are storing memories scoped by application and user instead so that memories are retained across threads.
-            ? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ApplicationId = "getting-started-agents", UserId = "sample-user" })
-            // For cases where we are restoring from serialized state:
-            : new Mem0Provider(mem0HttpClient, ctx.SerializedState, ctx.JsonSerializerOptions))
+        // The stateInitializer can be used to customize the Mem0 scope per session and it will be called each time a session
+        // is encountered by the Mem0Provider that does not already have Mem0Provider state stored on the session.
+        // If each session should have its own Mem0 scope, you can create a new id per session via the stateInitializer, e.g.:
+        // new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() }))
+        // In our case we are storing memories scoped by application and user instead so that memories are retained across threads.
+        AIContextProviders = [new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ApplicationId = "getting-started-agents", UserId = "sample-user" }))]
     });
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 // Clear any existing memories for this scope to demonstrate fresh behavior.
-Mem0Provider mem0Provider = session.GetService<Mem0Provider>()!;
-await mem0Provider.ClearStoredMemoriesAsync();
+// Note that the ClearStoredMemoriesAsync method will clear memories
+// using the scope stored in the session, or provided via the stateInitializer.
+Mem0Provider mem0Provider = agent.GetService<Mem0Provider>()!;
+await mem0Provider.ClearStoredMemoriesAsync(session);
 
 Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
 Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));
@@ -55,10 +59,10 @@ await Task.Delay(TimeSpan.FromSeconds(2));
 Console.WriteLine(await agent.RunAsync("What do you already know about my upcoming trip?", session));
 
 Console.WriteLine("\n>> Serialize and deserialize the session to demonstrate persisted state\n");
-JsonElement serializedSession = session.Serialize();
+JsonElement serializedSession = await agent.SerializeSessionAsync(session);
 AgentSession restoredSession = await agent.DeserializeSessionAsync(serializedSession);
 Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredSession));
 
 Console.WriteLine("\n>> Start a new session that shares the same Mem0 scope\n");
-AgentSession newSession = await agent.GetNewSessionAsync();
+AgentSession newSession = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("Summarize what you already know about me.", newSession));

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step03_CustomMemory/Program.cs

@@ -18,9 +18,12 @@ using SampleApp;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 ChatClient chatClient = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName);
 
 // Create the agent and provide a factory to add our custom memory component to
@@ -33,11 +36,11 @@ ChatClient chatClient = new AzureOpenAIClient(
 AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
 {
     ChatOptions = new() { Instructions = "You are a friendly assistant. Always address the user by their name." },
-    AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new UserInfoMemory(chatClient.AsIChatClient(), ctx.SerializedState, ctx.JsonSerializerOptions))
+    AIContextProviders = [new UserInfoMemory(chatClient.AsIChatClient())]
 });
 
 // Create a new session for the conversation.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 Console.WriteLine(">> Use session with blank memory\n");
 
@@ -47,7 +50,7 @@ Console.WriteLine(await agent.RunAsync("My name is Ruaidhrí", session));
 Console.WriteLine(await agent.RunAsync("I am 20 years old", session));
 
 // We can serialize the session. The serialized state will include the state of the memory component.
-var sesionElement = session.Serialize();
+JsonElement sesionElement = await agent.SerializeSessionAsync(session);
 
 Console.WriteLine("\n>> Use deserialized session with previously created memories\n");
 
@@ -55,10 +58,10 @@ Console.WriteLine("\n>> Use deserialized session with previously created memorie
 var deserializedSession = await agent.DeserializeSessionAsync(sesionElement);
 Console.WriteLine(await agent.RunAsync("What is my name and age?", deserializedSession));
 
-Console.WriteLine("\n>> Read memories from memory component\n");
+Console.WriteLine("\n>> Read memories using memory component\n");
 
-// It's possible to access the memory component via the session's GetService method.
-var userInfo = deserializedSession.GetService<UserInfoMemory>()?.UserInfo;
+// It's possible to access the memory component via the agent's GetService method.
+var userInfo = agent.GetService<UserInfoMemory>()?.GetUserInfo(deserializedSession);
 
 // Output the user info that was captured by the memory component.
 Console.WriteLine($"MEMORY - User Name: {userInfo?.UserName}");
@@ -66,12 +69,12 @@ Console.WriteLine($"MEMORY - User Age: {userInfo?.UserAge}");
 
 Console.WriteLine("\n>> Use new session with previously created memories\n");
 
-// It is also possible to set the memories in a memory component on an individual session.
+// It is also possible to set the memories using a memory component on an individual session.
 // This is useful if we want to start a new session, but have it share the same memories as a previous session.
-var newSession = await agent.GetNewSessionAsync();
-if (userInfo is not null && newSession.GetService<UserInfoMemory>() is UserInfoMemory newSessionMemory)
+var newSession = await agent.CreateSessionAsync();
+if (userInfo is not null && agent.GetService<UserInfoMemory>() is UserInfoMemory newSessionMemory)
 {
-    newSessionMemory.UserInfo = userInfo;
+    newSessionMemory.SetUserInfo(newSession, userInfo);
 }
 
 // Invoke the agent and output the text result.
@@ -86,28 +89,27 @@ namespace SampleApp
     internal sealed class UserInfoMemory : AIContextProvider
     {
         private readonly IChatClient _chatClient;
+        private readonly Func<AgentSession?, UserInfo> _stateInitializer;
 
-        public UserInfoMemory(IChatClient chatClient, UserInfo? userInfo = null)
+        public UserInfoMemory(IChatClient chatClient, Func<AgentSession?, UserInfo>? stateInitializer = null)
         {
             this._chatClient = chatClient;
-            this.UserInfo = userInfo ?? new UserInfo();
+            this._stateInitializer = stateInitializer ?? (_ => new UserInfo());
         }
 
-        public UserInfoMemory(IChatClient chatClient, JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null)
+        public UserInfo GetUserInfo(AgentSession session)
+            => session.StateBag.GetValue<UserInfo>(nameof(UserInfoMemory)) ?? new UserInfo();
+
+        public void SetUserInfo(AgentSession session, UserInfo userInfo)
+            => session.StateBag.SetValue(nameof(UserInfoMemory), userInfo);
+
+        protected override async ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
         {
-            this._chatClient = chatClient;
+            var userInfo = context.Session?.StateBag.GetValue<UserInfo>(nameof(UserInfoMemory))
+                ?? this._stateInitializer.Invoke(context.Session);
 
-            this.UserInfo = serializedState.ValueKind == JsonValueKind.Object ?
-                serializedState.Deserialize<UserInfo>(jsonSerializerOptions)! :
-                new UserInfo();
-        }
-
-        public UserInfo UserInfo { get; set; }
-
-        public override async ValueTask InvokedAsync(InvokedContext context, CancellationToken cancellationToken = default)
-        {
             // Try and extract the user name and age from the message if we don't have it already and it's a user message.
-            if ((this.UserInfo.UserName is null || this.UserInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
+            if ((userInfo.UserName is null || userInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
             {
                 var result = await this._chatClient.GetResponseAsync<UserInfo>(
                     context.RequestMessages,
@@ -117,36 +119,43 @@ namespace SampleApp
                     },
                     cancellationToken: cancellationToken);
 
-                this.UserInfo.UserName ??= result.Result.UserName;
-                this.UserInfo.UserAge ??= result.Result.UserAge;
+                userInfo.UserName ??= result.Result.UserName;
+                userInfo.UserAge ??= result.Result.UserAge;
             }
+
+            context.Session?.StateBag.SetValue(nameof(UserInfoMemory), userInfo);
         }
 
-        public override ValueTask<AIContext> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
+            var inputContext = context.AIContext;
+            var userInfo = context.Session?.StateBag.GetValue<UserInfo>(nameof(UserInfoMemory))
+                ?? this._stateInitializer.Invoke(context.Session);
+
             StringBuilder instructions = new();
+            if (!string.IsNullOrEmpty(inputContext.Instructions))
+            {
+                instructions.AppendLine(inputContext.Instructions);
+            }
 
             // If we don't already know the user's name and age, add instructions to ask for them, otherwise just provide what we have to the context.
             instructions
                 .AppendLine(
-                    this.UserInfo.UserName is null ?
+                    userInfo.UserName is null ?
                         "Ask the user for their name and politely decline to answer any questions until they provide it." :
-                        $"The user's name is {this.UserInfo.UserName}.")
+                        $"The user's name is {userInfo.UserName}.")
                 .AppendLine(
-                    this.UserInfo.UserAge is null ?
+                    userInfo.UserAge is null ?
                         "Ask the user for their age and politely decline to answer any questions until they provide it." :
-                        $"The user's age is {this.UserInfo.UserAge}.");
+                        $"The user's age is {userInfo.UserAge}.");
 
             return new ValueTask<AIContext>(new AIContext
             {
-                Instructions = instructions.ToString()
+                Instructions = instructions.ToString(),
+                Messages = inputContext.Messages,
+                Tools = inputContext.Tools
             });
         }
-
-        public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
-        {
-            return JsonSerializer.SerializeToElement(this.UserInfo, jsonSerializerOptions);
-        }
     }
 
     internal sealed class UserInfo

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Program.cs

@@ -5,7 +5,6 @@
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using OpenAI;
-using OpenAI.Responses;
 
 var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
 var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-5";
@@ -15,14 +14,10 @@ var client = new OpenAIClient(apiKey)
         .AsIChatClient().AsBuilder()
         .ConfigureOptions(o =>
         {
-            o.RawRepresentationFactory = _ => new CreateResponseOptions()
+            o.Reasoning = new()
             {
-                ReasoningOptions = new()
-                {
-                    ReasoningEffortLevel = ResponseReasoningEffortLevel.Medium,
-                    // Verbosity requires OpenAI verified Organization
-                    ReasoningSummaryVerbosity = ResponseReasoningSummaryVerbosity.Detailed
-                }
+                Effort = ReasoningEffort.Medium,
+                Output = ReasoningOutput.Full,
             };
         }).Build();
 

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Program.cs

@@ -30,7 +30,7 @@ using JsonDocument createConversationResultAsJson = JsonDocument.Parse(createCon
 string conversationId = createConversationResultAsJson.RootElement.GetProperty("id"u8)!.GetString()!;
 
 // Create a session for the conversation - this enables conversation state management for subsequent turns
-AgentSession session = await agent.GetNewSessionAsync(conversationId);
+AgentSession session = await agent.CreateSessionAsync(conversationId);
 
 Console.WriteLine("=== Multi-turn Conversation Demo ===\n");
 

dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/README.md

@@ -33,7 +33,7 @@ The `AgentSession` works with `ChatClientAgentRunOptions` to link the agent to a
 ChatClientAgentRunOptions agentRunOptions = new() { ChatOptions = new ChatOptions() { ConversationId = conversationId } };
 
 // Create a session for the conversation
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 // First call links the session to the conversation
 ChatCompletion firstResponse = await agent.RunAsync([firstMessage], session, agentRunOptions);
@@ -59,7 +59,7 @@ foreach (ClientResult result in getConversationItemsResults.GetRawPages())
 1. **Create an OpenAI Client**: Initialize an `OpenAIClient` with your API key
 2. **Create a Conversation**: Use `ConversationClient` to create a server-side conversation
 3. **Create an Agent**: Initialize an `OpenAIResponseClientAgent` with the desired model and instructions
-4. **Create a Session**: Call `agent.GetNewSessionAsync()` to create a new conversation session
+4. **Create a Session**: Call `agent.CreateSessionAsync()` to create a new conversation session
 5. **Link Session to Conversation**: Pass `ChatClientAgentRunOptions` with the `ConversationId` on the first call
 6. **Send Messages**: Subsequent calls to `agent.RunAsync()` only need the session - context is maintained
 7. **Cleanup**: Delete the conversation when done using `conversationClient.DeleteConversation()`

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/Program.cs

@@ -18,9 +18,12 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 var embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-3-large";
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient azureOpenAIClient = new(
     new Uri(endpoint),
-    new AzureCliCredential());
+    new DefaultAzureCredential());
 
 // Create an In-Memory vector store that uses the Azure OpenAI embedding model to generate embeddings.
 VectorStore vectorStore = new InMemoryVectorStore(new()
@@ -62,15 +65,19 @@ AIAgent agent = azureOpenAIClient
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)),
-        // Since we are using ChatCompletion which stores chat history locally, we can also add a message removal policy
+        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)],
+        // Since we are using ChatCompletion which stores chat history locally, we can also add a message filter
         // that removes messages produced by the TextSearchProvider before they are added to the chat history, so that
         // we don't bloat chat history with all the search result messages.
-        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(new InMemoryChatHistoryProvider(ctx.SerializedState, ctx.JsonSerializerOptions)
-            .WithAIContextProviderMessageRemoval()),
+        // By default the chat history provider will store all messages, except for those that came from chat history in the first place.
+        // We also want to maintain that exclusion here.
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
+        {
+            StorageInputMessageFilter = messages => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory)
+        }),
     });
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 Console.WriteLine(">> Asking about returns\n");
 Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", session));

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/Program.cs

@@ -19,9 +19,12 @@ var embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_E
 var afOverviewUrl = "https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/agent-framework/overview/agent-framework-overview.md";
 var afMigrationUrl = "https://raw.githubusercontent.com/MicrosoftDocs/semantic-kernel-docs/refs/heads/main/agent-framework/migration-guide/from-semantic-kernel/index.md";
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AzureOpenAIClient azureOpenAIClient = new(
     new Uri(endpoint),
-    new AzureCliCredential());
+    new DefaultAzureCredential());
 
 // Create a Qdrant vector store that uses the Azure OpenAI embedding model to generate embeddings.
 QdrantClient client = new("localhost");
@@ -71,10 +74,10 @@ AIAgent agent = azureOpenAIClient
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief." },
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions))
+        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)]
     });
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 Console.WriteLine(">> Asking about SK sessions\n");
 Console.WriteLine(await agent.RunAsync("Hi! How do I create a thread/session in Semantic Kernel?", session));

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/Program.cs

@@ -22,17 +22,20 @@ TextSearchProviderOptions textSearchOptions = new()
     RecentMessageMemoryLimit = 6,
 };
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(MockSearchAsync, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions))
+        AIContextProviders = [new TextSearchProvider(MockSearchAsync, textSearchOptions)]
     });
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 Console.WriteLine(">> Asking about returns\n");
 Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", session));

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/Program.cs

@@ -15,9 +15,12 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOIN
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Create an AI Project client and get an OpenAI client that works with the foundry service.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIProjectClient aiProjectClient = new(
     new Uri(endpoint),
-    new AzureCliCredential());
+    new DefaultAzureCredential());
 OpenAIClient openAIClient = aiProjectClient.GetProjectOpenAIClient();
 
 // Upload the file that contains the data to be used for RAG to the Foundry service.
@@ -43,7 +46,7 @@ AIAgent agent = await aiProjectClient
         instructions: "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
         tools: [fileSearchTool]);
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 Console.WriteLine(">> Asking about returns\n");
 Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", session));

dotnet/samples/GettingStarted/Agents/Agent_Step01_Running/Program.cs

@@ -10,9 +10,12 @@ using OpenAI.Chat;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 

dotnet/samples/GettingStarted/Agents/Agent_Step02_MultiturnConversation/Program.cs

@@ -10,19 +10,22 @@ using OpenAI.Chat;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 
 // Invoke the agent with a multi-turn conversation, where the context is preserved in the session object.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
 Console.WriteLine(await agent.RunAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", session));
 
 // Invoke the agent with a multi-turn conversation and streaming, where the context is preserved in the session object.
-session = await agent.GetNewSessionAsync();
+session = await agent.CreateSessionAsync();
 await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate.", session))
 {
     Console.WriteLine(update);

dotnet/samples/GettingStarted/Agents/Agent_Step03_UsingFunctionTools/Program.cs

@@ -18,9 +18,12 @@ static string GetWeather([Description("The location to get the weather for.")] s
     => $"The weather in {location} is cloudy with a high of 15°C.";
 
 // Create the chat client and agent, and provide the function tool to the agent.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);
 

dotnet/samples/GettingStarted/Agents/Agent_Step04_UsingFunctionToolsWithApprovals/Program.cs

@@ -23,42 +23,43 @@ static string GetWeather([Description("The location to get the weather for.")] s
 
 // Create the chat client and agent.
 // Note that we are wrapping the function tool with ApprovalRequiredAIFunction to require user approval before invoking it.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are a helpful assistant", tools: [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(GetWeather))]);
 
-// Call the agent and check if there are any user input requests to handle.
-AgentSession session = await agent.GetNewSessionAsync();
-var response = await agent.RunAsync("What is the weather like in Amsterdam?", session);
-var userInputRequests = response.UserInputRequests.ToList();
+// Call the agent and check if there are any function approval requests to handle.
+// For simplicity, we are assuming here that only function approvals are pending.
+AgentSession session = await agent.CreateSessionAsync();
+AgentResponse response = await agent.RunAsync("What is the weather like in Amsterdam?", session);
+List<FunctionApprovalRequestContent> approvalRequests = response.Messages.SelectMany(m => m.Contents).OfType<FunctionApprovalRequestContent>().ToList();
 
 // For streaming use:
 // var updates = await agent.RunStreamingAsync("What is the weather like in Amsterdam?", session).ToListAsync();
-// userInputRequests = updates.SelectMany(x => x.UserInputRequests).ToList();
+// approvalRequests = updates.SelectMany(x => x.Contents).OfType<FunctionApprovalRequestContent>().ToList();
 
-while (userInputRequests.Count > 0)
+while (approvalRequests.Count > 0)
 {
     // Ask the user to approve each function call request.
-    // For simplicity, we are assuming here that only function approval requests are being made.
-    var userInputResponses = userInputRequests
-        .OfType<FunctionApprovalRequestContent>()
-        .Select(functionApprovalRequest =>
+    List<ChatMessage> userInputResponses = approvalRequests
+        .ConvertAll(functionApprovalRequest =>
         {
             Console.WriteLine($"The agent would like to invoke the following function, please reply Y to approve: Name {functionApprovalRequest.FunctionCall.Name}");
             return new ChatMessage(ChatRole.User, [functionApprovalRequest.CreateResponse(Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) ?? false)]);
-        })
-        .ToList();
+        });
 
     // Pass the user input responses back to the agent for further processing.
     response = await agent.RunAsync(userInputResponses, session);
 
-    userInputRequests = response.UserInputRequests.ToList();
+    approvalRequests = response.Messages.SelectMany(m => m.Contents).OfType<FunctionApprovalRequestContent>().ToList();
 
     // For streaming use:
     // updates = await agent.RunStreamingAsync(userInputResponses, session).ToListAsync();
-    // userInputRequests = updates.SelectMany(x => x.UserInputRequests).ToList();
+    // approvalRequests = updates.SelectMany(x => x.Contents).OfType<FunctionApprovalRequestContent>().ToList();
 }
 
 Console.WriteLine($"\nAgent: {response}");

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs

@@ -15,9 +15,12 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Create chat client to be used by chat client agents.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 ChatClient chatClient = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
         .GetChatClient(deploymentName);
 
 // Create the ChatClientAgent with the specified name and instructions.

dotnet/samples/GettingStarted/Agents/Agent_Step06_PersistedConversations/Program.cs

@@ -12,20 +12,23 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Create the agent
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
 
 // Start a new session for the agent conversation.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 // Run the agent with a new session.
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
 
 // Serialize the session state to a JsonElement, so it can be stored for later use.
-JsonElement serializedSession = session.Serialize();
+JsonElement serializedSession = await agent.SerializeSessionAsync(session);
 
 // Save the serialized session to a temporary file (for demonstration purposes).
 string tempFilePath = Path.GetTempFileName();

dotnet/samples/GettingStarted/Agents/Agent_Step07_3rdPartyChatHistoryStorage/Program.cs

@@ -2,7 +2,9 @@
 
 #pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
 
-// This sample shows how to create and use a simple AI agent with a conversation that can be persisted to disk.
+// This sample shows how to create and use a simple AI agent with custom ChatHistoryProvider that stores chat history in a custom storage location.
+// The state of the custom ChatHistoryProvider (SessionDbKey) is stored in the AgentSession's StateBag, so that when the session is resumed later,
+// the chat history can be retrieved from the custom storage location.
 
 using System.Text.Json;
 using Azure.AI.OpenAI;
@@ -23,23 +25,23 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 VectorStore vectorStore = new InMemoryVectorStore();
 
 // Create the agent
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
-        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(
-            // Create a new ChatHistoryProvider for this agent that stores chat history in a vector store.
-            // Each session must get its own copy of the VectorChatHistoryProvider, since the provider
-            // also contains the id that the chat history is stored under.
-            new VectorChatHistoryProvider(vectorStore, ctx.SerializedState, ctx.JsonSerializerOptions))
+        // Create a new ChatHistoryProvider for this agent that stores chat history in a vector store.
+        ChatHistoryProvider = new VectorChatHistoryProvider(vectorStore)
     });
 
 // Start a new session for the agent conversation.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 // Run the agent with the session that stores chat history in the vector store.
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
@@ -47,7 +49,7 @@ Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session
 // Serialize the session state, so it can be stored for later use.
 // Since the chat history is stored in the vector store, the serialized session
 // only contains the guid that the messages are stored under in the vector store.
-JsonElement serializedSession = session.Serialize();
+JsonElement serializedSession = await agent.SerializeSessionAsync(session);
 
 Console.WriteLine("\n--- Serialized session ---\n");
 Console.WriteLine(JsonSerializer.Serialize(serializedSession, new JsonSerializerOptions { WriteIndented = true }));
@@ -61,51 +63,78 @@ AgentSession resumedSession = await agent.DeserializeSessionAsync(serializedSess
 // Run the agent with the session that stores chat history in the vector store a second time.
 Console.WriteLine(await agent.RunAsync("Now tell the same joke in the voice of a pirate, and add some emojis to the joke.", resumedSession));
 
-// We can access the VectorChatHistoryProvider via the session's GetService method if we need to read the key under which chat history is stored.
-var chatHistoryProvider = resumedSession.GetService<VectorChatHistoryProvider>()!;
-Console.WriteLine($"\nSession is stored in vector store under key: {chatHistoryProvider.SessionDbKey}");
+// We can access the VectorChatHistoryProvider via the agent's GetService method
+// if we need to read the key under which chat history is stored. The key is stored
+// in the session state, and therefore we need to provide the session when reading it.
+var chatHistoryProvider = agent.GetService<VectorChatHistoryProvider>()!;
+Console.WriteLine($"\nSession is stored in vector store under key: {chatHistoryProvider.GetSessionDbKey(resumedSession)}");
 
 namespace SampleApp
 {
     /// <summary>
     /// A sample implementation of <see cref="ChatHistoryProvider"/> that stores chat history in a vector store.
+    /// State (the session DB key) is stored in the <see cref="AgentSession.StateBag"/> so it roundtrips
+    /// automatically with session serialization.
     /// </summary>
     internal sealed class VectorChatHistoryProvider : ChatHistoryProvider
     {
         private readonly VectorStore _vectorStore;
+        private readonly Func<AgentSession?, State> _stateInitializer;
+        private readonly string _stateKey;
 
-        public VectorChatHistoryProvider(VectorStore vectorStore, JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null)
+        /// <inheritdoc />
+        public override string StateKey => this._stateKey;
+
+        public VectorChatHistoryProvider(
+            VectorStore vectorStore,
+            Func<AgentSession?, State>? stateInitializer = null,
+            string? stateKey = null)
         {
             this._vectorStore = vectorStore ?? throw new ArgumentNullException(nameof(vectorStore));
-
-            if (serializedState.ValueKind is JsonValueKind.String)
-            {
-                // Here we can deserialize the session id so that we can access the same messages as before the suspension.
-                this.SessionDbKey = serializedState.Deserialize<string>();
-            }
+            this._stateInitializer = stateInitializer ?? (_ => new State(Guid.NewGuid().ToString("N")));
+            this._stateKey = stateKey ?? base.StateKey;
         }
 
-        public string? SessionDbKey { get; private set; }
+        public string GetSessionDbKey(AgentSession session)
+            => this.GetOrInitializeState(session).SessionDbKey;
 
-        public override async ValueTask<IEnumerable<ChatMessage>> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        private State GetOrInitializeState(AgentSession? session)
         {
+            if (session?.StateBag.TryGetValue<State>(this._stateKey, out var state) is true && state is not null)
+            {
+                return state;
+            }
+
+            state = this._stateInitializer(session);
+            if (session is not null)
+            {
+                session.StateBag.SetValue(this._stateKey, state);
+            }
+
+            return state;
+        }
+
+        protected override async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        {
+            var state = this.GetOrInitializeState(context.Session);
             var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
             await collection.EnsureCollectionExistsAsync(cancellationToken);
 
             var records = await collection
                 .GetAsync(
-                    x => x.SessionId == this.SessionDbKey, 10,
+                    x => x.SessionId == state.SessionDbKey, 10,
                     new() { OrderBy = x => x.Descending(y => y.Timestamp) },
                     cancellationToken)
                 .ToListAsync(cancellationToken);
 
-            var messages = records.ConvertAll(x => JsonSerializer.Deserialize<ChatMessage>(x.SerializedMessage!)!)
-;
+            var messages = records.ConvertAll(x => JsonSerializer.Deserialize<ChatMessage>(x.SerializedMessage!)!);
             messages.Reverse();
-            return messages;
+            return messages
+                .Select(message => message.WithAgentRequestMessageSource(AgentRequestMessageSourceType.ChatHistory, this.GetType().FullName!))
+                .Concat(context.RequestMessages);
         }
 
-        public override async ValueTask InvokedAsync(InvokedContext context, CancellationToken cancellationToken = default)
+        protected override async ValueTask InvokedCoreAsync(InvokedContext context, CancellationToken cancellationToken = default)
         {
             // Don't store messages if the request failed.
             if (context.InvokeException is not null)
@@ -113,28 +142,39 @@ namespace SampleApp
                 return;
             }
 
-            this.SessionDbKey ??= Guid.NewGuid().ToString("N");
+            var state = this.GetOrInitializeState(context.Session);
 
             var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
             await collection.EnsureCollectionExistsAsync(cancellationToken);
 
-            // Add both request and response messages to the store
+            // Add both request and response messages to the store, excluding messages that came from chat history.
             // Optionally messages produced by the AIContextProvider can also be persisted (not shown).
-            var allNewMessages = context.RequestMessages.Concat(context.AIContextProviderMessages ?? []).Concat(context.ResponseMessages ?? []);
+            var allNewMessages = context.RequestMessages
+                .Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory)
+                .Concat(context.ResponseMessages ?? []);
 
             await collection.UpsertAsync(allNewMessages.Select(x => new ChatHistoryItem()
             {
-                Key = this.SessionDbKey + x.MessageId,
+                Key = state.SessionDbKey + x.MessageId,
                 Timestamp = DateTimeOffset.UtcNow,
-                SessionId = this.SessionDbKey,
+                SessionId = state.SessionDbKey,
                 SerializedMessage = JsonSerializer.Serialize(x),
                 MessageText = x.Text
             }), cancellationToken);
         }
 
-        public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null) =>
-            // We have to serialize the session id, so that on deserialization we can retrieve the messages using the same session id.
-            JsonSerializer.SerializeToElement(this.SessionDbKey);
+        /// <summary>
+        /// Represents the per-session state stored in the <see cref="AgentSession.StateBag"/>.
+        /// </summary>
+        public sealed class State
+        {
+            public State(string sessionDbKey)
+            {
+                this.SessionDbKey = sessionDbKey ?? throw new ArgumentNullException(nameof(sessionDbKey));
+            }
+
+            public string SessionDbKey { get; }
+        }
 
         /// <summary>
         /// The data structure used to store chat history items in the vector store.

dotnet/samples/GettingStarted/Agents/Agent_Step08_Observability/Program.cs

@@ -27,7 +27,10 @@ if (!string.IsNullOrWhiteSpace(applicationInsightsConnectionString))
 using var tracerProvider = tracerProviderBuilder.Build();
 
 // Create the agent, and enable OpenTelemetry instrumentation.
-AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker")
     .AsBuilder()

dotnet/samples/GettingStarted/Agents/Agent_Step09_DependencyInjection/Program.cs

@@ -21,9 +21,12 @@ HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
 builder.Services.AddSingleton(new ChatClientAgentOptions() { Name = "Joker", ChatOptions = new() { Instructions = "You are good at telling jokes." } });
 
 // Add a chat client to the service collection.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 builder.Services.AddKeyedChatClient("AzureOpenAI", (sp) => new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
         .GetChatClient(deploymentName)
         .AsIChatClient());
 
@@ -49,7 +52,7 @@ internal sealed class SampleService(AIAgent agent, IHostApplicationLifetime appL
     public async Task StartAsync(CancellationToken cancellationToken)
     {
         // Create a session that will be used for the entirety of the service lifetime so that the user can ask follow up questions.
-        this._session = await agent.GetNewSessionAsync(cancellationToken);
+        this._session = await agent.CreateSessionAsync(cancellationToken);
         _ = this.RunAsync(appLifetime.ApplicationStopping);
     }
 

dotnet/samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/Program.cs

@@ -12,7 +12,10 @@ using ModelContextProtocol.Server;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
-var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());
 
 // Create a server side persistent agent
 var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(

dotnet/samples/GettingStarted/Agents/Agent_Step11_UsingImages/Program.cs

@@ -11,7 +11,10 @@ using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o";
 
-var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+var agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(
         name: "VisionAgent",
@@ -22,7 +25,7 @@ ChatMessage message = new(ChatRole.User, [
     new UriContent("https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg", "image/jpeg")
 ]);
 
-var session = await agent.GetNewSessionAsync();
+var session = await agent.CreateSessionAsync();
 
 await foreach (var update in agent.RunStreamingAsync(message, session))
 {

dotnet/samples/GettingStarted/Agents/Agent_Step12_AsFunctionTool/Program.cs

@@ -17,9 +17,12 @@ static string GetWeather([Description("The location to get the weather for.")] s
     => $"The weather in {location} is cloudy with a high of 15°C.";
 
 // Create the chat client and agent, and provide the function tool to the agent.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent weatherAgent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetChatClient(deploymentName)
      .AsAIAgent(
         instructions: "You answer questions about the weather.",
@@ -30,7 +33,7 @@ AIAgent weatherAgent = new AzureOpenAIClient(
 // Create the main agent, and provide the weather agent as a function tool.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are a helpful assistant who responds in French.", tools: [weatherAgent.AsAIFunction()]);
 

dotnet/samples/GettingStarted/Agents/Agent_Step13_BackgroundResponsesWithToolsAndPersistence/Program.cs

@@ -19,9 +19,12 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 
 var stateStore = new Dictionary<string, JsonElement?>();
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetResponsesClient(deploymentName)
      .AsAIAgent(
         name: "SpaceNovelWriter",
@@ -32,7 +35,7 @@ AIAgent agent = new AzureOpenAIClient(
 // Enable background responses (only supported by {Azure}OpenAI Responses at this time).
 AgentRunOptions options = new() { AllowBackgroundResponses = true };
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 // Start the initial run.
 AgentResponse response = await agent.RunAsync("Write a very long novel about a team of astronauts exploring an uncharted galaxy.", session, options);
@@ -40,7 +43,7 @@ AgentResponse response = await agent.RunAsync("Write a very long novel about a t
 // Poll for background responses until complete.
 while (response.ContinuationToken is not null)
 {
-    PersistAgentState(session, response.ContinuationToken);
+    await PersistAgentState(agent, session, response.ContinuationToken);
 
     await Task.Delay(TimeSpan.FromSeconds(10));
 
@@ -52,9 +55,9 @@ while (response.ContinuationToken is not null)
 
 Console.WriteLine(response.Text);
 
-void PersistAgentState(AgentSession? session, ResponseContinuationToken? continuationToken)
+async Task PersistAgentState(AIAgent agent, AgentSession? session, ResponseContinuationToken? continuationToken)
 {
-    stateStore["session"] = session!.Serialize();
+    stateStore["session"] = await agent.SerializeSessionAsync(session!);
     stateStore["continuationToken"] = JsonSerializer.SerializeToElement(continuationToken, AgentAbstractionsJsonUtilities.DefaultOptions.GetTypeInfo(typeof(ResponseContinuationToken)));
 }
 

dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/Program.cs

@@ -17,7 +17,10 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o";
 
 // Get a client to create/retrieve server side agents with
-var azureOpenAIClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+var azureOpenAIClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
     .GetChatClient(deploymentName);
 
 [Description("Get the weather for a given location.")]
@@ -45,7 +48,7 @@ var middlewareEnabledAgent = originalAgent
     .Use(GuardrailMiddleware, null)
     .Build();
 
-var session = await middlewareEnabledAgent.GetNewSessionAsync();
+var session = await middlewareEnabledAgent.CreateSessionAsync();
 
 Console.WriteLine("\n\n=== Example 1: Wording Guardrail ===");
 var guardRailedResponse = await middlewareEnabledAgent.RunAsync("Tell me something harmful.");
@@ -210,28 +213,25 @@ async Task<AgentResponse> GuardrailMiddleware(IEnumerable<ChatMessage> messages,
 // This middleware handles Human in the loop console interaction for any user approval required during function calling.
 async Task<AgentResponse> ConsolePromptingApprovalMiddleware(IEnumerable<ChatMessage> messages, AgentSession? session, AgentRunOptions? options, AIAgent innerAgent, CancellationToken cancellationToken)
 {
-    var response = await innerAgent.RunAsync(messages, session, options, cancellationToken);
+    AgentResponse response = await innerAgent.RunAsync(messages, session, options, cancellationToken);
 
-    var userInputRequests = response.UserInputRequests.ToList();
+    // For simplicity, we are assuming here that only function approvals are pending.
+    List<FunctionApprovalRequestContent> approvalRequests = response.Messages.SelectMany(m => m.Contents).OfType<FunctionApprovalRequestContent>().ToList();
 
-    while (userInputRequests.Count > 0)
+    while (approvalRequests.Count > 0)
     {
         // Ask the user to approve each function call request.
-        // For simplicity, we are assuming here that only function approval requests are being made.
-
         // Pass the user input responses back to the agent for further processing.
-        response.Messages = userInputRequests
-            .OfType<FunctionApprovalRequestContent>()
-            .Select(functionApprovalRequest =>
+        response.Messages = approvalRequests
+            .ConvertAll(functionApprovalRequest =>
             {
                 Console.WriteLine($"The agent would like to invoke the following function, please reply Y to approve: Name {functionApprovalRequest.FunctionCall.Name}");
                 return new ChatMessage(ChatRole.User, [functionApprovalRequest.CreateResponse(Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) ?? false)]);
-            })
-            .ToList();
+            });
 
         response = await innerAgent.RunAsync(response.Messages, session, options, cancellationToken);
 
-        userInputRequests = response.UserInputRequests.ToList();
+        approvalRequests = response.Messages.SelectMany(m => m.Contents).OfType<FunctionApprovalRequestContent>().ToList();
     }
 
     return response;

dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/README.md

@@ -7,7 +7,7 @@ This sample demonstrates how to add middleware to intercept:
 
 ## What This Sample Shows
 
-1. Azure OpenAI integration via `AzureOpenAIClient` and `AzureCliCredential`
+1. Azure OpenAI integration via `AzureOpenAIClient` and `DefaultAzureCredential`
 2. Chat client middleware using `ChatClientBuilder.Use(...)`
 3. Agent run middleware (PII redaction and wording guardrails)
 4. Function invocation middleware (logging and overriding a tool result)

dotnet/samples/GettingStarted/Agents/Agent_Step15_Plugins/Program.cs

@@ -27,9 +27,12 @@ services.AddSingleton<AgentPlugin>(); // The plugin depends on WeatherProvider a
 
 IServiceProvider serviceProvider = services.BuildServiceProvider();
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(
         instructions: "You are a helpful assistant that helps people find information.",

dotnet/samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Program.cs

@@ -16,24 +16,30 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Construct the agent, and provide a factory to create an in-memory chat message store with a reducer that keeps only the last 2 non-system messages.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions
     {
         ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
-        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(new InMemoryChatHistoryProvider(new MessageCountingChatReducer(2), ctx.SerializedState, ctx.JsonSerializerOptions))
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(new() { ChatReducer = new MessageCountingChatReducer(2) })
     });
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 // Invoke the agent and output the text result.
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
 
 // Get the chat history to see how many messages are stored.
-IList<ChatMessage>? chatHistory = session.GetService<IList<ChatMessage>>();
+// We can use the ChatHistoryProvider, that is also used by the agent, to read the
+// chat history from the session state, and see how the reducer is affecting the stored messages.
+var provider = agent.GetService<InMemoryChatHistoryProvider>();
+List<ChatMessage>? chatHistory = provider?.GetMessages(session);
 Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
 
 // Invoke the agent a few more times.

dotnet/samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Program.cs

@@ -10,16 +10,19 @@ using OpenAI.Responses;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetResponsesClient(deploymentName)
      .AsAIAgent();
 
 // Enable background responses (only supported by OpenAI Responses at this time).
 AgentRunOptions options = new() { AllowBackgroundResponses = true };
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 // Start the initial run.
 AgentResponse response = await agent.RunAsync("Write a very long novel about otters in space.", session, options);
@@ -41,7 +44,7 @@ Console.WriteLine(response.Text);
 
 // Reset options and session for streaming.
 options = new() { AllowBackgroundResponses = true };
-session = await agent.GetNewSessionAsync();
+session = await agent.CreateSessionAsync();
 
 AgentResponseUpdate? lastReceivedUpdate = null;
 // Start streaming.

dotnet/samples/GettingStarted/Agents/Agent_Step18_DeepResearch/Program.cs

@@ -16,7 +16,10 @@ PersistentAgentsAdministrationClientOptions persistentAgentsClientOptions = new(
 persistentAgentsClientOptions.Retry.NetworkTimeout = TimeSpan.FromMinutes(20);
 
 // Get a client to create/retrieve server side agents with.
-PersistentAgentsClient persistentAgentsClient = new(endpoint, new AzureCliCredential(), persistentAgentsClientOptions);
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+PersistentAgentsClient persistentAgentsClient = new(endpoint, new DefaultAzureCredential(), persistentAgentsClientOptions);
 
 // Define and configure the Deep Research tool.
 DeepResearchToolDefinition deepResearchTool = new(new DeepResearchDetails(
@@ -39,7 +42,7 @@ Console.WriteLine();
 
 try
 {
-    AgentSession session = await agent.GetNewSessionAsync();
+    AgentSession session = await agent.CreateSessionAsync();
 
     await foreach (var response in agent.RunStreamingAsync(Task, session))
     {

dotnet/samples/GettingStarted/Agents/Agent_Step19_Declarative/Program.cs

@@ -11,9 +11,12 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Create the chat client
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 IChatClient chatClient = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetChatClient(deploymentName)
      .AsIChatClient();
 

dotnet/samples/GettingStarted/Agents/Agent_Step20_AdditionalAIContext/Program.cs

@@ -1,13 +1,12 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample shows how to inject additional AI context into a ChatClientAgent using a custom AIContextProvider component that is attached to the agent.
-// The sample also shows how to combine the results from multiple providers into a single class, in order to attach multiple of these to an agent.
+// This sample shows how to inject additional AI context into a ChatClientAgent using custom AIContextProvider components that are attached to the agent.
+// Multiple providers can be attached to an agent, and they will be called in sequence, each receiving the accumulated context from the previous one.
 // This mechanism can be used for various purposes, such as injecting RAG search results or memories into the agent's context.
 // Also note that Agent Framework already provides built-in AIContextProviders for many of these scenarios.
 
 #pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
 
-using System.ComponentModel;
 using System.Text;
 using System.Text.Json;
 using Azure.AI.OpenAI;
@@ -34,9 +33,12 @@ Func<Task<string[]>> loadNextThreeCalendarEvents = async () =>
 };
 
 // Create an agent with an AI context provider attached that aggregates two other providers:
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 AIAgent agent = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(new ChatClientAgentOptions()
     {
@@ -45,27 +47,31 @@ AIAgent agent = new AzureOpenAIClient(
         You manage a TODO list for the user. When the user has completed one of the tasks it can be removed from the TODO list. Only provide the list of TODO items if asked.
         You remind users of upcoming calendar events when the user interacts with you.
         """ },
-        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(new InMemoryChatHistoryProvider()
-            // Use WithAIContextProviderMessageRemoval, so that we don't store the messages from the AI context provider in the chat history.
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
+        {
+            // Use StorageInputMessageFilter to provide a custom filter for messages stored in chat history.
+            // By default the chat history provider will store all messages, except for those that came from chat history in the first place.
+            // In this case, we want to also exclude messages that came from AI context providers.
             // You may want to store these messages, depending on their content and your requirements.
-            .WithAIContextProviderMessageRemoval()),
-        // Add an AI context provider that maintains a todo list for the agent and one that provides upcoming calendar entries.
-        // Wrap these in an AI context provider that aggregates the other two.
-        AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new AggregatingAIContextProvider([
-            AggregatingAIContextProvider.CreateFactory((jsonElement, jsonSerializerOptions) => new TodoListAIContextProvider(jsonElement, jsonSerializerOptions)),
-            AggregatingAIContextProvider.CreateFactory((_, _) => new CalendarSearchAIContextProvider(loadNextThreeCalendarEvents))
-        ], ctx.SerializedState, ctx.JsonSerializerOptions)),
+            StorageInputMessageFilter = messages => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory)
+        }),
+        // Add multiple AI context providers: one that maintains a todo list and one that provides upcoming calendar entries.
+        // The agent will call each provider in sequence, accumulating context from each.
+        AIContextProviders = [
+            new TodoListAIContextProvider(),
+            new CalendarSearchAIContextProvider(loadNextThreeCalendarEvents)
+        ],
     });
 
 // Invoke the agent and output the text result.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("I need to pick up milk from the supermarket.", session) + "\n");
 Console.WriteLine(await agent.RunAsync("I need to take Sally for soccer practice.", session) + "\n");
 Console.WriteLine(await agent.RunAsync("I need to make a dentist appointment for Jimmy.", session) + "\n");
 Console.WriteLine(await agent.RunAsync("I've taken Sally to soccer practice.", session) + "\n");
 
 // We can serialize the session, and it will contain both the chat history and the data that each AI context provider serialized.
-JsonElement serializedSession = session.Serialize();
+JsonElement serializedSession = await agent.SerializeSessionAsync(session);
 // Let's print it to console to show the contents.
 Console.WriteLine(JsonSerializer.Serialize(serializedSession, options: new JsonSerializerOptions() { WriteIndented = true, IndentSize = 2 }) + "\n");
 // The serialized session can be stored long term in a persistent store, but in this case we will just deserialize again and continue the conversation.
@@ -80,51 +86,67 @@ namespace SampleApp
     /// </summary>
     internal sealed class TodoListAIContextProvider : AIContextProvider
     {
-        private readonly List<string> _todoItems = new();
+        private static List<string> GetTodoItems(AgentSession? session)
+            => session?.StateBag.GetValue<List<string>>(nameof(TodoListAIContextProvider)) ?? new List<string>();
 
-        public TodoListAIContextProvider(JsonElement jsonElement, JsonSerializerOptions? jsonSerializerOptions = null)
-        {
-            // Only try and restore the state if we got an array, since any other json would be invalid or undefined/null meaning
-            // it's the first time we are running.
-            if (jsonElement.ValueKind == JsonValueKind.Array)
-            {
-                this._todoItems = JsonSerializer.Deserialize<List<string>>(jsonElement.GetRawText(), jsonSerializerOptions) ?? new List<string>();
-            }
-        }
+        private static void SetTodoItems(AgentSession? session, List<string> items)
+            => session?.StateBag.SetValue(nameof(TodoListAIContextProvider), items);
 
-        public override ValueTask<AIContext> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
+            var inputContext = context.AIContext;
+            var todoItems = GetTodoItems(context.Session);
+
             StringBuilder outputMessageBuilder = new();
             outputMessageBuilder.AppendLine("Your todo list contains the following items:");
 
-            if (this._todoItems.Count == 0)
+            if (todoItems.Count == 0)
             {
                 outputMessageBuilder.AppendLine("  (no items)");
             }
             else
             {
-                for (int i = 0; i < this._todoItems.Count; i++)
+                for (int i = 0; i < todoItems.Count; i++)
                 {
-                    outputMessageBuilder.AppendLine($"{i}. {this._todoItems[i]}");
+                    outputMessageBuilder.AppendLine($"{i}. {todoItems[i]}");
                 }
             }
 
             return new ValueTask<AIContext>(new AIContext
             {
-                Tools = [AIFunctionFactory.Create(this.AddTodoItem), AIFunctionFactory.Create(this.RemoveTodoItem)],
-                Messages = [new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString())]
+                Instructions = inputContext.Instructions,
+                Tools = (inputContext.Tools ?? []).Concat(new AITool[]
+                {
+                    AIFunctionFactory.Create((string item) => AddTodoItem(context.Session, item), "AddTodoItem", "Adds an item to the todo list."),
+                    AIFunctionFactory.Create((int index) => RemoveTodoItem(context.Session, index), "RemoveTodoItem", "Removes an item from the todo list. Index is zero based.")
+                }),
+                Messages =
+                    (inputContext.Messages ?? [])
+                    .Concat(
+                    [
+                        new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString()).WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!)
+                    ])
             });
         }
 
-        [Description("Adds an item to the todo list. Index is zero based.")]
-        private void RemoveTodoItem(int index) =>
-            this._todoItems.RemoveAt(index);
+        private static void RemoveTodoItem(AgentSession? session, int index)
+        {
+            var items = GetTodoItems(session);
+            items.RemoveAt(index);
+            SetTodoItems(session, items);
+        }
 
-        private void AddTodoItem(string item) =>
-            this._todoItems.Add(string.IsNullOrWhiteSpace(item) ? throw new ArgumentException("Item must have a value") : item);
+        private static void AddTodoItem(AgentSession? session, string item)
+        {
+            if (string.IsNullOrWhiteSpace(item))
+            {
+                throw new ArgumentException("Item must have a value");
+            }
 
-        public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null) =>
-            JsonSerializer.SerializeToElement(this._todoItems, jsonSerializerOptions);
+            var items = GetTodoItems(session);
+            items.Add(item);
+            SetTodoItems(session, items);
+        }
     }
 
     /// <summary>
@@ -132,8 +154,9 @@ namespace SampleApp
     /// </summary>
     internal sealed class CalendarSearchAIContextProvider(Func<Task<string[]>> loadNextThreeCalendarEvents) : AIContextProvider
     {
-        public override async ValueTask<AIContext> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override async ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
+            var inputContext = context.AIContext;
             var events = await loadNextThreeCalendarEvents();
 
             StringBuilder outputMessageBuilder = new();
@@ -145,84 +168,16 @@ namespace SampleApp
 
             return new()
             {
+                Instructions = inputContext.Instructions,
                 Messages =
-                [
-                    new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString()),
-                ]
+                    (inputContext.Messages ?? [])
+                    .Concat(
+                    [
+                        new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString()).WithAgentRequestMessageSource(AgentRequestMessageSourceType.AIContextProvider, this.GetType().FullName!)
+                    ])
+                    .ToList(),
+                Tools = inputContext.Tools
             };
         }
     }
-
-    /// <summary>
-    /// An <see cref="AIContextProvider"/> which aggregates multiple AI context providers into one.
-    /// Serialized state for the different providers are stored under their type name.
-    /// Tools and messages from all providers are combined, and instructions are concatenated.
-    /// </summary>
-    internal sealed class AggregatingAIContextProvider : AIContextProvider
-    {
-        private readonly List<AIContextProvider> _providers = new();
-
-        public AggregatingAIContextProvider(ProviderFactory[] providerFactories, JsonElement jsonElement, JsonSerializerOptions? jsonSerializerOptions)
-        {
-            // We received a json object, so let's check if it has some previously serialized state that we can use.
-            if (jsonElement.ValueKind == JsonValueKind.Object)
-            {
-                this._providers = providerFactories
-                    .Select(factory => factory.FactoryMethod(jsonElement.TryGetProperty(factory.ProviderType.Name, out var prop) ? prop : default, jsonSerializerOptions))
-                    .ToList();
-                return;
-            }
-
-            // We didn't receive any valid json, so we can just construct fresh providers.
-            this._providers = providerFactories
-                .Select(factory => factory.FactoryMethod(default, jsonSerializerOptions))
-                .ToList();
-        }
-
-        public override async ValueTask<AIContext> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        {
-            // Invoke all the sub providers.
-            var tasks = this._providers.Select(provider => provider.InvokingAsync(context, cancellationToken).AsTask());
-            var results = await Task.WhenAll(tasks);
-
-            // Combine the results from each sub provider.
-            return new AIContext
-            {
-                Tools = results.SelectMany(r => r.Tools ?? []).ToList(),
-                Messages = results.SelectMany(r => r.Messages ?? []).ToList(),
-                Instructions = string.Join("\n", results.Select(r => r.Instructions).Where(s => !string.IsNullOrEmpty(s)))
-            };
-        }
-
-        public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
-        {
-            Dictionary<string, JsonElement> elements = new();
-            foreach (var provider in this._providers)
-            {
-                JsonElement element = provider.Serialize(jsonSerializerOptions);
-
-                // Don't try to store state for any providers that aren't producing any.
-                if (element.ValueKind != JsonValueKind.Undefined && element.ValueKind != JsonValueKind.Null)
-                {
-                    elements[provider.GetType().Name] = element;
-                }
-            }
-
-            return JsonSerializer.SerializeToElement(elements, jsonSerializerOptions);
-        }
-
-        public static ProviderFactory CreateFactory<TProviderType>(Func<JsonElement, JsonSerializerOptions?, TProviderType> factoryMethod)
-            where TProviderType : AIContextProvider => new()
-            {
-                FactoryMethod = (jsonElement, jsonSerializerOptions) => factoryMethod(jsonElement, jsonSerializerOptions),
-                ProviderType = typeof(TProviderType)
-            };
-
-        public readonly struct ProviderFactory
-        {
-            public Func<JsonElement, JsonSerializerOptions?, AIContextProvider> FactoryMethod { get; init; }
-
-            public Type ProviderType { get; init; }
-        }
-    }
 }

dotnet/samples/GettingStarted/Agents/README.md

@@ -33,7 +33,7 @@ Before you begin, ensure you have the following prerequisites:
 |[Using function tools with approvals](./Agent_Step04_UsingFunctionToolsWithApprovals/)|This sample demonstrates how to use function tools where approvals require human in the loop approvals before execution|
 |[Structured output with a simple agent](./Agent_Step05_StructuredOutput/)|This sample demonstrates how to use structured output with a simple agent|
 |[Persisted conversations with a simple agent](./Agent_Step06_PersistedConversations/)|This sample demonstrates how to persist conversations and reload them later. This is useful for cases where an agent is hosted in a stateless service|
-|[3rd party thread storage with a simple agent](./Agent_Step07_3rdPartyThreadStorage/)|This sample demonstrates how to store conversation history in a 3rd party storage solution|
+|[3rd party chat history storage with a simple agent](./Agent_Step07_3rdPartyChatHistoryStorage/)|This sample demonstrates how to store chat history in a 3rd party storage solution|
 |[Observability with a simple agent](./Agent_Step08_Observability/)|This sample demonstrates how to add telemetry to a simple agent|
 |[Dependency injection with a simple agent](./Agent_Step09_DependencyInjection/)|This sample demonstrates how to add and resolve an agent with a dependency injection container|
 |[Exposing a simple agent as MCP tool](./Agent_Step10_AsMcpTool/)|This sample demonstrates how to expose an agent as an MCP tool|

dotnet/samples/GettingStarted/DeclarativeAgents/ChatClient/Program.cs

@@ -12,9 +12,12 @@ var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? th
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
 
 // Create the chat client
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 IChatClient chatClient = new AzureOpenAIClient(
     new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
      .GetChatClient(deploymentName)
      .AsIChatClient();