chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="A2A" />
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,89 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to represent an A2A agent as a set of function tools, where each function tool
+// corresponds to a skill of the A2A agent, and register these function tools with another AI agent so
+// it can leverage the A2A agent's skills.
+
+using System.Text.RegularExpressions;
+using A2A;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+var a2aAgentHost = Environment.GetEnvironmentVariable("A2A_AGENT_HOST") ?? throw new InvalidOperationException("A2A_AGENT_HOST is not set.");
+
+// Initialize an A2ACardResolver to get an A2A agent card.
+A2ACardResolver agentCardResolver = new(new Uri(a2aAgentHost));
+
+// Get the agent card
+AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
+
+// Create an instance of the AIAgent for an existing A2A agent specified by the agent card.
+AIAgent a2aAgent = agentCard.AsAIAgent();
+
+// Create the main agent, and provide the a2a agent skills as a function tools.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsAIAgent(
+        instructions: "You are a helpful assistant that helps people with travel planning.",
+        tools: [.. CreateFunctionTools(a2aAgent, agentCard)]
+    );
+
+// Invoke the agent and output the text result.
+Console.WriteLine(await agent.RunAsync("Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls"));
+
+static IEnumerable<AIFunction> CreateFunctionTools(AIAgent a2aAgent, AgentCard agentCard)
+{
+    foreach (var skill in agentCard.Skills)
+    {
+        // A2A agent skills don't have schemas describing the expected shape of their inputs and outputs. 
+        // Schemas can be beneficial for AI models to better understand the skill's contract, generate 
+        // the skill's input accordingly and to know what to expect in the skill's output.
+        // However, the A2A specification defines properties such as name, description, tags, examples, 
+        // inputModes, and outputModes to provide context about the skill's purpose, capabilities, usage, 
+        // and supported MIME types. These properties are added to the function tool description to help 
+        // the model determine the appropriate shape of the skill's input and output.
+        AIFunctionFactoryOptions options = new()
+        {
+            Name = FunctionNameSanitizer.Sanitize(skill.Name),
+            Description = $$"""
+            {
+                "description": "{{skill.Description}}",
+                "tags": "[{{string.Join(", ", skill.Tags ?? [])}}]",
+                "examples": "[{{string.Join(", ", skill.Examples ?? [])}}]",
+                "inputModes": "[{{string.Join(", ", skill.InputModes ?? [])}}]",
+                "outputModes": "[{{string.Join(", ", skill.OutputModes ?? [])}}]"
+            }
+            """,
+        };
+
+        yield return AIFunctionFactory.Create(RunAgentAsync, options);
+    }
+
+    async Task<string> RunAgentAsync(string input, CancellationToken cancellationToken)
+    {
+        var response = await a2aAgent.RunAsync(input, cancellationToken: cancellationToken).ConfigureAwait(false);
+
+        return response.Text;
+    }
+}
+
+internal static partial class FunctionNameSanitizer
+{
+    public static string Sanitize(string name)
+    {
+        return InvalidNameCharsRegex().Replace(name, "_");
+    }
+
+    [GeneratedRegex("[^0-9A-Za-z]+")]
+    private static partial Regex InvalidNameCharsRegex();
+}
@@ -0,0 +1,22 @@
+# A2A Agent as Function Tools
+
+This sample demonstrates how to represent an A2A agent as a set of function tools, where each function tool corresponds to a skill of the A2A agent, 
+and register these function tools with another AI agent so it can leverage the A2A agent's skills.
+
+# Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10 SDK or later
+- Access to the A2A agent host service
+
+**Note**: These samples need to be run against a valid A2A server. If no A2A server is available, they can be run against the echo-agent that can be 
+spun up locally by following the guidelines at: https://github.com/a2aproject/a2a-dotnet/blob/main/samples/AgentServer/README.md
+
+Set the following environment variables:
+
+```powershell
+$env:A2A_AGENT_HOST="https://your-a2a-agent-host" # Replace with your A2A agent host endpoint
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
+```
@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="A2A" />
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to poll for long-running task completion using continuation tokens with an A2A AI agent.
+
+using A2A;
+using Microsoft.Agents.AI;
+
+var a2aAgentHost = Environment.GetEnvironmentVariable("A2A_AGENT_HOST") ?? throw new InvalidOperationException("A2A_AGENT_HOST is not set.");
+
+// Initialize an A2ACardResolver to get an A2A agent card.
+A2ACardResolver agentCardResolver = new(new Uri(a2aAgentHost));
+
+// Get the agent card
+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.CreateSessionAsync();
+
+// AllowBackgroundResponses must be true so the server returns immediately with a continuation token
+// instead of blocking until the task is complete.
+AgentRunOptions options = new() { AllowBackgroundResponses = true };
+
+// 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, options: options);
+
+// Poll until the response is complete.
+while (response.ContinuationToken is { } token)
+{
+    // Wait before polling again.
+    await Task.Delay(TimeSpan.FromSeconds(2));
+
+    // Continue with the token.
+    response = await agent.RunAsync(session, options: new AgentRunOptions { ContinuationToken = token });
+}
+
+// Display the result
+Console.WriteLine(response);
@@ -0,0 +1,25 @@
+# Polling for A2A Agent Task Completion
+
+This sample demonstrates how to poll for long-running task completion using continuation tokens with an A2A AI agent, following the background responses pattern.
+
+The sample:
+
+- Connects to an A2A agent server specified in the `A2A_AGENT_HOST` environment variable
+- Sends a request to the agent that may take time to complete
+- Polls the agent at regular intervals using continuation tokens until a final response is received
+- Displays the final result
+
+This pattern is useful when an AI model cannot complete a complex task in a single response and needs multiple rounds of processing.
+
+# Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10.0 SDK or later
+- An A2A agent server running and accessible via HTTP
+
+Set the following environment variable:
+
+```powershell
+$env:A2A_AGENT_HOST="http://localhost:5000"  # Replace with your A2A agent server host
+```
@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="A2A" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to select the A2A protocol binding (HTTP+JSON vs JSON-RPC) when
+// creating an AIAgent from an A2A agent card using A2AClientOptions.PreferredBindings.
+
+using A2A;
+using Microsoft.Agents.AI;
+
+var a2aAgentHost = Environment.GetEnvironmentVariable("A2A_AGENT_HOST") ?? throw new InvalidOperationException("A2A_AGENT_HOST is not set.");
+
+// Initialize an A2ACardResolver to get an A2A agent card.
+A2ACardResolver agentCardResolver = new(new Uri(a2aAgentHost));
+
+// Get the agent card
+AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
+
+// Use A2AClientOptions to explicitly select the HTTP+JSON protocol binding.
+// This tells the A2A client factory to prefer the HTTP+JSON interface when the agent card
+// advertises multiple supported interfaces.
+A2AClientOptions options = new()
+{
+    PreferredBindings = [ProtocolBindingNames.HttpJson]
+};
+
+// To prefer JSON-RPC instead, use:
+// A2AClientOptions options = new()
+// {
+//     PreferredBindings = [ProtocolBindingNames.JsonRpc]
+// };
+
+// Create an instance of the AIAgent for an existing A2A agent, using the specified protocol binding.
+AIAgent agent = agentCard.AsAIAgent(options: options);
+
+// Invoke the agent and output the text result.
+AgentResponse response = await agent.RunAsync("Tell me a joke about a pirate.");
+Console.WriteLine(response);
@@ -0,0 +1,27 @@
+# A2A Agent Protocol Selection
+
+This sample demonstrates how to select the A2A protocol binding when creating an `AIAgent` from an A2A agent card.
+
+A2A agents can expose multiple interfaces with different protocol bindings (e.g., HTTP+JSON, JSON-RPC). By default, `AsAIAgent()` prefers HTTP+JSON with JSON-RPC as a fallback. This sample shows how to use `A2AClientOptions.PreferredBindings` to explicitly control which protocol binding is used.
+
+The sample:
+
+- Connects to an A2A agent server specified in the `A2A_AGENT_HOST` environment variable
+- Configures `A2AClientOptions` to prefer the HTTP+JSON protocol binding
+- Creates an `AIAgent` from the resolved agent card using the specified binding
+- Sends a message to the agent and displays the response
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10.0 SDK or later
+- An A2A agent server running and accessible via HTTP
+
+**Note**: These samples need to be run against a valid A2A server. If no A2A server is available, they can be run against the echo-agent that can be spun up locally by following the guidelines at: https://github.com/a2aproject/a2a-dotnet/blob/main/samples/AgentServer/README.md
+
+Set the following environment variable:
+
+```powershell
+$env:A2A_AGENT_HOST="http://localhost:5000"  # Replace with your A2A agent server host
+```
@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="A2A" />
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to reconnect to an A2A agent's streaming response using continuation tokens,
+// allowing recovery from stream interruptions without losing progress.
+
+using A2A;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var a2aAgentHost = Environment.GetEnvironmentVariable("A2A_AGENT_HOST") ?? throw new InvalidOperationException("A2A_AGENT_HOST is not set.");
+
+// Initialize an A2ACardResolver to get an A2A agent card.
+A2ACardResolver agentCardResolver = new(new Uri(a2aAgentHost));
+
+// Get the agent card
+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.CreateSessionAsync();
+
+ResponseContinuationToken? continuationToken = null;
+
+await foreach (var update in agent.RunStreamingAsync("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))
+{
+    // Saving the continuation token to be able to reconnect to the same response stream later.
+    // Note: Continuation tokens are only returned for long-running tasks. If the underlying A2A agent
+    // returns a message instead of a task, the continuation token will not be initialized.
+    // A2A agents do not support stream resumption from a specific point in the stream,
+    // but only reconnection to obtain the same response stream from the beginning.
+    // So, A2A agents will return an initialized continuation token in the first update
+    // representing the beginning of the stream, and it will be null in all subsequent updates.
+    if (update.ContinuationToken is { } token)
+    {
+        continuationToken = token;
+    }
+
+    // Imitating stream interruption
+    break;
+}
+
+// Reconnect to the same response stream using the continuation token obtained from the previous run.
+// As a first update, the agent will return an update representing the current state of the response at the moment of calling
+// RunStreamingAsync with the same continuation token, followed by other updates until the end of the stream is reached.
+if (continuationToken is not null)
+{
+    await foreach (var update in agent.RunStreamingAsync(session, options: new() { ContinuationToken = continuationToken }))
+    {
+        if (!string.IsNullOrEmpty(update.Text))
+        {
+            Console.WriteLine(update.Text);
+        }
+    }
+}
@@ -0,0 +1,29 @@
+# A2A Agent Stream Reconnection
+
+This sample demonstrates how to reconnect to an A2A agent's streaming response using continuation tokens, allowing recovery from stream interruptions without losing progress.
+
+The sample:
+
+- Connects to an A2A agent server specified in the `A2A_AGENT_HOST` environment variable
+- Sends a request to the agent and begins streaming the response
+- Captures a continuation token from the stream for later reconnection
+- Simulates a stream interruption by breaking out of the streaming loop
+- Reconnects to the same response stream using the captured continuation token
+- Displays the response received after reconnection
+
+This pattern is useful when network interruptions or other failures may disrupt an ongoing streaming response, and you need to recover and continue processing.
+
+> **Note:** Continuation tokens are only available when the underlying A2A agent returns a task. If the agent returns a message instead, the continuation token will not be initialized and stream reconnection is not applicable.
+
+# Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 10.0 SDK or later
+- An A2A agent server running and accessible via HTTP
+
+Set the following environment variable:
+
+```powershell
+$env:A2A_AGENT_HOST="http://localhost:5000"  # Replace with your A2A agent server host
+```
@@ -0,0 +1,53 @@
+# Agent-to-Agent (A2A) Samples
+
+These samples demonstrate how to work with Agent-to-Agent (A2A) specific features in the Agent Framework.
+
+For other samples that demonstrate how to use AIAgent instances,
+see the [Getting Started With Agents](../Agents/README.md) samples.
+
+## Prerequisites
+
+See the README.md for each sample for the prerequisites for that sample.
+
+## Samples
+
+|Sample|Description|
+|---|---|
+|[A2A Agent As Function Tools](./A2AAgent_AsFunctionTools/)|This sample demonstrates how to represent an A2A agent as a set of function tools, where each function tool corresponds to a skill of the A2A agent, and register these function tools with another AI agent so it can leverage the A2A agent's skills.|
+|[A2A Agent Polling For Task Completion](./A2AAgent_PollingForTaskCompletion/)|This sample demonstrates how to poll for long-running task completion using continuation tokens with an A2A agent.|
+|[A2A Agent Stream Reconnection](./A2AAgent_StreamReconnection/)|This sample demonstrates how to reconnect to an A2A agent's streaming response using continuation tokens, allowing recovery from stream interruptions.|
+|[A2A Agent Protocol Selection](./A2AAgent_ProtocolSelection/)|This sample demonstrates how to select the A2A protocol binding (HTTP+JSON vs JSON-RPC) when creating an AIAgent from an A2A agent card using A2AClientOptions.|
+
+## Running the samples from the console
+
+To run the samples, navigate to the desired sample directory, e.g.
+
+```powershell
+cd A2AAgent_AsFunctionTools
+```
+
+Set the required environment variables as documented in the sample readme.
+If the variables are not set, you will be prompted for the values when running the samples.
+Execute the following command to build the sample:
+
+```powershell
+dotnet build
+```
+
+Execute the following command to run the sample:
+
+```powershell
+dotnet run --no-build
+```
+
+Or just build and run in one step:
+
+```powershell
+dotnet run
+```
+
+## Running the samples from Visual Studio
+
+Open the solution in Visual Studio and set the desired sample project as the startup project. Then, run the project using the built-in debugger or by pressing `F5`.
+
+You will be prompted for any required environment variables if they are not already set.