Files
Roger BarretoandCopilot fdc6e68f58 .Net: Semantic Kernel -> Agent Framework - Migration/Samples Update (AF 1.0 Compatible) (#13852)
## Description

Updates the SK → Agent Framework migration document, samples, and bridge
code from AF preview (`1.0.0-preview.251009.1`) to GA (`1.0.0`).

### Breaking changes addressed

| Preview API | AF 1.0 GA | Scope |
|---|---|---|
| `AgentThread` | `AgentSession` | Core type rename |
| `GetNewThread()` | `CreateSessionAsync()` | Now async |
| `AgentRunResponse` | `AgentResponse` | Return type rename |
| `AgentRunResponseUpdate` | `AgentResponseUpdate` | Streaming type
rename |
| `CreateAIAgent()` | `AsAIAgent()` | Extension method rename |
| `AssistantClient.CreateAIAgentAsync()` | **Removed** | Redirect to
Responses API |
| `PersistentAgentsClient` | **Obsolete** | Use `AIProjectClient` via
`Microsoft.Agents.AI.Foundry` |
| `Microsoft.Agents.AI.AzureAI` | `Microsoft.Agents.AI.Foundry` |
Package rename |
| `InProcessExecution.StreamAsync` | `RunStreamingAsync` | Workflow API
|
| `AgentRunUpdateEvent` | `AgentResponseUpdateEvent` | Workflow event |
| `AIAgent.Id` (virtual) | `IdCore` (protected virtual) | Override
pattern |

### Additional discoveries
- `using OpenAI.Chat;` required for `ChatClient.AsAIAgent()` extension
to resolve
- `using OpenAI.Responses;` required for `ResponsesClient.AsAIAgent()`
extension to resolve

### What changed

**Package versions** (`dotnet/Directory.Packages.props`)
- AF packages updated to `1.0.0`
- `Microsoft.Agents.AI.AzureAI` → `Microsoft.Agents.AI.Foundry`

**Bridge code** (`dotnet/src/Agents/Abstractions/AIAgent/`)
- `SemanticKernelAIAgent.cs`: New `Core` method overrides
(`CreateSessionCoreAsync`, `RunCoreAsync`, etc.)
- `SemanticKernelAIAgentThread` → `SemanticKernelAIAgentSession`
(extends `AgentSession`)

**31 migration samples** (all compile ✅)
- OpenAI/AzureOpenAI: `AsAIAgent`, `CreateSessionAsync`, `using
OpenAI.Chat;`
- Assistants (8): AF sections rewritten to Responses API
- Responses (8): Direct `ResponsesClient.AsAIAgent()`
- Foundry (4): `AIProjectClient.AsAIAgent()` via
`Microsoft.Agents.AI.Foundry`
- Orchestrations (3): `RunStreamingAsync`, `AgentResponseUpdateEvent`

**Migration document**
(`.github/upgrades/prompts/SemanticKernelToAgentFramework.md`)
- All AF preview API references updated to 1.0 GA patterns

**Unit/integration tests** (~15 files)
- Mechanical renames for `AgentSession`, `AgentResponse`,
`CreateSessionAsync`

### Validation

8 standalone console programs were created and executed against AF 1.0.0
NuGet packages with real API keys, validating all migration patterns
end-to-end:
1. OpenAI Basics (ChatClient → AsAIAgent, CreateSessionAsync,
Run/RunStreaming)
2. OpenAI ToolCall (AIFunctionFactory.Create, tool invocation)
3. OpenAI DI (ServiceProvider registration)
4. OpenAI Responses (ResponsesClient.AsAIAgent)
5. Azure AI Foundry (AIProjectClient.AsAIAgent)
6. Workflows Handoff (HandoffWorkflowBuilder,
InProcessExecution.RunStreamingAsync)
7. Session Lifecycle (Create, Serialize, Deserialize, multi-turn)
8. Assistants Migration Path (Responses API as replacement)

---------

Co-authored-by: Copilot <[email protected]>
2026-05-12 14:49:47 +00:00

226 lines
7.8 KiB
C#

// Copyright (c) Microsoft. All rights reserved.
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents.OpenAI;
using Microsoft.SemanticKernel.ChatCompletion;
using OpenAI.Responses;
#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
#pragma warning disable SKEXP0110 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "o4-mini";
var userInput =
"""
Instructions:
- Given the React component below, think about it and change it so that nonfiction books have red
text.
- Return only the code in your reply
- Do not include any additional formatting, such as markdown code blocks
- For formatting, use four space tabs, and do not allow any lines of code to
exceed 80 columns
const books = [
{ title: 'Dune', category: 'fiction', id: 1 },
{ title: 'Frankenstein', category: 'fiction', id: 2 },
{ title: 'Moneyball', category: 'nonfiction', id: 3 },
];
export default function BookList() {
const listItems = books.map(book =>
<li>
{book.title}
</li>
);
return (
<ul>{listItems}</ul>
);
}
""";
Console.WriteLine($"User Input: {userInput}");
await SKAgentAsync();
await SKAgent_As_AFAgentAsync();
await AFAgentAsync();
async Task SKAgentAsync()
{
Console.WriteLine("\n=== SK Agent ===\n");
var responseClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
.GetResponsesClient();
OpenAIResponseAgent agent = new(responseClient, deploymentName)
{
Name = "Thinker",
Instructions = "You are good at thinking hard before answering.",
StoreEnabled = true
};
var agentOptions = new OpenAIResponseAgentInvokeOptions()
{
ResponseCreationOptions = new()
{
MaxOutputTokenCount = 8000,
ReasoningOptions = new()
{
ReasoningEffortLevel = OpenAI.Responses.ResponseReasoningEffortLevel.High,
ReasoningSummaryVerbosity = OpenAI.Responses.ResponseReasoningSummaryVerbosity.Detailed
}
}
};
Microsoft.SemanticKernel.Agents.AgentThread? thread = null;
await foreach (var item in agent.InvokeAsync(userInput, thread, agentOptions))
{
thread = item.Thread;
foreach (var content in item.Message.Items)
{
if (content is ReasoningContent thinking)
{
Console.Write($"Thinking: \n{thinking}\n---\n");
}
else if (content is Microsoft.SemanticKernel.TextContent text)
{
Console.Write($"Assistant: {text}");
}
}
Console.WriteLine(item.Message);
}
Console.WriteLine("---");
var userMessage = new ChatMessageContent(AuthorRole.User, userInput);
await foreach (var item in agent.InvokeStreamingAsync(userMessage, thread, agentOptions))
{
thread = item.Thread;
foreach (var content in item.Message.Items)
{
// Currently SK Agent doesn't output thinking in streaming mode.
// SK Issue: https://github.com/microsoft/semantic-kernel/issues/13046
// OpenAI SDK Issue: https://github.com/openai/openai-dotnet/issues/643
if (content is StreamingReasoningContent thinking)
{
Console.WriteLine($"Thinking: [{thinking}]");
continue;
}
if (content is StreamingTextContent text)
{
Console.WriteLine($"Response: [{text}]");
}
}
}
}
async Task SKAgent_As_AFAgentAsync()
{
Console.WriteLine("\n=== SK Agent Converted as an AF Agent ===\n");
var responseClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
.GetResponsesClient();
#pragma warning disable SKEXP0110 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
OpenAIResponseAgent skAgent = new(responseClient, deploymentName)
{
Name = "Thinker",
Instructions = "You are good at thinking hard before answering.",
StoreEnabled = true
};
var agent = skAgent.AsAIAgent();
#pragma warning restore SKEXP0110 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
var thread = await agent.CreateSessionAsync();
var agentOptions = new ChatClientAgentRunOptions(new()
{
MaxOutputTokens = 8000,
Reasoning = new()
{
Effort = ReasoningEffort.High,
Output = ReasoningOutput.Full
}
});
var result = await agent.RunAsync(userInput, thread, agentOptions);
// Retrieve the thinking as a full text block requires flattening multiple TextReasoningContents from multiple messages content lists.
string assistantThinking = string.Join("\n", result.Messages
.SelectMany(m => m.Contents)
.OfType<TextReasoningContent>()
.Select(trc => trc.Text));
var assistantText = result.Text;
Console.WriteLine($"Thinking: \n{assistantThinking}\n---\n");
Console.WriteLine($"Assistant: \n{assistantText}\n---\n");
Console.WriteLine("---");
await foreach (var update in agent.RunStreamingAsync(userInput, thread, agentOptions))
{
var thinkingContents = update.Contents
.OfType<TextReasoningContent>()
.Select(trc => trc.Text)
.ToList();
if (thinkingContents.Count != 0)
{
Console.WriteLine($"Thinking: [{string.Join("\n", thinkingContents)}]");
continue;
}
Console.WriteLine($"Response: [{update.Text}]");
}
}
async Task AFAgentAsync()
{
Console.WriteLine("\n=== AF Agent ===\n");
var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
.GetResponsesClient()
.AsAIAgent(model: deploymentName, name: "Thinker", instructions: "You are good at thinking hard before answering.");
var session = await agent.CreateSessionAsync();
var agentOptions = new ChatClientAgentRunOptions(new()
{
MaxOutputTokens = 8000,
Reasoning = new()
{
Effort = ReasoningEffort.High,
Output = ReasoningOutput.Full
}
});
var result = await agent.RunAsync(userInput, session, agentOptions);
// Retrieve the thinking as a full text block requires flattening multiple TextReasoningContents from multiple messages content lists.
string assistantThinking = string.Join("\n", result.Messages
.SelectMany(m => m.Contents)
.OfType<TextReasoningContent>()
.Select(trc => trc.Text));
var assistantText = result.Text;
Console.WriteLine($"Thinking: \n{assistantThinking}\n---\n");
Console.WriteLine($"Assistant: \n{assistantText}\n---\n");
Console.WriteLine("---");
await foreach (var update in agent.RunStreamingAsync(userInput, session, agentOptions))
{
var thinkingContents = update.Contents
.OfType<TextReasoningContent>()
.Select(trc => trc.Text)
.ToList();
if (thinkingContents.Count != 0)
{
Console.WriteLine($"Thinking: [{string.Join("\n", thinkingContents)}]");
continue;
}
Console.WriteLine($"Response: [{update.Text}]");
}
}