chore: import upstream snapshot with attribution

dotnet/samples/01-get-started/01_hello_agent/01_hello_agent.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/01-get-started/01_hello_agent/Program.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create and use a simple AI agent with AIProjectClient as the backend.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, instructions: "You are good at telling jokes.", name: "Joker");
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
+
+// Invoke the agent with streaming support.
+await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate."))
+{
+    Console.WriteLine(update);
+}

dotnet/samples/01-get-started/02_add_tools/02_add_tools.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/01-get-started/02_add_tools/Program.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use an AIProjectClient agent with function tools.
+// It shows both non-streaming and streaming agent interactions using weather tools.
+
+using System.ComponentModel;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+[Description("Get the weather for a given location.")]
+static string GetWeather([Description("The location to get the weather for.")] string location)
+    => $"The weather in {location} is cloudy with a high of 15°C.";
+
+// Create the agent and provide the function tool to the agent.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetWeather)]);
+
+// Non-streaming agent interaction with function tools.
+Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));
+
+// Streaming agent interaction with function tools.
+await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
+{
+    Console.WriteLine(update);
+}

dotnet/samples/01-get-started/03_multi_turn/03_multi_turn.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/01-get-started/03_multi_turn/Program.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create and use a simple AI agent with a multi-turn conversation.
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, 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.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.CreateSessionAsync();
+await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate.", session))
+{
+    Console.WriteLine(update);
+}
+await foreach (var update in agent.RunStreamingAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", session))
+{
+    Console.WriteLine(update);
+}

dotnet/samples/01-get-started/04_memory/04_memory.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/01-get-started/04_memory/Program.cs

@@ -0,0 +1,182 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to add a basic custom memory component to an agent.
+// The memory component subscribes to all messages added to the conversation and
+// extracts the user's name and age if provided.
+// The component adds a prompt to ask for this information if it is not already known
+// and provides it to the model before each invocation if known.
+
+using System.Text;
+using System.Text.Json;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using SampleApp;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
+
+// Create a separate IChatClient for the memory component to use for structured extraction.
+// The memory component calls the model with a ResponseFormat (JSON schema) to extract user info.
+// Using a dedicated client here avoids mixing side-channel extraction calls with the agent's
+// conversation history, and avoids the chicken-and-egg problem of needing an IChatClient
+// before the main agent is constructed.
+IChatClient extractionClient =
+    new AIProjectClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetProjectOpenAIClient()
+    .GetResponsesClient()
+    .AsIChatClient(model);
+
+// Create the agent with instructions and the custom memory context provider.
+// The memory component is attached to all sessions created by the agent. Here each new memory
+// component will have its own user info object, so each session will have its own memory.
+// In real world applications/services, where the user info would be persisted in a database,
+// and preferably shared between multiple sessions used by the same user, ensure that the
+// factory reads the user id from the current context and scopes the memory component
+// and its storage to that user id.
+AIAgent agent = projectClient.AsAIAgent(new ChatClientAgentOptions
+{
+    ChatOptions = new ChatOptions
+    {
+        ModelId = model,
+        Instructions = "You are a friendly assistant. Always address the user by their name.",
+    },
+    AIContextProviders = [new UserInfoMemory(extractionClient)]
+});
+
+// Create a new session for the conversation.
+AgentSession session = await agent.CreateSessionAsync();
+
+Console.WriteLine(">> Use session with blank memory\n");
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent.RunAsync("Hello, what is the square root of 9?", session));
+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.
+JsonElement sessionElement = await agent.SerializeSessionAsync(session);
+
+Console.WriteLine("\n>> Use deserialized session with previously created memories\n");
+
+// Later we can deserialize the session and continue the conversation with the previous memory component state.
+var deserializedSession = await agent.DeserializeSessionAsync(sessionElement);
+Console.WriteLine(await agent.RunAsync("What is my name and age?", deserializedSession));
+
+Console.WriteLine("\n>> Read memories using memory component\n");
+
+// It's possible to access the memory component via the agent's GetService method.
+var userInfo = agent.GetService<UserInfoMemory>()?.GetUserInfo(deserializedSession);
+
+// Output the user info that was captured by the memory component.
+Console.WriteLine($"MEMORY - User Name: {userInfo?.UserName}");
+Console.WriteLine($"MEMORY - User Age: {userInfo?.UserAge}");
+
+Console.WriteLine("\n>> Use new session with previously created memories\n");
+
+// It is also possible to set the memories using a memory component on an individual session.
+// This is useful if we want to start a new session, but have it share the same memories as a previous session.
+var newSession = await agent.CreateSessionAsync();
+if (userInfo is not null && agent.GetService<UserInfoMemory>() is UserInfoMemory newSessionMemory)
+{
+    newSessionMemory.SetUserInfo(newSession, userInfo);
+}
+
+// Invoke the agent and output the text result.
+// This time the agent should remember the user's name and use it in the response.
+Console.WriteLine(await agent.RunAsync("What is my name and age?", newSession));
+
+namespace SampleApp
+{
+    /// <summary>
+    /// Sample memory component that can remember a user's name and age.
+    /// </summary>
+    internal sealed class UserInfoMemory : AIContextProvider
+    {
+        private readonly ProviderSessionState<UserInfo> _sessionState;
+        private IReadOnlyList<string>? _stateKeys;
+        private readonly IChatClient _chatClient;
+
+        public UserInfoMemory(IChatClient chatClient, Func<AgentSession?, UserInfo>? stateInitializer = null)
+        {
+            this._sessionState = new ProviderSessionState<UserInfo>(
+                stateInitializer ?? (_ => new UserInfo()),
+                this.GetType().Name);
+            this._chatClient = chatClient;
+        }
+
+        public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
+
+        public UserInfo GetUserInfo(AgentSession session)
+            => this._sessionState.GetOrInitializeState(session);
+
+        public void SetUserInfo(AgentSession session, UserInfo userInfo)
+            => this._sessionState.SaveState(session, userInfo);
+
+        protected override async ValueTask StoreAIContextAsync(InvokedContext context, CancellationToken cancellationToken = default)
+        {
+            var userInfo = this._sessionState.GetOrInitializeState(context.Session);
+
+            // 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 ((userInfo.UserName is null || userInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
+            {
+                // The Foundry Responses API requires the model name in the request body.
+                // Retrieve it from the client's metadata so callers don't need to pass it separately.
+                var modelId = this._chatClient.GetService<ChatClientMetadata>()?.DefaultModelId
+                    ?? throw new InvalidOperationException(
+                        "Could not retrieve DefaultModelId from the extraction IChatClient. " +
+                        "Ensure the client was created with a model ID (e.g., via projectClient.AsAIAgent(...)).");
+                var result = await this._chatClient.GetResponseAsync<UserInfo>(
+                    context.RequestMessages,
+                    new ChatOptions()
+                    {
+                        ModelId = modelId,
+                        Instructions = "Extract the user's name and age from the message if present. If not present return nulls."
+                    },
+                    cancellationToken: cancellationToken);
+
+                userInfo.UserName ??= result.Result.UserName;
+                userInfo.UserAge ??= result.Result.UserAge;
+            }
+
+            this._sessionState.SaveState(context.Session, userInfo);
+        }
+
+        protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+        {
+            var userInfo = this._sessionState.GetOrInitializeState(context.Session);
+
+            StringBuilder instructions = new();
+
+            // If we don't already know the user's name and age, add instructions to ask for them, otherwise just provide what we have to the context.
+            instructions
+                .AppendLine(
+                    userInfo.UserName is null ?
+                        "Ask the user for their name and politely decline to answer any questions until they provide it." :
+                        $"The user's name is {userInfo.UserName}.")
+                .AppendLine(
+                    userInfo.UserAge is null ?
+                        "Ask the user for their age and politely decline to answer any questions until they provide it." :
+                        $"The user's age is {userInfo.UserAge}.");
+
+            return new ValueTask<AIContext>(new AIContext
+            {
+                Instructions = instructions.ToString()
+            });
+        }
+    }
+
+    internal sealed class UserInfo
+    {
+        public string? UserName { get; set; }
+        public int? UserAge { get; set; }
+    }
+}

