Share via

Exploring the Semantic Kernel OpenAIAssistantAgent

  • Article

Important

This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability.

Detailed API documentation related to this discussion is available at:

Agents are currently unavailable in Java.

What is an Assistant?

The OpenAI Assistant API is a specialized interface designed for more advanced and interactive AI capabilities, enabling developers to create personalized and multi-step task-oriented agents. Unlike the Chat Completion API, which focuses on simple conversational exchanges, the Assistant API allows for dynamic, goal-driven interactions with additional features like code-interpreter and file-search.

Preparing Your Development Environment

To proceed with developing an OpenAIAIAssistantAgent, configure your development environment with the appropriate packages.

Add the Microsoft.SemanticKernel.Agents.OpenAI package to your project:

dotnet add package Microsoft.SemanticKernel.Agents.AzureAI --prerelease

You may also want to include the Azure.Identity package:

dotnet add package Azure.Identity

Install the semantic-kernel package with the optional Azure dependencies:

pip install semantic-kernel[azure]

Agents are currently unavailable in Java.

Creating an OpenAIAssistantAgent

Creating an OpenAIAssistant requires invoking a remote service, which is handled asynchronously. To manage this, the OpenAIAssistantAgent is instantiated through a static factory method, ensuring the process occurs in a non-blocking manner. This method abstracts the complexity of the asynchronous call, returning a promise or future once the assistant is fully initialized and ready for use.

AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient();
Assistant assistant =
    await this.AssistantClient.CreateAssistantAsync(
        "<model name>",
        "<agent name>",
        instructions: "<agent instructions>");
OpenAIAssistantAgent agent = new(assistant, client);

from semantic_kernel.agents.open_ai import AzureAssistantAgent, OpenAIAssistantAgent

# Set up the client and model using Azure OpenAI Resources
client, model = AzureAssistantAgent.setup_resources()

# Define the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="<instructions>",
    name="<agent name>",
)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
)

# or

# Set up the client and model using OpenAI Resources
client, model = OpenAIAssistantAgent.setup_resources()

# Define the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="<instructions>",
    name="<agent name>",
)

# Create the OpenAIAssistantAgent instance using the client and the assistant definition
agent = OpenAIAssistantAgent(
    client=client,
    definition=definition,
)

Agents are currently unavailable in Java.

Retrieving an OpenAIAssistantAgent

Once created, the identifier of the assistant may be access via its identifier. This identifier may be used to create an OpenAIAssistantAgent from an existing assistant definition.

For .NET, the agent identifier is exposed as a string via the property defined by any agent.

AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient();
Assistant assistant = await this.AssistantClient.GetAssistantAsync("<assistant id>");
OpenAIAssistantAgent agent = new(assistant, client);

# Using Azure OpenAI Resources

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    name="<agent name>",
    instructions="<instructions>",
)

# Store the assistant ID
assistant_id = definition.id

# Retrieve the assistant definition from the server based on the assistant ID
new_asst_definition = await client.beta.assistants.retrieve(assistant_id)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=new_asst_definition,
)

Agents are currently unavailable in Java.

Using an OpenAIAssistantAgent

As with all aspects of the Assistant API, conversations are stored remotely. Each conversation is referred to as a thread and identified by a unique string identifier. Interactions with your OpenAIAssistantAgent are tied to this specific thread identifier which must be specified when calling the agent/

// Define agent
OpenAIAssistantAgent agent = ...;

// Create a thread for the agent conversation.
string threadId = await agent.CreateThreadAsync();

// Add a user message to the conversation
chat.Add(threadId, new ChatMessageContent(AuthorRole.User, "<user input>"));

// Generate the agent response(s)
await foreach (ChatMessageContent response in agent.InvokeAsync(threadId))
{
  // Process agent response(s)...
}

// Delete the thread when it is no longer needed
await agent.DeleteThreadAsync(threadId);

# Define agent
openai_agent = await ...

# Create a thread for the agent conversation
thread_id = await agent.create_thread()

# Add a user message to the conversation
await agent.add_chat_message(
  thread_id=thread_id, 
  message=ChatMessageContent(role=AuthorRole.USER, content="<user input>"),
)

# Generate the agent response(s)
async for response in agent.invoke(thread_id=thread_id):
  # process agent response(s)...

# Delete the thread when it is no longer needed
await agent.delete_thread(thread_id)

Agents are currently unavailable in Java.

Deleting an OpenAIAssistantAgent

Since the assistant's definition is stored remotely, it will persist if not deleted.
Deleting an assistant definition may be performed directly with the AssistantClient.

Note: Attempting to use an agent instance after being deleted will result in a service exception.

For .NET, the agent identifier is exposed as a string via the Agent.Id property defined by any agent.

AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient();
Assistant assistant = await this.AssistantClient.DeleteAssistantAsync("<assistant id>");

await agent.delete()

is_deleted = agent._is_deleted

Agents are currently unavailable in Java.

How-To

For an end-to-end example for a OpenAIAssistantAgent, see:

Exploring the Azure AI Agent