chore: import upstream snapshot with attribution
CodeQL / Analyze (csharp) (push) Has been cancelled
CodeQL / Analyze (python) (push) Has been cancelled

This commit is contained in:
wehub-resource-sync
2026-07-13 13:21:23 +08:00
commit b957a53def
5423 changed files with 863745 additions and 0 deletions
@@ -0,0 +1,110 @@
## OpenAI Assistant Agents
The following getting started samples show how to use OpenAI Assistant agents with Semantic Kernel.
## Assistants API Overview
The Assistants API is a robust solution from OpenAI that empowers developers to integrate powerful, purpose-built AI assistants into their applications. It streamlines the development process by handling conversation histories, managing threads, and providing seamless access to advanced tools.
### Key Features
- **Purpose-Built AI Assistants:**
Assistants are specialized AIs that leverage OpenAIs models to interact with users, access files, maintain persistent threads, and call additional tools. This enables highly tailored and effective user interactions.
- **Simplified Conversation Management:**
The concept of a **thread** -- a dedicated conversation session between an assistant and a user -- ensures that message history is managed automatically. Threads optimize the conversation context by storing and truncating messages as needed.
- **Integrated Tool Access:**
The API provides built-in tools such as:
- **Code Interpreter:** Allows the assistant to execute code, enhancing its ability to solve complex tasks.
- **File Search:** Implements best practices for retrieving data from uploaded files, including advanced chunking and embedding techniques.
- **Enhanced Function Calling:**
With improved support for third-party tool integration, the Assistants API enables assistants to extend their capabilities beyond native functions.
For more detailed technical information, refer to the [Assistants API](https://platform.openai.com/docs/assistants/overview).
### Semantic Kernel OpenAI Assistant Agents
OpenAI Assistant Agents are created in the following way:
```python
from semantic_kernel.agents import OpenAIAssistantAgent
from semantic_kernel.connectors.ai.open_ai import OpenAISettings
# Create the client using OpenAI resources and configuration
client = OpenAIAssistantAgent.create_client()
# Create the assistant definition
definition = await client.beta.assistants.create(
model=OpenAISettings().chat_model_id,
instructions="<instructions>",
name="<name>",
)
# Define the Semantic Kernel OpenAI Assistant Agent
agent = OpenAIAssistantAgent(
client=client,
definition=definition,
)
# Define a thread to hold the conversation's context
# If a thread is not created initially it will be created
# and returned as part of the first response
thread = None
# Get the agent response
response = await agent.get_response(messages="Why is the sky blue?", thread=thread)
thread = response.thread
# or use the agent.invoke(...) method
async for response in agent.invoke(messages="Why is the sky blue?", thread=thread):
print(f"# {response.role}: {response.content}")
thread = response.thread
```
### Semantic Kernel Azure Assistant Agents
Azure Assistant Agents are currently in preview and require a `-preview` API version (minimum version: `2024-05-01-preview`). As new features are introduced, API versions will be updated accordingly. For the latest versioning details, please refer to the [Azure OpenAI API preview lifecycle](https://learn.microsoft.com/azure/ai-services/openai/api-version-deprecation).
To specify the correct API version, set the following environment variable (for example, in your `.env` file):
```bash
AZURE_OPENAI_API_VERSION="2025-01-01-preview"
```
Alternatively, you can pass the `api_version` parameter when creating an `AzureAssistantAgent`:
```python
from semantic_kernel.agents import AzureAssistantAgent
# Create the client using Azure OpenAI resources and configuration
client = AzureAssistantAgent.create_client()
# Create the assistant definition
definition = await client.beta.assistants.create(
model=model,
instructions="<instructions>",
name="<name>",
)
# Define the Semantic Kernel Azure OpenAI Assistant Agent
agent = AzureAssistantAgent(
client=client,
definition=definition,
)
# Define a thread to hold the conversation's context
# If a thread is not created initially it will be created
# and returned as part of the first response
thread = None
# Get the agent response
response = await agent.get_response(messages="Why is the sky blue?", thread=thread)
thread = response.thread
# or use the agent.invoke(...) method
async for response in agent.invoke(messages="Why is the sky blue?", thread=thread):
print(f"# {response.role}: {response.content}")
thread = response.thread
```
@@ -0,0 +1,76 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
from azure.identity import AzureCliCredential
from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent
from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings
"""
The following sample demonstrates how to create an OpenAI assistant using either
Azure OpenAI or OpenAI. The sample shows how to have the assistant answrer
questions about the world.
The interaction with the agent is via the `get_response` method, which sends a
user input to the agent and receives a response from the agent. The conversation
history is maintained by the agent service, i.e. the responses are automatically
associated with the thread. Therefore, client code does not need to maintain the
conversation history.
"""
# Simulate a conversation with the agent
USER_INPUTS = [
"Why is the sky blue?",
"What is the speed of light?",
"What have we been talking about?",
]
async def main():
# 1. Create the client using Azure OpenAI resources and configuration
client = AzureAssistantAgent.create_client(credential=AzureCliCredential())
# 2. Create the assistant on the Azure OpenAI service
definition = await client.beta.assistants.create(
model=AzureOpenAISettings().chat_deployment_name,
instructions="Answer questions about the world in one sentence.",
name="Assistant",
)
# 3. Create a Semantic Kernel agent for the Azure OpenAI assistant
agent = AzureAssistantAgent(
client=client,
definition=definition,
)
# 4. Create a new thread for use with the assistant
# If no thread is provided, a new thread will be
# created and returned with the initial response
thread: AssistantAgentThread = None
try:
for user_input in USER_INPUTS:
print(f"# User: '{user_input}'")
# 6. Invoke the agent for the current thread and print the response
response = await agent.get_response(messages=user_input, thread=thread)
print(f"# {response.name}: {response}")
thread = response.thread
finally:
# 7. Clean up the resources
await thread.delete() if thread else None
await agent.client.beta.assistants.delete(assistant_id=agent.id)
"""
You should see output similar to the following:
# User: 'Why is the sky blue?'
# Agent: The sky appears blue because molecules in the atmosphere scatter sunlight in all directions, and blue
light is scattered more than other colors because it travels in shorter, smaller waves.
# User: 'What is the speed of light?'
# Agent: The speed of light in a vacuum is approximately 299,792,458 meters per second
(about 186,282 miles per second).
"""
if __name__ == "__main__":
asyncio.run(main())
@@ -0,0 +1,100 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
from typing import Annotated
from azure.identity import AzureCliCredential
from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent
from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings
from semantic_kernel.functions import kernel_function
"""
The following sample demonstrates how to create an OpenAI
assistant using either Azure OpenAI or OpenAI. The sample
shows how to use a Semantic Kernel plugin as part of the
OpenAI Assistant.
"""
# Define a sample plugin for the sample
class MenuPlugin:
"""A sample Menu Plugin used for the concept sample."""
@kernel_function(description="Provides a list of specials from the menu.")
def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
return """
Special Soup: Clam Chowder
Special Salad: Cobb Salad
Special Drink: Chai Tea
"""
@kernel_function(description="Provides the price of the requested menu item.")
def get_item_price(
self, menu_item: Annotated[str, "The name of the menu item."]
) -> Annotated[str, "Returns the price of the menu item."]:
return "$9.99"
# Simulate a conversation with the agent
USER_INPUTS = [
"Hello",
"What is the special soup?",
"What is the special drink?",
"How much is it?",
"Thank you",
]
async def main():
# 1. Create the client using Azure OpenAI resources and configuration
client = AzureAssistantAgent.create_client(credential=AzureCliCredential())
# 2. Create the assistant on the Azure OpenAI service
definition = await client.beta.assistants.create(
model=AzureOpenAISettings().chat_deployment_name,
instructions="Answer questions about the menu.",
name="Host",
)
# 3. Create a Semantic Kernel agent for the Azure OpenAI assistant
agent = AzureAssistantAgent(
client=client,
definition=definition,
plugins=[MenuPlugin()], # The plugins can be passed in as a list to the constructor
)
# Note: plugins can also be configured on the Kernel and passed in as a parameter to the OpenAIAssistantAgent
# 4. Create a new thread for use with the assistant
# If no thread is provided, a new thread will be
# created and returned with the initial response
thread: AssistantAgentThread = None
try:
for user_input in USER_INPUTS:
print(f"# User: '{user_input}'")
# 6. Invoke the agent for the current thread and print the response
async for response in agent.invoke(messages=user_input, thread=thread):
print(f"# Agent: {response}")
thread = response.thread
finally:
# 7. Clean up the resources
await thread.delete() if thread else None
await agent.client.beta.assistants.delete(assistant_id=agent.id)
"""
You should see output similar to the following:
# User: 'Hello'
# Agent: Hello! How can I assist you today?
# User: 'What is the special soup?'
# Agent: The special soup today is Clam Chowder. Would you like to know more about any other menu items?
# User: 'What is the special drink?'
# Agent: The special drink today is Chai Tea. Would you like more information on anything else?
# User: 'Thank you'
# Agent: You're welcome! If you have any more questions or need further assistance, feel free to ask.
Enjoy your day!
"""
if __name__ == "__main__":
asyncio.run(main())
@@ -0,0 +1,89 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import os
from semantic_kernel.agents import AssistantAgentThread, OpenAIAssistantAgent
from semantic_kernel.connectors.ai.open_ai import OpenAISettings
from semantic_kernel.contents import AuthorRole, ChatMessageContent, FileReferenceContent, ImageContent, TextContent
"""
The following sample demonstrates how to create an OpenAI
assistant using OpenAI configuration, and leverage the
multi-modal content types to have the assistant describe images
and answer questions about them. This sample uses non-streaming responses.
"""
async def main():
# 1. Create the OpenAI Assistant Agent client
# Note Azure OpenAI doesn't support vision files yet
client = OpenAIAssistantAgent.create_client()
# 2. Load a sample image of a cat used for the assistant to describe
file_path = os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))), "resources", "cat.jpg")
with open(file_path, "rb") as file:
file = await client.files.create(file=file, purpose="assistants")
# 3. Create the assistant on the OpenAI service
definition = await client.beta.assistants.create(
model=OpenAISettings().chat_model_id,
instructions="Answer questions about the provided images.",
name="Vision",
)
# 4. Create a Semantic Kernel agent for the OpenAI assistant
agent = OpenAIAssistantAgent(
client=client,
definition=definition,
)
# 5. Create a new thread for use with the assistant
# If no thread is provided, a new thread will be
# created and returned with the initial response
thread: AssistantAgentThread = None
# 6. Define the user messages with the image content to simulate the conversation
user_messages = {
ChatMessageContent(
role=AuthorRole.USER,
items=[
TextContent(text="Describe this image."),
ImageContent(
uri="https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/New_york_times_square-terabass.jpg/1200px-New_york_times_square-terabass.jpg"
),
],
),
ChatMessageContent(
role=AuthorRole.USER,
items=[
TextContent(text="What is the main color in this image?"),
ImageContent(uri="https://upload.wikimedia.org/wikipedia/commons/5/56/White_shark.jpg"),
],
),
ChatMessageContent(
role=AuthorRole.USER,
items=[
TextContent(text="Is there an animal in this image?"),
FileReferenceContent(file_id=file.id),
],
),
}
try:
for message in user_messages:
print(f"# User: {str(message)}") # type: ignore
# 8. Invoke the agent for the current thread and print the response
async for response in agent.invoke(messages=message, thread=thread):
print(f"# Agent: {response}\n")
thread = response.thread
finally:
# 9. Clean up the resources
await client.files.delete(file.id)
await thread.delete() if thread else None
await agent.client.beta.assistants.delete(assistant_id=agent.id)
if __name__ == "__main__":
asyncio.run(main())
@@ -0,0 +1,59 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
from azure.identity import AzureCliCredential
from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent
from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings
"""
The following sample demonstrates how to create an OpenAI
assistant using either Azure OpenAI or OpenAI and leverage the
assistant's code interpreter functionality to have it write
Python code to print Fibonacci numbers.
"""
TASK = "Use code to determine the values in the Fibonacci sequence that that are less than the value of 101?"
async def main():
# 1. Create the client using Azure OpenAI resources and configuration
client = AzureAssistantAgent.create_client(credential=AzureCliCredential())
# 2. Configure the code interpreter tool and resources for the Assistant
code_interpreter_tool, code_interpreter_tool_resources = AzureAssistantAgent.configure_code_interpreter_tool()
# 3. Create the assistant on the Azure OpenAI service
definition = await client.beta.assistants.create(
model=AzureOpenAISettings().chat_deployment_name,
name="CodeRunner",
instructions="Run the provided request as code and return the result.",
tools=code_interpreter_tool,
tool_resources=code_interpreter_tool_resources,
)
# 4. Create a Semantic Kernel agent for the Azure OpenAI assistant
agent = AzureAssistantAgent(
client=client,
definition=definition,
)
# 5. Create a new thread for use with the assistant
# If no thread is provided, a new thread will be
# created and returned with the initial response
thread: AssistantAgentThread = None
print(f"# User: '{TASK}'")
try:
# 6. Invoke the agent for the current thread and print the response
async for response in agent.invoke(messages=TASK, thread=thread):
print(f"# Agent: {response}")
thread = response.thread
finally:
# 7. Clean up the resources
await thread.delete() if thread else None
await agent.client.beta.assistants.delete(agent.id)
if __name__ == "__main__":
asyncio.run(main())
@@ -0,0 +1,81 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import os
from azure.identity import AzureCliCredential
from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent
from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings
"""
The following sample demonstrates how to create an OpenAI
Assistant using either Azure OpenAI or OpenAI and leverage the
assistant's file search functionality.
"""
# Simulate a conversation with the agent
USER_INPUTS = {
"Who is the youngest employee?",
"Who works in sales?",
"I have a customer request, who can help me?",
}
async def main():
# 1. Create the client using Azure OpenAI resources and configuration
client = AzureAssistantAgent.create_client(credential=AzureCliCredential())
# 2. Read and upload the file to the Azure OpenAI assistant service
pdf_file_path = os.path.join(
os.path.dirname(os.path.dirname(os.path.realpath(__file__))), "resources", "employees.pdf"
)
with open(pdf_file_path, "rb") as file:
file = await client.files.create(file=file, purpose="assistants")
vector_store = await client.vector_stores.create(
name="step4_assistant_file_search",
file_ids=[file.id],
)
# 3. Create file search tool with uploaded resources
file_search_tool, file_search_tool_resources = AzureAssistantAgent.configure_file_search_tool(vector_store.id)
# 4. Create the assistant on the Azure OpenAI service with the file search tool
definition = await client.beta.assistants.create(
model=AzureOpenAISettings().chat_deployment_name,
instructions="Find answers to the user's questions in the provided file.",
name="FileSearch",
tools=file_search_tool,
tool_resources=file_search_tool_resources,
)
# 5. Create a Semantic Kernel agent for the Azure OpenAI assistant
agent = AzureAssistantAgent(
client=client,
definition=definition,
)
# 6. Create a new thread for use with the assistant
# If no thread is provided, a new thread will be
# created and returned with the initial response
thread: AssistantAgentThread = None
try:
for user_input in USER_INPUTS:
print(f"# User: '{user_input}'")
# 7. Invoke the agent for the current thread and print the response
async for response in agent.invoke(messages=user_input, thread=thread):
print(f"# Agent: {response}")
thread = response.thread
finally:
# 9. Clean up the resources
await client.files.delete(file.id)
await client.vector_stores.delete(vector_store.id)
await client.beta.threads.delete(thread.id)
await client.beta.assistants.delete(agent.id)
if __name__ == "__main__":
asyncio.run(main())
@@ -0,0 +1,98 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
from typing import Annotated
from semantic_kernel.agents import AgentRegistry, OpenAIAssistantAgent
from semantic_kernel.functions import kernel_function
"""
The following sample demonstrates how to create an OpenAI Assistant agent that answers
questions about a sample menu using a Semantic Kernel Plugin. The agent is created
using a yaml declarative spec.
"""
# Simulate a conversation with the agent
USER_INPUTS = [
"Hello",
"What is the special soup?",
"How much does that cost?",
"Thank you",
]
# Define the YAML string for the sample
SPEC = """
type: openai_assistant
name: Host
instructions: Respond politely to the user's questions.
model:
id: ${OpenAI:ChatModelId}
tools:
- id: MenuPlugin.get_specials
type: function
- id: MenuPlugin.get_item_price
type: function
"""
# Define a sample plugin for the sample
class MenuPlugin:
"""A sample Menu Plugin used for the concept sample."""
@kernel_function(description="Provides a list of specials from the menu.")
def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
return """
Special Soup: Clam Chowder
Special Salad: Cobb Salad
Special Drink: Chai Tea
"""
@kernel_function(description="Provides the price of the requested menu item.")
def get_item_price(
self, menu_item: Annotated[str, "The name of the menu item."]
) -> Annotated[str, "Returns the price of the menu item."]:
return "$9.99"
async def main():
# 1. Create the client using Azure OpenAI resources and configuration
client = OpenAIAssistantAgent.create_client()
# 2. Create the assistant on the Azure OpenAI service
agent: OpenAIAssistantAgent = await AgentRegistry.create_from_yaml(
SPEC,
plugins=[MenuPlugin()],
client=client,
)
# 3. Create a thread for the agent
# If no thread is provided, a new thread will be
# created and returned with the initial response
thread = None
try:
for user_input in USER_INPUTS:
print(f"# User: {user_input}")
# 4. Invoke the agent for the specified thread for response
async for response in agent.invoke(
messages=user_input,
thread=thread,
):
print(f"# {response.name}: {response}")
thread = response.thread
finally:
# 5. Clean up the resources
await thread.delete() if thread else None
await agent.client.beta.assistants.delete(assistant_id=agent.id)
"""
Sample Output:
# User: Hello
# Agent: Hello! How can I assist you today?
# User: What is the special soup?
# ...
"""
if __name__ == "__main__":
asyncio.run(main())