dotnet/samples/01-get-started/05_first_workflow/05_first_workflow.csproj

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

dotnet/samples/01-get-started/05_first_workflow/Program.cs

@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowExecutorsAndEdgesSample;
+
+/// <summary>
+/// This sample introduces the concepts of executors and edges in a workflow.
+///
+/// Workflows are built from executors (processing units) connected by edges (data flow paths).
+/// In this example, we create a simple text processing pipeline that:
+/// 1. Takes input text and converts it to uppercase using an UppercaseExecutor
+/// 2. Takes the uppercase text and reverses it using a ReverseTextExecutor
+///
+/// The executors are connected sequentially, so data flows from one to the next in order.
+/// For input "Hello, World!", the workflow produces "!DLROW ,OLLEH".
+/// </summary>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Create the executors
+        Func<string, string> uppercaseFunc = s => s.ToUpperInvariant();
+        var uppercase = uppercaseFunc.BindAsExecutor("UppercaseExecutor");
+
+        ReverseTextExecutor reverse = new();
+
+        // Build the workflow by connecting executors sequentially
+        WorkflowBuilder builder = new(uppercase);
+        builder.AddEdge(uppercase, reverse).WithOutputFrom(reverse);
+        var workflow = builder.Build();
+
+        // Execute the workflow with input data
+        await using Run run = await InProcessExecution.RunAsync(workflow, "Hello, World!");
+        foreach (WorkflowEvent evt in run.NewEvents)
+        {
+            if (evt is ExecutorCompletedEvent executorComplete)
+            {
+                Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
+            }
+        }
+    }
+}
+
+/// <summary>
+/// Second executor: reverses the input text and completes the workflow.
+/// </summary>
+internal sealed class ReverseTextExecutor() : Executor<string, string>("ReverseTextExecutor")
+{
+    /// <summary>
+    /// Processes the input message by reversing the text.
+    /// </summary>
+    /// <param name="message">The input text to reverse</param>
+    /// <param name="context">Workflow context for accessing workflow services and adding events</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
+    /// The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The input text reversed</returns>
+    public override ValueTask<string> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Because we do not suppress it, the returned result will be yielded as an output from this executor.
+        return ValueTask.FromResult(string.Concat(message.Reverse()));
+    }
+}

