Exploring the Semantic Kernel Open AI Assistant Agent (Experimental)

  • Article

Warning

The Semantic Kernel Agent Framework is experimental, still in development and is subject to change.

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.

Creating an Open AI Assistant Agent

Creating an Open AI Assistant requires invoking a remote service, which is handled asynchronously. To manage this, the Open AI Assistant Agent 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.

OpenAIAssistantAgent agent =
    await OpenAIAssistantAgent.CreateAsync(
        OpenAIClientProvider.ForAzureOpenAI(/*<...service configuration>*/),
        new OpenAIAssistantDefinition("<model name>")
        {
          Name = "<agent name>",
          Instructions = "<agent instructions>",
        },
        new Kernel());

azure_agent = await AzureAssistantAgent.create(
    kernel=kernel, 
    service_id=service_id, 
    name="<agent name>", 
    instructions="<agent instructions>"
)

# or

openai_agent = await OpenAIAssistantAgent.create(
    kernel=kernel, 
    service_id=service_id, 
    name="<agent name>", 
    instructions="<agent instructions>"
)

Agents are currently unavailable in Java.

Retrieving an Open AI Assistant Agent

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

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

OpenAIAssistantAgent agent =
    await OpenAIAssistantAgent.RetrieveAsync(
        OpenAIClientProvider.ForAzureOpenAI(/*<...service configuration>*/),
        "<your agent id>",
        new Kernel());

agent = await OpenAIAssistantAgent.retrieve(id=agent_id, kernel=kernel)

# or

agent = await AzureAssistantAgent.retrieve(id=agent_id, kernel=kernel)

Agents are currently unavailable in Java.

Using an Open AI Assistant Agent

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 OpenAI Assistant Agent 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 Open AI Assistant Agent

Since the assistant's definition is stored remotely, it supports the capability to self-delete. This enables the agent to be removed from the system when it is no longer needed.

Note: Attempting to use an agent instance after being deleted results in an exception.

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

// Perform the deletion
await agent.DeleteAsync();

// Inspect whether an agent has been deleted
bool isDeleted = agent.IsDeleted();

await agent.delete()

is_deleted = agent._is_deleted

Agents are currently unavailable in Java.

How-To

For an end-to-end example for a Open AI Assistant Agent, see:

Agent Collaboration in Agent Chat