Add extension methods to get an AF agent from a Foundry Client (#191)

* Add helpers to go from foundry client to agent more easily. * Fix xml docs.
2026-06-16 21:04:09 +08:00 · 2025-07-16 14:45:31 +00:00
parent 95a3264c8b
commit dd32a6d399
6 changed files with 140 additions and 11 deletions
@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>$(ProjectsTargetFrameworks)</TargetFrameworks>
+    <TargetFrameworks Condition="'$(Configuration)' == 'Debug'">$(ProjectsDebugTargetFrameworks)</TargetFrameworks>
+    <VersionSuffix>alpha</VersionSuffix>
+  </PropertyGroup>
+
+  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Agents.Persistent" />
+    <PackageReference Include="Microsoft.Extensions.AI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Microsoft.Extensions.AI.Agents\Microsoft.Extensions.AI.Agents.csproj" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <!-- NuGet Package Settings -->
+    <Title>Microsoft.Extensions.AI.Agents.AzureAI</Title>
+    <Description>Implementation of generative AI abstractions for Azure AI Persistent Agents.</Description>
+  </PropertyGroup>
+
+</Project>
@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.AI.Agents;
+
+namespace Azure.AI.Agents.Persistent;
+
+/// <summary>
+/// Provides extension methods for <see cref="PersistentAgentsClient"/>.
+/// </summary>
+public static class PersistentAgentsClientExtensions
+{
+    /// <summary>
+    /// Retrieves an existing server side agent, wrapped as a <see cref="ChatClientAgent"/> using the provided <see cref="PersistentAgentsClient"/>.
+    /// </summary>
+    /// <param name="persistentAgentsClient">The <see cref="PersistentAgentsClient"/> to create the <see cref="ChatClientAgent"/> with.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> for the persistent agent.</returns>
+    /// <param name="agentId"> The ID of the server side agent to create a <see cref="ChatClientAgent"/> for.</param>
+    /// <param name="chatOptions">Options that should apply to all runs of the agent.</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="ChatClientAgent"/> instance that can be used to perform operations on the persistent agent.</returns>
+    public static async Task<ChatClientAgent> GetRunnableAgentAsync(
+        this PersistentAgentsClient persistentAgentsClient,
+        string agentId,
+        ChatOptions? chatOptions = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (persistentAgentsClient is null)
+        {
+            throw new ArgumentNullException(nameof(persistentAgentsClient));
+        }
+
+        if (string.IsNullOrWhiteSpace(agentId))
+        {
+            throw new ArgumentException($"{nameof(agentId)} should not be null or whitespace.", nameof(agentId));
+        }
+
+        var persistentAgentResponse = await persistentAgentsClient.Administration.GetAgentAsync(agentId, cancellationToken).ConfigureAwait(false);
+        return persistentAgentResponse.AsRunnableAgent(persistentAgentsClient, chatOptions);
+    }
+}
@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.AI.Agents;
+
+namespace Azure.AI.Agents.Persistent;
+
+/// <summary>
+/// Provides extension methods for working with <see cref="Response{PersistentAgent}"/>.
+/// </summary>
+internal static class PersistentAgentResponseExtensions
+{
+    /// <summary>
+    /// Converts a response containing persistent agent metadata into a runnable agent instance.
+    /// </summary>
+    /// <param name="persistentAgentResponse">The response containing the persistent agent to be converted. Cannot be <see langword="null"/>.</param>
+    /// <param name="persistentAgentsClient">The client used to interact with persistent agents. Cannot be <see langword="null"/>.</param>
+    /// <param name="chatOptions">The default <see cref="ChatOptions"/> to use when interacting with the agent.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the persistent agent.</returns>
+    public static ChatClientAgent AsRunnableAgent(this Response<PersistentAgent> persistentAgentResponse, PersistentAgentsClient persistentAgentsClient, ChatOptions? chatOptions = null)
+    {
+        if (persistentAgentResponse is null)
+        {
+            throw new ArgumentNullException(nameof(persistentAgentResponse));
+        }
+
+        return AsRunnableAgent(persistentAgentResponse.Value, persistentAgentsClient, chatOptions);
+    }
+
+    /// <summary>
+    /// Converts a <see cref="PersistentAgent"/> containing metadata about a persistent agent into a runnable agent instance.
+    /// </summary>
+    /// <param name="persistentAgentMetadata">The persistent agent metadata to be converted. Cannot be <see langword="null"/>.</param>
+    /// <param name="persistentAgentsClient">The client used to interact with persistent agents. Cannot be <see langword="null"/>.</param>
+    /// <param name="chatOptions">The default <see cref="ChatOptions"/> to use when interacting with the agent.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the persistent agent.</returns>
+    public static ChatClientAgent AsRunnableAgent(this PersistentAgent persistentAgentMetadata, PersistentAgentsClient persistentAgentsClient, ChatOptions? chatOptions = null)
+    {
+        if (persistentAgentMetadata is null)
+        {
+            throw new ArgumentNullException(nameof(persistentAgentMetadata));
+        }
+
+        if (persistentAgentsClient is null)
+        {
+            throw new ArgumentNullException(nameof(persistentAgentsClient));
+        }
+
+#pragma warning disable CA2000 // Dispose objects before losing scope
+        var chatClient = persistentAgentsClient.AsIChatClient(persistentAgentMetadata.Id);
+#pragma warning restore CA2000 // Dispose objects before losing scope
+
+        return new ChatClientAgent(chatClient, options: new()
+        {
+            Id = persistentAgentMetadata.Id,
+            Name = persistentAgentMetadata.Name,
+            Description = persistentAgentMetadata.Description,
+            Instructions = persistentAgentMetadata.Instructions,
+            ChatOptions = chatOptions
+        });
+    }
+}