Graduate Agent Abstractions

[alliscode]

Agent Framework Feature Graduation

Plan for the graduation of certain components in the Agent Framework

---

Checklist to be completed when graduating an experimental feature

• Notify PM's and EM's that feature is ready for graduation

  Shawn has been involved and engaged at every step with visibility given to Evan and Sophia (PM's).
  Ben and Mark (EM's) have been engaged throughout the process as well.

• Contact PM for list of sample use cases

• Verify there are sample implementations​ for each of the use cases

• Verify telemetry and logging are complete

• ​Verify API docs are complete and arrange to have them published

  API docs generated in build pipeline and are complete. Need to ensure publish pipeline is active.

• Make appropriate updates to Learn docs​

  Learn docs need to be updated for the breaking changes to OpenAIAssistant. We do have backwards compatibility with what is current documented.

  Update Agent Framework Learn Site Docs with New Agent Types #10541

• Make appropriate updates to Concept samples

• Make appropriate updates to Blog posts

  https://devblogs.microsoft.com/semantic-kernel/release-the-agents-sk-agents-framework-rc1/

• Verify there are no serious open Issues​​

• Update table in EXPERIMENTS.md

  No update as SKEXP0110 is still being used for non-graduated features in the Agent Framework.

• Remove SKEXP​ flag from the experimental code

  .Net Agents: Update experimental meta-data for graduation #10600

[crickman]

.NET API Being Graduated:

Class: Agent

public

• Id
• Name
• LoggerFactory

protected

• Logger
• ActiveLoggerFactory

Class: KernelAgent : Agent

public

• Arguments

• Instructions

• Kernel

protected

• Template

• FormatInstructionsAsync(Microsoft.SemanticKernel.Kernel, Microsoft.SemanticKernel.KernelArguments, System.Threading.CancellationToken)

• MergeArguments(Microsoft.SemanticKernel.KernelArguments)

Class: ChatHistoryKernelAgent : KernelAgent

public

• HistoryReducer

• InvokeAsync(Microsoft.SemanticKernel.ChatCompletion.ChatHistory, Microsoft.SemanticKernel.KernelArguments, Microsoft.SemanticKernel.Kernel, System.Threading.CancellationToken)

• InvokeStreamingAsync(Microsoft.SemanticKernel.ChatCompletion.ChatHistory, Microsoft.SemanticKernel.KernelArguments, Microsoft.SemanticKernel.Kernel, System.Threading.CancellationToken)

• ReduceAsync(Microsoft.SemanticKernel.ChatCompletion.ChatHistory, System.Threading.CancellationToken)

Class: ChatCompletionAgent : ChatHistoryKernelAgent

public

• ChatCompletionAgent()

• ChatCompletionAgent(Microsoft.SemanticKernel.PromptTemplateConfig, Microsoft.SemanticKernel.IPromptTemplateFactory)

• InstructionsRole

• InvokeAsync(Microsoft.SemanticKernel.ChatCompletion.ChatHistory, Microsoft.SemanticKernel.KernelArguments, Microsoft.SemanticKernel.Kernel, System.Threading.CancellationToken)

• InvokeStreamingAsync(Microsoft.SemanticKernel.ChatCompletion.ChatHistory, Microsoft.SemanticKernel.KernelArguments, Microsoft.SemanticKernel.Kernel, System.Threading.CancellationToken)

Class: OpenAIAssistantAgent : KernelAgent

public/static

• CreateAzureOpenAIClient(System.ClientModel.ApiKeyCredential, System.Uri, System.Net.Http.HttpClient)

• CreateAzureOpenAIClient(Azure.Core.TokenCredential, System.Uri, System.Net.Http.HttpClient)

• CreateOpenAIClient(System.Uri, System.Net.Http.HttpClient)

public

• CreateOpenAIClient(System.ClientModel.ApiKeyCredential, System.Uri, System.Net.Http.HttpClient)

• OpenAIAssistantAgent(OpenAI.Assistants.Assistant, OpenAI.Assistants.AssistantClient, System.Collections.Generic.IEnumerable{Microsoft.SemanticKernel.KernelPlugin}, Microsoft.SemanticKernel.IPromptTemplateFactory, System.String)

• Client

• Definition

• PollingOptions

• RunOptions

• AddChatMessageAsync(System.String, Microsoft.SemanticKernel.ChatMessageContent, System.Threading.CancellationToken)

• GetThreadMessagesAsync(System.String, System.Threading.CancellationToken)

• InvokeAsync(System.String, Microsoft.SemanticKernel.KernelArguments, Microsoft.SemanticKernel.Kernel, System.Threading.CancellationToken)

• InvokeAsync(System.String, OpenAI.Assistants.RunCreationOptions, Microsoft.SemanticKernel.KernelArguments, Microsoft.SemanticKernel.Kernel, System.Threading.CancellationToken)

• InvokeStreamingAsync(System.String, Microsoft.SemanticKernel.KernelArguments, Microsoft.SemanticKernel.Kernel, Microsoft.SemanticKernel.ChatCompletion.ChatHistory, System.Threading.CancellationToken)

• InvokeStreamingAsync(System.String, OpenAI.Assistants.RunCreationOptions, Microsoft.SemanticKernel.KernelArguments, Microsoft.SemanticKernel.Kernel, Microsoft.SemanticKernel.ChatCompletion.ChatHistory, System.Threading.CancellationToken)

Class: AssistantClientExtensions

public/static

• CreateAssistantAsync(...)

• CreateAssistantFromTemplateAsync(...)

• CreateThreadAsync(OpenAI.Assistants.AssistantClient, System.Collections.Generic.IEnumerable{Microsoft.SemanticKernel.ChatMessageContent}, ...)

---

Class: ChatContentMessageExtensions

public/static

• ToThreadInitializationMessage(Microsoft.SemanticKernel.ChatMessageContent)

• ToThreadInitializationMessages(System.Collections.Generic.IEnumerable{Microsoft.SemanticKernel.ChatMessageContent})

Class: RunPollingOptions

public

• DefaultMaximumRetryCount
• DefaultPollingInterval
• DefaultPollingBackoff
• DefaultPollingBackoffThreshold
• DefaultMessageSynchronizationDelay
• MaximumRetryCount
• RunPollingInterval
• RunPollingBackoff
• RunPollingBackoffThreshold
• MessageSynchronizationDelay
• GetPollingInterval(System.Int32)

[crickman]

.NET OpenAIAssistantAgent Migration Guide

We recently applied a significant shift around the OpenAIAssistantAgent in the Semantic Kernel Agent Framework.

These changes were applied in:

• PR #10583
• PR #10616
• PR #10633

These changes are intended to:

• Align with the pattern for using for our AzureAIAgent.
• Fix bugs around static initialization pattern.
• Avoid limiting features based on our abstraction of the underlying SDK.

Migration Tactics

All deprecated patterns are maked with the [Obsolete] attribute that includes an actionable message on the preferred pattern.

As always, our samples illustrate usage of the Agent Framework:

• GettingStartedWithAgents
• Concepts/Agents

The following migration tactics are included to clarity how to move forward with the new patterns.

Backwards Compatibility / "Do Nothing"

By retaining the deprecated patterns, backwards compatibility has been maintained.

To proceed without any migration, you may suppress warning (CS0618) for obsolete patterns and properties in your projext file:

  <PropertyGroup>
    <NoWarn>$(NoWarn);CS0618</NoWarn>
  </PropertyGroup>

Client Instantiation

Previously, an OpenAIClientProvider was required to initiate any OpenAIAssistantAgent.

This has been changed to only require an AssistantClient.

Static methods exist on OpenAIAssistantAgent to aid in creating a AssistantClient:

• OpenAIAssistantAgent.CreateAzureOpenAIClient(...)
• OpenAIAssistantAgent.CreateOpenAIClient(...)

Example:

OpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(endpointUrl));
AssistantClient assistantClient = client.GetAssistantClient();

Assistant Lifecycle

Constructor

You may now invoke the public constructor of OpenAIAssistantAgent with a corresponding Assistant definition. This Assistant definition may be newly created or retrieved by its identifier using the AssistantClient.

Assistant definition = await assistantClient.GetAssistantAsync(assistantId);
OpenAIAssistantAgent agent = new(definition, client);

Additionally, plugins may be provided streamlining the agent initialization process:

KernelPlugin plugin = KernelPluginFactory.CreateFromType<YourPlugin>()
Assistant definition = await assistantClient.GetAssistantAsync(assistantId);
OpenAIAssistantAgent agent = new(definition, client, [plugin]);

To create a new assistant definition, we've provided a convenient extension method that streamlines common configuations such as enabling the code-interpeter:

Assistant assistant =
    await assistantClient.CreateAssistantAsync(
        this.Model,
        name,
        instructions: instructions,
        enableCodeInterpreter: true);

Invocation

When invoking an agent, you may optionally specify RunCreationOptions instead of OpenAIAssistantInvocationOptions. This enables the access to the full set of features exposed in the underlying SDK.

Deletion

await assistantClient.DeleteAssistantAsync(agent.Id);

Thread Lifecycle

Thread creation and deletion may be directly managed using the AssistantClient.

Creation

The AssistantClient may be directly utilized to create a thread:

AssistantThread thread = await assistantClient.CreateThreadAsync();

Extension Method

We provide a convenient extension method that can handle translation of ChatMessageContent:

string threadId = await assistantClient.CreateThreadAsync(messages: [new ChatMessageContent(AuthorRole.User, "<message content>")]);

Deletion

Likewise, the AssistantClient may be directly utilized to delete a thread:

await assistantClient.DeleteThreadAsync(thread.Id);

File Lifecycle

File creation and deletion may be directly managed using the OpenAIFileClient.

We've also added a convenient extension method to streamline this operation using the OpenAIClient:

Upload

string fileId = await client.UploadAssistantFileAsync(stream, "<filename>");

Deletion

await client.DeleteFileAsync(fileId);

VectorStore Lifecycle

Lifecycle management of a Vector Store has always required using the VectorStoreClient; however, we've added a convenient extension method to streamline this operation using the OpenAIClient.

Creation

string vectorStoreId = await client.CreateVectorStoreAsync([fileId1, fileId2], waitUntilCompleted: true);

Deletion

await client.DeleteVectorStoreAsync(vectorStoreId);