.NET Samples - Create 02-agents learning path step (#4107)

dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj

@@ -0,0 +1,15 @@
+<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.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/OpenAIChatClientAgent.cs

@@ -0,0 +1,96 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
+using OpenAI.Chat;
+using ChatMessage = OpenAI.Chat.ChatMessage;
+
+namespace OpenAIChatClientSample;
+
+/// <summary>
+/// Provides an <see cref="AIAgent"/> backed by an OpenAI chat completion implementation.
+/// </summary>
+public class OpenAIChatClientAgent : DelegatingAIAgent
+{
+    /// <summary>
+    /// Initialize an instance of <see cref="OpenAIChatClientAgent"/>
+    /// </summary>
+    /// <param name="client">Instance of <see cref="ChatClient"/></param>
+    /// <param name="instructions">Optional instructions for the agent.</param>
+    /// <param name="name">Optional name for the agent.</param>
+    /// <param name="description">Optional description for the agent.</param>
+    /// <param name="loggerFactory">Optional instance of <see cref="ILoggerFactory"/></param>
+    public OpenAIChatClientAgent(
+        ChatClient client,
+        string? instructions = null,
+        string? name = null,
+        string? description = null,
+        ILoggerFactory? loggerFactory = null) :
+        this(client, new()
+        {
+            Name = name,
+            Description = description,
+            ChatOptions = new ChatOptions() { Instructions = instructions },
+        }, loggerFactory)
+    {
+    }
+
+    /// <summary>
+    /// Initialize an instance of <see cref="OpenAIChatClientAgent"/>
+    /// </summary>
+    /// <param name="client">Instance of <see cref="ChatClient"/></param>
+    /// <param name="options">Options to create the agent.</param>
+    /// <param name="loggerFactory">Optional instance of <see cref="ILoggerFactory"/></param>
+    public OpenAIChatClientAgent(
+        ChatClient client, ChatClientAgentOptions options, ILoggerFactory? loggerFactory = null) :
+        base(new ChatClientAgent((client ?? throw new ArgumentNullException(nameof(client))).AsIChatClient(), options, loggerFactory))
+    {
+    }
+
+    /// <summary>
+    /// Run the agent with the provided message and arguments.
+    /// </summary>
+    /// <param name="messages">The messages to pass to the agent.</param>
+    /// <param name="session">The conversation session to continue with this invocation. If not provided, creates a new session. The session will be mutated with the provided messages and agent response.</param>
+    /// <param name="options">Optional parameters for agent invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatCompletion"/> containing the list of <see cref="ChatMessage"/> items.</returns>
+    public virtual async Task<ChatCompletion> RunAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var response = await this.RunAsync(messages.AsChatMessages(), session, options, cancellationToken).ConfigureAwait(false);
+
+        return response.AsOpenAIChatCompletion();
+    }
+
+    /// <summary>
+    /// Run the agent streaming with the provided message and arguments.
+    /// </summary>
+    /// <param name="messages">The messages to pass to the agent.</param>
+    /// <param name="session">The conversation session to continue with this invocation. If not provided, creates a new session. The session will be mutated with the provided messages and agent response.</param>
+    /// <param name="options">Optional parameters for agent invocation.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatCompletion"/> containing the list of <see cref="ChatMessage"/> items.</returns>
+    public virtual IAsyncEnumerable<StreamingChatCompletionUpdate> RunStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var response = this.RunStreamingAsync(messages.AsChatMessages(), session, options, cancellationToken);
+
+        return response.AsChatResponseUpdatesAsync().AsOpenAIStreamingChatCompletionUpdatesAsync(cancellationToken);
+    }
+
+    /// <inheritdoc/>
+    protected sealed override Task<AgentResponse> RunCoreAsync(IEnumerable<Microsoft.Extensions.AI.ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) =>
+        base.RunCoreAsync(messages, session, options, cancellationToken);
+
+    /// <inheritdoc/>
+    protected override IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(IEnumerable<Microsoft.Extensions.AI.ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) =>
+        base.RunCoreStreamingAsync(messages, session, options, cancellationToken);
+}

dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Program.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to create an AI agent directly from an OpenAI.Chat.ChatClient instance using OpenAIChatClientAgent.
+
+using OpenAI;
+using OpenAI.Chat;
+using OpenAIChatClientSample;
+
+string apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
+string model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";
+
+// Create a ChatClient directly from OpenAIClient
+ChatClient chatClient = new OpenAIClient(apiKey).GetChatClient(model);
+
+// Create an agent directly from the ChatClient using OpenAIChatClientAgent
+OpenAIChatClientAgent agent = new(chatClient, instructions: "You are good at telling jokes.", name: "Joker");
+
+UserChatMessage chatMessage = new("Tell me a joke about a pirate.");
+
+// Invoke the agent and output the text result.
+ChatCompletion chatCompletion = await agent.RunAsync([chatMessage]);
+Console.WriteLine(chatCompletion.Content.Last().Text);
+
+// Invoke the agent with streaming support.
+IAsyncEnumerable<StreamingChatCompletionUpdate> completionUpdates = agent.RunStreamingAsync([chatMessage]);
+await foreach (StreamingChatCompletionUpdate completionUpdate in completionUpdates)
+{
+    if (completionUpdate.ContentUpdate.Count > 0)
+    {
+        Console.WriteLine(completionUpdate.ContentUpdate[0].Text);
+    }
+}

dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/README.md

@@ -0,0 +1,22 @@
+# Creating an Agent from a ChatClient
+
+This sample demonstrates how to create an AI agent directly from an `OpenAI.Chat.ChatClient` instance using the `OpenAIChatClientAgent` class.
+
+## What This Sample Shows
+
+- **Direct ChatClient Creation**: Shows how to create an `OpenAI.Chat.ChatClient` from `OpenAI.OpenAIClient` and then use it to instantiate an agent
+- **OpenAIChatClientAgent**: Demonstrates using the OpenAI SDK primitives instead of the ones from Microsoft.Extensions.AI and Microsoft.Agents.AI abstractions
+- **Full Agent Capabilities**: Shows both regular and streaming invocation of the agent
+
+## Running the Sample
+
+1. Set the required environment variables:
+   ```bash
+   set OPENAI_API_KEY=your_api_key_here
+   set OPENAI_MODEL=gpt-4o-mini
+   ```
+
+2. Run the sample:
+   ```bash
+   dotnet run
+   ```