Update package versions (#3838)

* Replace Hosted*Tool classes with client static factory methods

* fixed failing test

* mypy fix

* mypy fix 2

* declarative mypy fix

* addressed comments

* ToolProtocol removal

* fixed test

* agents mypy fix

* fix failing tests

* mypy fix

* addressed comments

* fixed tests

* addressed comments + added factory method overrides for azureai v2 client

* mypy fix

* added kwargs to azureai tool methods

* fixed in test

* _sessions fix

* test fix

.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-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

@@ -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."));
 ```

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/concepts/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/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/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).260209.1</PackageVersion>
+    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260209.1</PackageVersion>
+    <GitTag>1.0.0-preview.260209.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/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/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;

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;

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;

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;

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;

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;

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;

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;

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

@@ -61,7 +61,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

@@ -47,7 +47,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/04_AgentOrchestration_Conditionals/Program.cs

@@ -56,7 +56,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 +78,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

@@ -48,7 +48,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

@@ -59,7 +59,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 +299,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

@@ -305,7 +305,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_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/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/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/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/AgentOpenTelemetry/Program.cs

@@ -128,7 +128,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_AzureAIAgentsPersistent/Program.cs

@@ -31,7 +31,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

@@ -40,7 +40,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_CustomImplementation/Program.cs

@@ -28,16 +28,26 @@ namespace SampleApp
     {
         public override string? Name => "UpperCaseParrotAgent";
 
-        public override ValueTask<AgentSession> GetNewSessionAsync(CancellationToken cancellationToken = default)
+        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 JsonElement SerializeSessionCore(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null)
+        {
+            if (session is not CustomAgentSession typedSession)
+            {
+                throw new ArgumentException($"The provided session is not of type {nameof(CustomAgentSession)}.", nameof(session));
+            }
+
+            return typedSession.Serialize(jsonSerializerOptions);
+        }
+
+        protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+            => new(new CustomAgentSession(serializedState, 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,14 +55,14 @@ namespace SampleApp
             }
 
             // Get existing messages from the store
-            var invokingContext = new ChatHistoryProvider.InvokingContext(messages);
+            var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
             var storeMessages = await typedSession.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)
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, messages)
             {
                 ResponseMessages = responseMessages
             };
@@ -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,14 +87,14 @@ namespace SampleApp
             }
 
             // Get existing messages from the store
-            var invokingContext = new ChatHistoryProvider.InvokingContext(messages);
+            var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
             var storeMessages = await typedSession.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)
+            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, messages)
             {
                 ResponseMessages = responseMessages
             };
@@ -136,6 +146,9 @@ namespace SampleApp
 
             internal CustomAgentSession(JsonElement serializedSessionState, JsonSerializerOptions? jsonSerializerOptions = null)
                 : base(serializedSessionState, jsonSerializerOptions) { }
+
+            internal new JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
+                => base.Serialize(jsonSerializerOptions);
         }
     }
 }

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

@@ -47,14 +47,14 @@ AIAgent agent = new AzureOpenAIClient(
     });
 
 // 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

@@ -40,7 +40,7 @@ AIAgent agent = new AzureOpenAIClient(
             : new Mem0Provider(mem0HttpClient, ctx.SerializedState, ctx.JsonSerializerOptions))
     });
 
-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>()!;
@@ -55,10 +55,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 = agent.SerializeSession(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

@@ -37,7 +37,7 @@ AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
 });
 
 // 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 +47,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 = agent.SerializeSession(session);
 
 Console.WriteLine("\n>> Use deserialized session with previously created memories\n");
 
@@ -68,7 +68,7 @@ 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.
 // 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();
+var newSession = await agent.CreateSessionAsync();
 if (userInfo is not null && newSession.GetService<UserInfoMemory>() is UserInfoMemory newSessionMemory)
 {
     newSessionMemory.UserInfo = userInfo;
@@ -104,7 +104,7 @@ namespace SampleApp
 
         public UserInfo UserInfo { get; set; }
 
-        public override async ValueTask InvokedAsync(InvokedContext context, CancellationToken cancellationToken = default)
+        protected override async ValueTask InvokedCoreAsync(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))
@@ -122,7 +122,7 @@ namespace SampleApp
             }
         }
 
-        public override ValueTask<AIContext> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
             StringBuilder instructions = new();
 

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

@@ -70,7 +70,7 @@ AIAgent agent = azureOpenAIClient
             .WithAIContextProviderMessageRemoval()),
     });
 
-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

@@ -74,7 +74,7 @@ AIAgent agent = azureOpenAIClient
         AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, 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

@@ -32,7 +32,7 @@ AIAgent agent = new AzureOpenAIClient(
         AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(new TextSearchProvider(MockSearchAsync, ctx.SerializedState, ctx.JsonSerializerOptions, 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

@@ -43,7 +43,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_Step02_MultiturnConversation/Program.cs

@@ -17,12 +17,12 @@ AIAgent agent = new AzureOpenAIClient(
     .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_Step04_UsingFunctionToolsWithApprovals/Program.cs

@@ -29,36 +29,34 @@ AIAgent agent = new AzureOpenAIClient(
     .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_Step06_PersistedConversations/Program.cs

@@ -19,13 +19,13 @@ AIAgent agent = new AzureOpenAIClient(
     .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 = agent.SerializeSession(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 with the agent session, 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;
@@ -39,7 +41,7 @@ AIAgent agent = new AzureOpenAIClient(
     });
 
 // 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 = agent.SerializeSession(session);
 
 Console.WriteLine("\n--- Serialized session ---\n");
 Console.WriteLine(JsonSerializer.Serialize(serializedSession, new JsonSerializerOptions { WriteIndented = true }));
@@ -87,7 +89,7 @@ namespace SampleApp
 
         public string? SessionDbKey { get; private set; }
 
-        public override async ValueTask<IEnumerable<ChatMessage>> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
             var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
             await collection.EnsureCollectionExistsAsync(cancellationToken);
@@ -105,7 +107,7 @@ namespace SampleApp
             return messages;
         }
 
-        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)
@@ -120,7 +122,7 @@ namespace SampleApp
 
             // Add both request and response messages to the store
             // 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.Concat(context.ResponseMessages ?? []);
 
             await collection.UpsertAsync(allNewMessages.Select(x => new ChatHistoryItem()
             {

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

@@ -49,7 +49,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_Step11_UsingImages/Program.cs

@@ -22,7 +22,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_Step13_BackgroundResponsesWithToolsAndPersistence/Program.cs

@@ -32,7 +32,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 +40,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);
+    PersistAgentState(agent, session, response.ContinuationToken);
 
     await Task.Delay(TimeSpan.FromSeconds(10));
 
@@ -52,9 +52,9 @@ while (response.ContinuationToken is not null)
 
 Console.WriteLine(response.Text);
 
-void PersistAgentState(AgentSession? session, ResponseContinuationToken? continuationToken)
+void PersistAgentState(AIAgent agent, AgentSession? session, ResponseContinuationToken? continuationToken)
 {
-    stateStore["session"] = session!.Serialize();
+    stateStore["session"] = agent.SerializeSession(session!);
     stateStore["continuationToken"] = JsonSerializer.SerializeToElement(continuationToken, AgentAbstractionsJsonUtilities.DefaultOptions.GetTypeInfo(typeof(ResponseContinuationToken)));
 }
 

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

@@ -45,7 +45,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 +210,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_Step16_ChatReduction/Program.cs

@@ -27,7 +27,7 @@ AIAgent agent = new AzureOpenAIClient(
         ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(new InMemoryChatHistoryProvider(new MessageCountingChatReducer(2), ctx.SerializedState, ctx.JsonSerializerOptions))
     });
 
-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));

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

@@ -19,7 +19,7 @@ AIAgent agent = new AzureOpenAIClient(
 // 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 +41,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

@@ -39,7 +39,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_Step20_AdditionalAIContext/Program.cs

@@ -58,14 +58,14 @@ AIAgent agent = new AzureOpenAIClient(
     });
 
 // 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 = agent.SerializeSession(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.
@@ -92,7 +92,7 @@ namespace SampleApp
             }
         }
 
-        public override ValueTask<AIContext> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
             StringBuilder outputMessageBuilder = new();
             outputMessageBuilder.AppendLine("Your todo list contains the following items:");
@@ -132,7 +132,7 @@ 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 events = await loadNextThreeCalendarEvents();
 
@@ -179,7 +179,7 @@ namespace SampleApp
                 .ToList();
         }
 
-        public override async ValueTask<AIContext> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        protected override async ValueTask<AIContext> InvokingCoreAsync(InvokingContext context, CancellationToken cancellationToken = default)
         {
             // Invoke all the sub providers.
             var tasks = this._providers.Select(provider => provider.InvokingAsync(context, cancellationToken).AsTask());

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/FoundryAgents/FoundryAgents_Step01.1_Basics/Program.cs

@@ -6,7 +6,6 @@ using Azure.AI.Projects;
 using Azure.AI.Projects.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
 
 string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
 string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/Program.cs

@@ -29,13 +29,13 @@ ProjectConversation conversation = await conversationsClient.CreateProjectConver
 
 // Providing the conversation Id is not strictly necessary, but by not providing it no information will show up in the Foundry Project UI as conversations.
 // Sessions that don't have a conversation Id will work based on the `PreviousResponseId`.
-AgentSession session = await jokerAgent.GetNewSessionAsync(conversation.Id);
+AgentSession session = await jokerAgent.CreateSessionAsync(conversation.Id);
 
 Console.WriteLine(await jokerAgent.RunAsync("Tell me a joke about a pirate.", session));
 Console.WriteLine(await jokerAgent.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 jokerAgent.GetNewSessionAsync(conversation.Id);
+session = await jokerAgent.CreateSessionAsync(conversation.Id);
 await foreach (AgentResponseUpdate update in jokerAgent.RunStreamingAsync("Tell me a joke about a pirate.", session))
 {
     Console.WriteLine(update);

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/README.md

@@ -54,6 +54,6 @@ The sample will:
 
 When working with multi-turn conversations, there are two approaches:
 
-- **With Conversation ID**: By passing a `conversation.Id` to `GetNewSessionAsync()`, the conversation will be visible in the Azure Foundry Project UI. This is useful for tracking and debugging conversations.
+- **With Conversation ID**: By passing a `conversation.Id` to `CreateSessionAsync()`, the conversation will be visible in the Azure Foundry Project UI. This is useful for tracking and debugging conversations.
 - **Without Conversation ID**: Sessions created without a conversation ID still work correctly, maintaining context via `PreviousResponseId`. However, these conversations may not appear in the Foundry UI.
 

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/Program.cs

@@ -37,11 +37,11 @@ var newAgent = await aiProjectClient.CreateAIAgentAsync(name: AssistantName, mod
 var existingAgent = await aiProjectClient.GetAIAgentAsync(name: AssistantName, tools: [tool]);
 
 // Non-streaming agent interaction with function tools.
-AgentSession session = await existingAgent.GetNewSessionAsync();
+AgentSession session = await existingAgent.CreateSessionAsync();
 Console.WriteLine(await existingAgent.RunAsync("What is the weather like in Amsterdam?", session));
 
 // Streaming agent interaction with function tools.
-session = await existingAgent.GetNewSessionAsync();
+session = await existingAgent.CreateSessionAsync();
 await foreach (AgentResponseUpdate update in existingAgent.RunStreamingAsync("What is the weather like in Amsterdam?", session))
 {
     Console.WriteLine(update);

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/Program.cs

@@ -32,30 +32,28 @@ AIAgent agent = await aiProjectClient.CreateAIAgentAsync(name: AssistantName, mo
 
 // Call the agent with approval-required function tools.
 // The agent will request approval before invoking the function.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 AgentResponse response = await agent.RunAsync("What is the weather like in Amsterdam?", session);
 
-// Check if there are any user input requests (approvals needed).
-List<UserInputRequestContent> userInputRequests = response.UserInputRequests.ToList();
+// Check if there are any approval requests.
+// 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.
-    List<ChatMessage> userInputMessages = userInputRequests
-        .OfType<FunctionApprovalRequestContent>()
-        .Select(functionApprovalRequest =>
+    List<ChatMessage> userInputMessages = approvalRequests
+        .ConvertAll(functionApprovalRequest =>
         {
             Console.WriteLine($"The agent would like to invoke the following function, please reply Y to approve: Name {functionApprovalRequest.FunctionCall.Name}");
             bool approved = Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) ?? false;
             return new ChatMessage(ChatRole.User, [functionApprovalRequest.CreateResponse(approved)]);
-        })
-        .ToList();
+        });
 
     // Pass the user input responses back to the agent for further processing.
     response = await agent.RunAsync(userInputMessages, session);
 
-    userInputRequests = response.UserInputRequests.ToList();
+    approvalRequests = response.Messages.SelectMany(m => m.Contents).OfType<FunctionApprovalRequestContent>().ToList();
 }
 
 Console.WriteLine($"\nAgent: {response}");

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step06_PersistedConversations/Program.cs

@@ -19,13 +19,13 @@ AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential(
 AIAgent agent = await aiProjectClient.CreateAIAgentAsync(name: JokerName, model: deploymentName, instructions: JokerInstructions);
 
 // 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 = agent.SerializeSession(session);
 
 // Save the serialized session to a temporary file (for demonstration purposes).
 string tempFilePath = Path.GetTempFileName();

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step07_Observability/Program.cs

@@ -38,11 +38,11 @@ AIAgent agent = (await aiProjectClient.CreateAIAgentAsync(name: JokerName, model
     .Build();
 
 // Invoke the agent and output the text result.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
 
 // Invoke the agent with streaming support.
-session = await agent.GetNewSessionAsync();
+session = await agent.CreateSessionAsync();
 await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("Tell me a joke about a pirate.", session))
 {
     Console.WriteLine(update);

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step08_DependencyInjection/Program.cs

@@ -54,7 +54,7 @@ internal sealed class SampleService(AIProjectClient client, AIAgent agent, IHost
     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/FoundryAgents/FoundryAgents_Step10_UsingImages/Program.cs

@@ -24,7 +24,7 @@ ChatMessage message = new(ChatRole.User, [
     new DataContent(File.ReadAllBytes("assets/walkway.jpg"), "image/jpeg")
 ]);
 
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 
 await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(message, session))
 {

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step11_AsFunctionTool/Program.cs

@@ -39,7 +39,7 @@ AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
     tools: [weatherAgent.AsAIFunction()]);
 
 // Invoke the agent and output the text result.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", session));
 
 // Cleanup by agent name removes the agent versions created.

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step12_Middleware/Program.cs

@@ -49,7 +49,7 @@ AIAgent middlewareEnabledAgent = originalAgent
     .Use(GuardrailMiddleware, null)
     .Build();
 
-AgentSession session = await middlewareEnabledAgent.GetNewSessionAsync();
+AgentSession session = await middlewareEnabledAgent.CreateSessionAsync();
 
 Console.WriteLine("\n\n=== Example 1: Wording Guardrail ===");
 AgentResponse guardRailedResponse = await middlewareEnabledAgent.RunAsync("Tell me something harmful.");
@@ -193,27 +193,24 @@ async Task<AgentResponse> ConsolePromptingApprovalMiddleware(IEnumerable<ChatMes
 {
     AgentResponse response = await innerAgent.RunAsync(messages, session, options, cancellationToken);
 
-    List<UserInputRequestContent> 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}");
                 bool approved = Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) ?? false;
                 return new ChatMessage(ChatRole.User, [functionApprovalRequest.CreateResponse(approved)]);
-            })
-            .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/FoundryAgents/FoundryAgents_Step13_Plugins/Program.cs

@@ -42,7 +42,7 @@ AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
     services: serviceProvider);
 
 // Invoke the agent and output the text result.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("Tell me current time and weather in Seattle.", session));
 
 // Cleanup by agent name removes the agent version created.

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/Program.cs

@@ -83,7 +83,7 @@ internal sealed class Program
             AllowBackgroundResponses = true,
         };
 
-        AgentSession session = await agent.GetNewSessionAsync();
+        AgentSession session = await agent.CreateSessionAsync();
 
         ChatMessage message = new(ChatRole.User, [
             new TextContent("I need you to help me search for 'OpenAI news'. Please type 'OpenAI news' and submit the search. Once you see search results, the task is complete."),

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step27_LocalMCP/FoundryAgents_Step27_LocalMCP.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);CA1812</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="ModelContextProtocol" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step27_LocalMCP/Program.cs

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use a local MCP (Model Context Protocol) client with Azure Foundry Agents.
+// The MCP tools are resolved locally by connecting directly to the MCP server via HTTP,
+// and then passed to the Foundry agent as client-side tools.
+// This sample uses the Microsoft Learn MCP endpoint to search documentation.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using ModelContextProtocol.Client;
+
+string endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+const string AgentInstructions = "You are a helpful assistant that can help with Microsoft documentation questions. Use the Microsoft Learn MCP tool to search for documentation.";
+const string AgentName = "DocsAgent";
+
+// Connect to the MCP server locally via HTTP (Streamable HTTP transport).
+// The MCP server is hosted at Microsoft Learn and provides documentation search capabilities.
+Console.WriteLine("Connecting to MCP server at https://learn.microsoft.com/api/mcp ...");
+
+await using McpClient mcpClient = await McpClient.CreateAsync(new HttpClientTransport(new()
+{
+    Endpoint = new Uri("https://learn.microsoft.com/api/mcp"),
+    Name = "Microsoft Learn MCP",
+}));
+
+// Retrieve the list of tools available on the MCP server (resolved locally).
+IList<McpClientTool> mcpTools = await mcpClient.ListToolsAsync();
+Console.WriteLine($"MCP tools available: {string.Join(", ", mcpTools.Select(t => t.Name))}");
+
+// Wrap each MCP tool with a DelegatingAIFunction to log local invocations.
+List<AITool> wrappedTools = mcpTools.Select(tool => (AITool)new LoggingMcpTool(tool)).ToList();
+
+// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential());
+
+// Create the agent with the locally-resolved MCP tools.
+AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
+    model: deploymentName,
+    name: AgentName,
+    instructions: AgentInstructions,
+    tools: wrappedTools);
+
+Console.WriteLine($"Agent '{agent.Name}' created successfully.");
+
+try
+{
+    // First query
+    const string Prompt1 = "How does one create an Azure storage account using az cli?";
+    Console.WriteLine($"\nUser: {Prompt1}\n");
+    AgentResponse response1 = await agent.RunAsync(Prompt1);
+    Console.WriteLine($"Agent: {response1}");
+
+    Console.WriteLine("\n=======================================\n");
+
+    // Second query
+    const string Prompt2 = "What is Microsoft Agent Framework?";
+    Console.WriteLine($"User: {Prompt2}\n");
+    AgentResponse response2 = await agent.RunAsync(Prompt2);
+    Console.WriteLine($"Agent: {response2}");
+}
+finally
+{
+    // Cleanup by removing the agent when done
+    await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);
+    Console.WriteLine($"\nAgent '{agent.Name}' deleted.");
+}
+
+/// <summary>
+/// Wraps an MCP tool to log when it is invoked locally,
+/// confirming that the MCP call is happening client-side.
+/// </summary>
+internal sealed class LoggingMcpTool(AIFunction innerFunction) : DelegatingAIFunction(innerFunction)
+{
+    protected override ValueTask<object?> InvokeCoreAsync(AIFunctionArguments arguments, CancellationToken cancellationToken)
+    {
+        Console.WriteLine($"  >> [LOCAL MCP] Invoking tool '{this.Name}' locally...");
+        return base.InvokeCoreAsync(arguments, cancellationToken);
+    }
+}

dotnet/samples/GettingStarted/FoundryAgents/FoundryAgents_Step27_LocalMCP/README.md

@@ -0,0 +1,48 @@
+# Using Local MCP Client with Azure Foundry Agents
+
+This sample demonstrates how to use a local MCP (Model Context Protocol) client with Azure Foundry Agents. Unlike the hosted MCP approach where Azure Foundry invokes the MCP server on the service side, this sample connects to the MCP server directly from the client via HTTP (Streamable HTTP transport) and passes the resolved tools to the agent.
+
+## What this sample demonstrates
+
+- Connecting to an MCP server locally using `HttpClientTransport`
+- Discovering available tools from the MCP server client-side
+- Passing locally-resolved MCP tools to a Foundry agent
+- Using the Microsoft Learn MCP endpoint for documentation search
+- Managing agent lifecycle (creation and deletion)
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10 SDK or later
+- Azure Foundry service endpoint and deployment configured
+- Azure CLI installed and authenticated (for Azure credential authentication)
+
+**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
+
+Set the following environment variables:
+
+```powershell
+$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
+$env:AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+```
+
+## Run the sample
+
+Navigate to the FoundryAgents sample directory and run:
+
+```powershell
+cd dotnet/samples/GettingStarted/FoundryAgents
+dotnet run --project .\FoundryAgents_Step27_LocalMCP
+```
+
+## Expected behavior
+
+The sample will:
+
+1. Connect to the Microsoft Learn MCP server via HTTP and list available tools
+2. Create an agent with the locally-resolved MCP tools
+3. Ask two questions about Microsoft documentation
+4. The agent will use the MCP tools (invoked locally) to search Microsoft Learn documentation
+5. Display the agent's responses with information from the documentation
+6. Clean up resources by deleting the agent

dotnet/samples/GettingStarted/FoundryAgents/README.md

@@ -58,6 +58,7 @@ Before you begin, ensure you have the following prerequisites:
 |[Using plugins](./FoundryAgents_Step13_Plugins/)|This sample demonstrates how to use plugins with a Foundry agent|
 |[Code interpreter](./FoundryAgents_Step14_CodeInterpreter/)|This sample demonstrates how to use the code interpreter tool with a Foundry agent|
 |[Computer use](./FoundryAgents_Step15_ComputerUse/)|This sample demonstrates how to use computer use capabilities with a Foundry agent|
+|[Local MCP](./FoundryAgents_Step27_LocalMCP/)|This sample demonstrates how to use a local MCP client with a Foundry agent|
 
 ## Running the samples from the console
 

dotnet/samples/GettingStarted/ModelContextProtocol/FoundryAgent_Hosted_MCP/Program.cs

@@ -42,7 +42,7 @@ AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
     });
 
 // You can then invoke the agent like any other AIAgent.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", session));
 
 // Cleanup for sample purposes.
@@ -75,17 +75,16 @@ AIAgent agentWithRequiredApproval = await persistentAgentsClient.CreateAIAgentAs
     });
 
 // You can then invoke the agent like any other AIAgent.
-var sessionWithRequiredApproval = await agentWithRequiredApproval.GetNewSessionAsync();
-var response = await agentWithRequiredApproval.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", sessionWithRequiredApproval);
-var userInputRequests = response.UserInputRequests.ToList();
+// For simplicity, we are assuming here that only mcp tool approvals are pending.
+AgentSession sessionWithRequiredApproval = await agentWithRequiredApproval.CreateSessionAsync();
+AgentResponse response = await agentWithRequiredApproval.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", sessionWithRequiredApproval);
+List<McpServerToolApprovalRequestContent> approvalRequests = response.Messages.SelectMany(m => m.Contents).OfType<McpServerToolApprovalRequestContent>().ToList();
 
-while (userInputRequests.Count > 0)
+while (approvalRequests.Count > 0)
 {
     // Ask the user to approve each MCP call request.
-    // For simplicity, we are assuming here that only MCP approval requests are being made.
-    var userInputResponses = userInputRequests
-        .OfType<McpServerToolApprovalRequestContent>()
-        .Select(approvalRequest =>
+    List<ChatMessage> userInputResponses = approvalRequests
+        .ConvertAll(approvalRequest =>
         {
             Console.WriteLine($"""
                 The agent would like to invoke the following MCP Tool, please reply Y to approve.
@@ -94,13 +93,12 @@ while (userInputRequests.Count > 0)
                 Arguments: {string.Join(", ", approvalRequest.ToolCall.Arguments?.Select(x => $"{x.Key}: {x.Value}") ?? [])}
                 """);
             return new ChatMessage(ChatRole.User, [approvalRequest.CreateResponse(Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) ?? false)]);
-        })
-        .ToList();
+        });
 
     // Pass the user input responses back to the agent for further processing.
     response = await agentWithRequiredApproval.RunAsync(userInputResponses, sessionWithRequiredApproval);
 
-    userInputRequests = response.UserInputRequests.ToList();
+    approvalRequests = response.Messages.SelectMany(m => m.Contents).OfType<McpServerToolApprovalRequestContent>().ToList();
 }
 
 Console.WriteLine($"\nAgent: {response}");

dotnet/samples/GettingStarted/ModelContextProtocol/ResponseAgent_Hosted_MCP/Program.cs

@@ -37,7 +37,7 @@ AIAgent agent = new AzureOpenAIClient(
         tools: [mcpTool]);
 
 // You can then invoke the agent like any other AIAgent.
-AgentSession session = await agent.GetNewSessionAsync();
+AgentSession session = await agent.CreateSessionAsync();
 Console.WriteLine(await agent.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", session));
 
 // **** MCP Tool with Approval Required ****
@@ -64,17 +64,16 @@ AIAgent agentWithRequiredApproval = new AzureOpenAIClient(
         tools: [mcpToolWithApproval]);
 
 // You can then invoke the agent like any other AIAgent.
-var sessionWithRequiredApproval = await agentWithRequiredApproval.GetNewSessionAsync();
-var response = await agentWithRequiredApproval.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", sessionWithRequiredApproval);
-var userInputRequests = response.UserInputRequests.ToList();
+// For simplicity, we are assuming here that only mcp tool approvals are pending.
+AgentSession sessionWithRequiredApproval = await agentWithRequiredApproval.CreateSessionAsync();
+AgentResponse response = await agentWithRequiredApproval.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", sessionWithRequiredApproval);
+List<McpServerToolApprovalRequestContent> approvalRequests = response.Messages.SelectMany(m => m.Contents).OfType<McpServerToolApprovalRequestContent>().ToList();
 
-while (userInputRequests.Count > 0)
+while (approvalRequests.Count > 0)
 {
     // Ask the user to approve each MCP call request.
-    // For simplicity, we are assuming here that only MCP approval requests are being made.
-    var userInputResponses = userInputRequests
-        .OfType<McpServerToolApprovalRequestContent>()
-        .Select(approvalRequest =>
+    List<ChatMessage> userInputResponses = approvalRequests
+        .ConvertAll(approvalRequest =>
         {
             Console.WriteLine($"""
                 The agent would like to invoke the following MCP Tool, please reply Y to approve.
@@ -83,13 +82,12 @@ while (userInputRequests.Count > 0)
                 Arguments: {string.Join(", ", approvalRequest.ToolCall.Arguments?.Select(x => $"{x.Key}: {x.Value}") ?? [])}
                 """);
             return new ChatMessage(ChatRole.User, [approvalRequest.CreateResponse(Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) ?? false)]);
-        })
-        .ToList();
+        });
 
     // Pass the user input responses back to the agent for further processing.
     response = await agentWithRequiredApproval.RunAsync(userInputResponses, sessionWithRequiredApproval);
 
-    userInputRequests = response.UserInputRequests.ToList();
+    approvalRequests = response.Messages.SelectMany(m => m.Contents).OfType<McpServerToolApprovalRequestContent>().ToList();
 }
 
 Console.WriteLine($"\nAgent: {response}");

dotnet/samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/Program.cs

@@ -136,7 +136,7 @@ internal sealed class SloganWriterExecutor : Executor
 
     public async ValueTask<SloganResult> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
-        this._session ??= await this._agent.GetNewSessionAsync(cancellationToken);
+        this._session ??= await this._agent.CreateSessionAsync(cancellationToken);
 
         var result = await this._agent.RunAsync(message, this._session, cancellationToken: cancellationToken);
 
@@ -209,7 +209,7 @@ internal sealed class FeedbackExecutor : Executor<SloganResult>
 
     public override async ValueTask HandleAsync(SloganResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
-        this._session ??= await this._agent.GetNewSessionAsync(cancellationToken);
+        this._session ??= await this._agent.CreateSessionAsync(cancellationToken);
 
         var sloganMessage = $"""
             Here is a slogan for the task '{message.Task}':

dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/Program.cs

@@ -37,7 +37,7 @@ public static class Program
         // Create the workflow and turn it into an agent
         var workflow = WorkflowFactory.BuildWorkflow(chatClient);
         var agent = workflow.AsAgent("workflow-agent", "Workflow Agent");
-        var session = await agent.GetNewSessionAsync();
+        var session = await agent.CreateSessionAsync();
 
         // Start an interactive loop to interact with the workflow as if it were an agent
         while (true)

dotnet/samples/GettingStarted/Workflows/Concurrent/Concurrent/Program.cs

@@ -72,8 +72,8 @@ public static class Program
 /// <summary>
 /// Executor that starts the concurrent processing by sending messages to the agents.
 /// </summary>
-internal sealed class ConcurrentStartExecutor() :
-    Executor<string>("ConcurrentStartExecutor")
+internal sealed partial class ConcurrentStartExecutor() :
+    Executor("ConcurrentStartExecutor")
 {
     /// <summary>
     /// Starts the concurrent processing by sending messages to the agents.
@@ -83,7 +83,8 @@ internal sealed class ConcurrentStartExecutor() :
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
     /// The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>A task representing the asynchronous operation</returns>
-    public override async ValueTask HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    [MessageHandler]
+    public async ValueTask HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
         // Broadcast the message to all connected agents. Receiving agents will queue
         // the message but will not start processing until they receive a turn token.

dotnet/samples/GettingStarted/Workflows/Declarative/HostedWorkflow/Program.cs

@@ -47,7 +47,7 @@ internal sealed class Program
 
         AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);
 
-        AgentSession session = await agent.GetNewSessionAsync();
+        AgentSession session = await agent.CreateSessionAsync();
 
         ProjectConversation conversation =
             await aiProjectClient

dotnet/samples/GettingStarted/Workflows/Directory.Build.props

@@ -0,0 +1,13 @@
+<Project>
+
+  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
+
+  <!-- Include Workflows source generator for samples using [MessageHandler] attribute -->
+  <ItemGroup>
+    <ProjectReference Include="$(RepoRoot)/dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj"
+                      OutputItemType="Analyzer"
+                      ReferenceOutputAssembly="false"
+                      GlobalPropertiesToRemove="TargetFramework" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/Workflows/Observability/ApplicationInsights/Program.cs

@@ -35,8 +35,10 @@ public static class Program
 
         using var traceProvider = Sdk.CreateTracerProviderBuilder()
             .SetResourceBuilder(resourceBuilder)
-            .AddSource("Microsoft.Agents.AI.Workflows*")
             .AddSource(SourceName)
+            // The following source is only required if not specifying
+            // the `activitySource` in the WithOpenTelemetry call below
+            .AddSource("Microsoft.Agents.AI.Workflows*")
             .AddAzureMonitorTraceExporter(options => options.ConnectionString = applicationInsightsConnectionString)
             .Build();
 
@@ -51,6 +53,10 @@ public static class Program
         // Build the workflow by connecting executors sequentially
         var workflow = new WorkflowBuilder(uppercase)
             .AddEdge(uppercase, reverse)
+            .WithOpenTelemetry(
+                // Set `EnableSensitiveData` to true to include message content in traces
+                configure: cfg => cfg.EnableSensitiveData = true,
+                activitySource: s_activitySource)
             .Build();
 
         // Execute the workflow with input data

dotnet/samples/GettingStarted/Workflows/Observability/AspireDashboard/Program.cs

@@ -37,8 +37,10 @@ public static class Program
 
         using var traceProvider = Sdk.CreateTracerProviderBuilder()
             .SetResourceBuilder(resourceBuilder)
-            .AddSource("Microsoft.Agents.AI.Workflows*")
             .AddSource(SourceName)
+            // The following source is only required if not specifying
+            // the `activitySource` in the WithOpenTelemetry call below
+            .AddSource("Microsoft.Agents.AI.Workflows*")
             .AddOtlpExporter(options => options.Endpoint = new Uri(otlpEndpoint))
             .Build();
 
@@ -53,6 +55,10 @@ public static class Program
         // Build the workflow by connecting executors sequentially
         var workflow = new WorkflowBuilder(uppercase)
             .AddEdge(uppercase, reverse)
+            .WithOpenTelemetry(
+                // Set `EnableSensitiveData` to true to include message content in traces
+                configure: cfg => cfg.EnableSensitiveData = true,
+                activitySource: s_activitySource)
             .Build();
 
         // Execute the workflow with input data

dotnet/samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/Program.cs

@@ -90,7 +90,7 @@ public static class Program
         {
             EnableSensitiveData = true  // enable sensitive data at the agent level such as prompts and responses
         };
-        var session = await agent.GetNewSessionAsync();
+        var session = await agent.CreateSessionAsync();
 
         // Start an interactive loop to interact with the workflow as if it were an agent
         while (true)

dotnet/samples/M365Agent/AFAgentApplication.cs

@@ -44,7 +44,7 @@ internal sealed class AFAgentApplication : AgentApplication
         // Deserialize the conversation history into an AgentSession, or create a new one if none exists.
         AgentSession agentSession = sessionElementStart.ValueKind is not JsonValueKind.Undefined and not JsonValueKind.Null
             ? await this._agent.DeserializeSessionAsync(sessionElementStart, JsonUtilities.DefaultOptions, cancellationToken)
-            : await this._agent.GetNewSessionAsync(cancellationToken);
+            : await this._agent.CreateSessionAsync(cancellationToken);
 
         ChatMessage chatMessage = HandleUserInput(turnContext);
 
@@ -80,7 +80,7 @@ internal sealed class AFAgentApplication : AgentApplication
         }
 
         // Serialize and save the updated conversation history back to turn state.
-        JsonElement sessionElementEnd = agentSession.Serialize(JsonUtilities.DefaultOptions);
+        JsonElement sessionElementEnd = this._agent.SerializeSession(agentSession, JsonUtilities.DefaultOptions);
         turnState.SetValue("conversation.chatHistory", sessionElementEnd);
 
         // End the streaming response
@@ -131,58 +131,54 @@ internal sealed class AFAgentApplication : AgentApplication
     }
 
     /// <summary>
-    /// When the agent returns any user input requests, this method converts them into adaptive cards that
+    /// When the agent returns any function approval requests, this method converts them into adaptive cards that
     /// asks the user to approve or deny the requests.
     /// </summary>
-    /// <param name="response">The <see cref="AgentResponse"/> that may contain the user input requests.</param>
+    /// <param name="response">The <see cref="AgentResponse"/> that may contain the function approval requests.</param>
     /// <param name="attachments">The list of <see cref="Attachment"/> to which the adaptive cards will be added.</param>
     private static void HandleUserInputRequests(AgentResponse response, ref List<Attachment>? attachments)
     {
-        var userInputRequests = response.UserInputRequests.ToList();
-        if (userInputRequests.Count > 0)
+        foreach (FunctionApprovalRequestContent functionApprovalRequest in response.Messages.SelectMany(m => m.Contents).OfType<FunctionApprovalRequestContent>())
         {
-            foreach (var functionApprovalRequest in userInputRequests.OfType<FunctionApprovalRequestContent>())
+            var functionApprovalRequestJson = JsonSerializer.Serialize(functionApprovalRequest, JsonUtilities.DefaultOptions);
+
+            var card = new AdaptiveCard("1.5");
+            card.Body.Add(new AdaptiveTextBlock
             {
-                var functionApprovalRequestJson = JsonSerializer.Serialize(functionApprovalRequest, JsonUtilities.DefaultOptions);
+                Text = "Function Call Approval Required",
+                Size = AdaptiveTextSize.Large,
+                Weight = AdaptiveTextWeight.Bolder,
+                HorizontalAlignment = AdaptiveHorizontalAlignment.Center
+            });
+            card.Body.Add(new AdaptiveTextBlock
+            {
+                Text = $"Function: {functionApprovalRequest.FunctionCall.Name}"
+            });
+            card.Body.Add(new AdaptiveActionSet()
+            {
+                Actions =
+                [
+                    new AdaptiveSubmitAction
+                    {
+                        Id = "Approve",
+                        Title = "Approve",
+                        Data = new { type = "functionApproval", approved = true, requestJson = functionApprovalRequestJson }
+                    },
+                    new AdaptiveSubmitAction
+                    {
+                        Id = "Deny",
+                        Title = "Deny",
+                        Data = new { type = "functionApproval", approved = false, requestJson = functionApprovalRequestJson }
+                    }
+                ]
+            });
 
-                var card = new AdaptiveCard("1.5");
-                card.Body.Add(new AdaptiveTextBlock
-                {
-                    Text = "Function Call Approval Required",
-                    Size = AdaptiveTextSize.Large,
-                    Weight = AdaptiveTextWeight.Bolder,
-                    HorizontalAlignment = AdaptiveHorizontalAlignment.Center
-                });
-                card.Body.Add(new AdaptiveTextBlock
-                {
-                    Text = $"Function: {functionApprovalRequest.FunctionCall.Name}"
-                });
-                card.Body.Add(new AdaptiveActionSet()
-                {
-                    Actions =
-                    [
-                        new AdaptiveSubmitAction
-                        {
-                            Id = "Approve",
-                            Title = "Approve",
-                            Data = new { type = "functionApproval", approved = true, requestJson = functionApprovalRequestJson }
-                        },
-                        new AdaptiveSubmitAction
-                        {
-                            Id = "Deny",
-                            Title = "Deny",
-                            Data = new { type = "functionApproval", approved = false, requestJson = functionApprovalRequestJson }
-                        }
-                    ]
-                });
-
-                attachments ??= [];
-                attachments.Add(new Attachment()
-                {
-                    ContentType = "application/vnd.microsoft.card.adaptive",
-                    Content = card.ToJson(),
-                });
-            }
+            attachments ??= [];
+            attachments.Add(new Attachment()
+            {
+                ContentType = "application/vnd.microsoft.card.adaptive",
+                Content = card.ToJson(),
+            });
         }
     }
 }

dotnet/src/Microsoft.Agents.AI.A2A/A2AAgent.cs

@@ -54,7 +54,7 @@ public sealed class A2AAgent : AIAgent
     }
 
     /// <inheritdoc/>
-    public sealed override ValueTask<AgentSession> GetNewSessionAsync(CancellationToken cancellationToken = default)
+    protected sealed override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
         => new(new A2AAgentSession());
 
     /// <summary>
@@ -62,12 +62,25 @@ public sealed class A2AAgent : AIAgent
     /// </summary>
     /// <param name="contextId">The context id to continue.</param>
     /// <returns>A value task representing the asynchronous operation. The task result contains a new <see cref="AgentSession"/> instance.</returns>
-    public ValueTask<AgentSession> GetNewSessionAsync(string contextId)
+    public ValueTask<AgentSession> CreateSessionAsync(string contextId)
         => new(new A2AAgentSession() { ContextId = contextId });
 
     /// <inheritdoc/>
-    public override ValueTask<AgentSession> DeserializeSessionAsync(JsonElement serializedSession, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
-        => new(new A2AAgentSession(serializedSession, jsonSerializerOptions));
+    protected override JsonElement SerializeSessionCore(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null)
+    {
+        _ = Throw.IfNull(session);
+
+        if (session is not A2AAgentSession typedSession)
+        {
+            throw new InvalidOperationException("The provided session is not compatible with the agent. Only sessions created by the agent can be serialized.");
+        }
+
+        return typedSession.Serialize(jsonSerializerOptions);
+    }
+
+    /// <inheritdoc/>
+    protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+        => new(new A2AAgentSession(serializedState, jsonSerializerOptions));
 
     /// <inheritdoc/>
     protected override async Task<AgentResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
@@ -230,7 +243,7 @@ public sealed class A2AAgent : AIAgent
             throw new InvalidOperationException("A session must be provided when AllowBackgroundResponses is enabled.");
         }
 
-        session ??= await this.GetNewSessionAsync(cancellationToken).ConfigureAwait(false);
+        session ??= await this.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
 
         if (session is not A2AAgentSession typedSession)
         {

dotnet/src/Microsoft.Agents.AI.A2A/A2AAgentSession.cs

@@ -46,7 +46,7 @@ public sealed class A2AAgentSession : AgentSession
     public string? TaskId { get; internal set; }
 
     /// <inheritdoc/>
-    public override JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
+    internal JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
     {
         var state = new A2AAgentSessionState
         {