dotnet/samples/01-get-started/06_host_your_agent/06_host_your_agent.csproj

@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- The Functions build tools don't like namespaces that start with a number -->
+    <AssemblyName>HostedAgent</AssemblyName>
+    <RootNamespace>HostedAgent</RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+  <!-- Azure Functions packages -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
+  </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Foundry\Microsoft.Agents.AI.Foundry.csproj" />
+  </ItemGroup>
+</Project>

dotnet/samples/01-get-started/06_host_your_agent/Program.cs

@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to host an AI agent with Azure Functions (DurableAgents).
+//
+// Prerequisites:
+//   - Azure Functions Core Tools
+//   - Foundry project endpoint and credentials
+//
+// Environment variables:
+//   FOUNDRY_PROJECT_ENDPOINT
+//   FOUNDRY_MODEL (defaults to "gpt-5.4-mini")
+//
+// Run with: func start
+// Then call: POST http://localhost:7071/api/agents/HostedAgent/run
+
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting.AzureFunctions;
+using Microsoft.Azure.Functions.Worker.Builder;
+using Microsoft.Extensions.Hosting;
+
+var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
+var model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+// Set up an AI agent following the standard Microsoft Agent Framework pattern.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: model, instructions: "You are a helpful assistant hosted in Azure Functions.", name: "HostedAgent");
+
+// Configure the function app to host the AI agent.
+// This will automatically generate HTTP API endpoints for the agent.
+using IHost app = FunctionsApplication
+    .CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableAgents(options => options.AddAIAgent(agent, timeToLive: TimeSpan.FromHours(1)))
+    .Build();
+app.Run();