Repo sync for protected branch

semantic-kernel/Frameworks/agent/TOC.yml

@@ -6,6 +6,8 @@
   href: chat-completion-agent.md
 - name: OpenAI Assistant Agent
   href: assistant-agent.md
+- name: Azure AI Agent
+  href: azure-ai-agent.md
 - name: Agent Collaboration
   href: agent-chat.md
 - name: Create an Agent from a Template

semantic-kernel/Frameworks/agent/agent-architecture.md

@@ -53,6 +53,7 @@ Agents can either be invoked directly to perform tasks or orchestrated within an
 
 #### Deep Dive:
 
+- [`AzureAIAgent`](./azure-ai-agent.md)
 - [`ChatCompletionAgent`](./chat-completion-agent.md)
 - [`OpenAIAssistantAgent`](./assistant-agent.md)
 
@@ -61,10 +62,23 @@ Agents can either be invoked directly to perform tasks or orchestrated within an
 ## Agent Exensibility
   -->
 
+## Agent Thread
+
+The abstract `AgentThread` class serves as the core abstraction for threads or conversation state.
+It abstracts away the different ways in which convesation state may be managed for different agents.
+
+Stateful agent services often store conversation state in the service, and you can interact with it via an id.
+Other agents may require the entire chat history to be passed to the agent on each invocation, in which
+case the conversation state is managed locally in the application.
+
+Stateful agents typically only work with a matching `AgentThread` implementation, while other types of agents could work with more than one `AgentThread` type.
+For example, `AzureAIAgent` requires a matching `AzureAIAgentThread`.
+This is because the Azure AI Agent service stores conversations in the service, and requires specific service calls to create a thread and update it.
+If a different agent thread type was used with `AzureAIAgent`, no thread would be created in the Azure AI Agent service and invoke calls would fail.
 
 ## Agent Chat
 
-The  [`AgentChat`](./agent-chat.md) class serves as the foundational component that enables agents of any type to engage in a specific conversation. This class provides the essential capabilities for managing agent interactions within a chat environment. Building on this, the [`AgentGroupChat`](./agent-chat.md#creating-an-agentgroupchat) class extends these capabilities by offering a stategy-based container, which allows multiple agents to collaborate across numerous interactions within the same conversation. 
+The  [`AgentChat`](./agent-chat.md) class serves as the foundational component that enables agents of any type to engage in a specific conversation. This class provides the essential capabilities for managing agent interactions within a chat environment. Building on this, the [`AgentGroupChat`](./agent-chat.md#creating-an-agentgroupchat) class extends these capabilities by offering a stategy-based container, which allows multiple agents to collaborate across numerous interactions within the same conversation.
 
 This structure facilitates more complex, multi-agent scenarios where different agents can work together, share information, and dynamically respond to evolving conversations, making it an ideal solution for advanced use cases such as customer support, multi-faceted task management, or collaborative problem-solving environments.
 
@@ -94,7 +108,7 @@ The _Agent Channel_ class enables agents of various types to participate in an [
 
 ::: zone-end
 
-## Agent Alignment with _Semantic Kernel_ Features
+## Agent Alignment with Semantic Kernel Features
 
 The `Agent Framework` is built on the foundational concepts and features that many developers have come to know within the _Semantic Kernel_ ecosystem. These core principles serve as the building blocks for the Agent Framework’s design. By leveraging the familiar structure and capabilities of the _Semantic Kernel_, the Agent Framework extends its functionality to enable more advanced, autonomous agent behaviors, while maintaining consistency with the broader _Semantic Kernel_ architecture. This ensures a smooth transition for developers, allowing them to apply their existing knowledge to create intelligent, adaptable agents within the framework.
 
@@ -103,8 +117,9 @@ The `Agent Framework` is built on the foundational concepts and features that ma
 
 At the heart of the Semantic Kernel ecosystem is the [`Kernel`](../../concepts/kernel.md), which serves as the core object that drives AI operations and interactions. To create any agent within this framework, a _Kernel instance_ is required as it provides the foundational context and capabilities for the agent’s functionality. The `Kernel` acts as the engine for processing instructions, managing state, and invoking the necessary AI services that power the agent's behavior.
 
-The [`ChatCompletionAgent`](./chat-completion-agent.md) and [`OpenAIAssistantAgent`](./assistant-agent.md) articles provide specific details on how to create each type of agent.
- These resources offer step-by-step instructions and highlight the key configurations needed to tailor the agents to different conversational or task-based applications, demonstrating how the Kernel enables dynamic and intelligent agent behaviors across diverse use cases.
+The [`AzureAIAgent`](./azure-ai-agent.md), [`ChatCompletionAgent`](./chat-completion-agent.md) and [`OpenAIAssistantAgent`](./assistant-agent.md) articles provide specific details on how to create each type of agent.
+
+These resources offer step-by-step instructions and highlight the key configurations needed to tailor the agents to different conversational or task-based applications, demonstrating how the Kernel enables dynamic and intelligent agent behaviors across diverse use cases.
 
 #### Related API's:
 

semantic-kernel/Frameworks/agent/agent-chat.md

@@ -24,8 +24,8 @@ Detailed API documentation related to this discussion is available at:
 
 ::: zone pivot="programming-language-python"
 
-- [`agent_chat`](/python/api/semantic-kernel/semantic_kernel.agents.group_chat.agent_chat)
-- [`agent_group_chat`](/python/api/semantic-kernel/semantic_kernel.agents.group_chat.agent_group_chat)
+- [`AgentChat`](/python/api/semantic-kernel/semantic_kernel.agents.group_chat.agent_chat.agentchat)
+- [`AgentGroupChat`](/python/api/semantic-kernel/semantic_kernel.agents.group_chat.agent_group_chat.agentgroupchat)
 
 ::: zone-end
 

semantic-kernel/Frameworks/agent/agent-streaming.md

@@ -58,42 +58,49 @@ The `Agent Framework` supports _streamed_ responses when using [`AgentChat`](./a
 
 ### Streamed response from `ChatCompletionAgent`
 
-When invoking a streamed response from a [`ChatCompletionAgent`](./chat-completion-agent.md), the `ChatHistory` is updated after the full response is received. Although the response is streamed incrementally, the history records only the complete message. This ensures that the `ChatHistory` reflects fully formed responses for consistency.
+When invoking a streamed response from a [`ChatCompletionAgent`](./chat-completion-agent.md), the `ChatHistory` in the `AgentThread` is updated after the full response is received. Although the response is streamed incrementally, the history records only the complete message. This ensures that the `ChatHistory` reflects fully formed responses for consistency.
 
 ::: zone pivot="programming-language-csharp"
 ```csharp
 // Define agent
 ChatCompletionAgent agent = ...;
 
-// Create a ChatHistory object to maintain the conversation state.
-ChatHistory chat = [];
+ChatHistoryAgentThread agentThread = new();
 
-// Add a user message to the conversation
-chat.Add(new ChatMessageContent(AuthorRole.User, "<user input>"));
+// Create a user message
+var message = ChatMessageContent(AuthorRole.User, "<user input>");
 
 // Generate the streamed agent response(s)
-await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(chat))
+await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread))
 {
   // Process streamed response(s)...
 }
+
+// It's also possible to read the messages that were added to the ChatHistoryAgentThread.
+await foreach (ChatMessageContent response in agentThread.GetMessagesAsync())
+{
+  // Process messages...
+}
 ```
 ::: zone-end
 
 ::: zone pivot="programming-language-python"
 ```python
+from semantic_kernel.agents import ChatCompletionAgent, ChatHistoryAgentThread
+
 # Define agent
 agent = ChatCompletionAgent(...)
 
-# Create a ChatHistory object to maintain the conversation state.
-chat = ChatHistory()
-
-# Add a user message to the conversation
-chat.add_message(ChatMessageContent(AuthorRole.USER, "<user input>"))
+# Create a thread object to maintain the conversation state.
+# If no thread is provided one will be created and returned with
+# the initial response.
+thread: ChatHistoryAgentThread = None
 
 # Generate the streamed agent response(s)
-async for response in agent.invoke_stream(chat)
+async for response in agent.invoke_stream(messages="user input", thread=thread)
 {
   # Process streamed response(s)...
+  thread = response.thread
 }
 ```
 ::: zone-end
@@ -106,44 +113,51 @@ async for response in agent.invoke_stream(chat)
 
 ### Streamed response from `OpenAIAssistantAgent`
 
-When invoking a streamed response from an [`OpenAIAssistantAgent`](./assistant-agent.md), an optional `ChatHistory` can be provided to capture the complete messages for further analysis if needed. Since the assistant maintains the conversation state as a remote thread, capturing these messages is not always necessary. The decision to store and analyze the full response depends on the specific requirements of the interaction.
+When invoking a streamed response from an [`OpenAIAssistantAgent`](./assistant-agent.md), the assistant maintains the conversation state as a remote thread. It is possible to read the messages from the remote thread if required.
 
 ::: zone pivot="programming-language-csharp"
 ```csharp
 // Define agent
 OpenAIAssistantAgent agent = ...;
 
 // Create a thread for the agent conversation.
-string threadId = await agent.CreateThreadAsync();
+OpenAIAssistantAgentThread agentThread = new(assistantClient);
 
-// Add a user message to the conversation
-chat.Add(threadId, new ChatMessageContent(AuthorRole.User, "<user input>"));
+// Cerate a user message
+var message = new ChatMessageContent(AuthorRole.User, "<user input>");
 
 // Generate the streamed agent response(s)
-await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(threadId))
+await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread))
 {
   // Process streamed response(s)...
 }
 
+// It's possible to read the messages from the remote thread.
+await foreach (ChatMessageContent response in agentThread.GetMessagesAsync())
+{
+  // Process messages...
+}
+
 // Delete the thread when it is no longer needed
-await agent.DeleteThreadAsync(threadId);
+await agentThread.DeleteAsync();
 ```
 ::: zone-end
 
 ::: zone pivot="programming-language-python"
 ```python
+from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent, OpenAIAssistantAgent
 # Define agent
-agent = OpenAIAssistantAgent(...)
+agent = OpenAIAssistantAgent(...)  # or = AzureAssistantAgent(...)
 
 # Create a thread for the agent conversation.
-thread_id = await agent.create_thread()
-
-# Add user message to the conversation
-await agent.add_chat_message(message="<user input>")
+# If no thread is provided one will be created and returned with
+# the initial response.
+thread: AssistantAgentThread = None
 
 # Generate the streamed agent response(s)
-async for response in agent.invoke_stream(thread_id=thread_id):
+async for response in agent.invoke_stream(messages="user input", thread=thread):
   # Process streamed response(s)...
+  thread = response.thread
 ```
 ::: zone-end
 

semantic-kernel/Frameworks/agent/agent-templates.md

@@ -76,10 +76,8 @@ ChatCompletionAgent agent =
 
 ::: zone pivot="programming-language-python"
 ```python
-kernel = Kernel()
-
 agent = ChatCompletionAgent(
-    kernel=kernel,
+    service=AzureChatCompletion(), # or other supported AI Services
     name="StoryTeller",
     instructions="Tell a story about {{$topic}} that is {{$length}} sentences long.",
     arguments=KernelArguments(topic="Dog", length="2"),
@@ -100,24 +98,34 @@ Templated instructions are especially powerful when working with an [`OpenAIAssi
 ::: zone pivot="programming-language-csharp"
 ```csharp
 // Retrieve an existing assistant definition by identifier
-OpenAIAssistantAgent agent = 
-    await OpenAIAssistantAgent.RetrieveAsync(
-        this.GetClientProvider(),
-        "<stored agent-identifier>",
-        new Kernel(),
-        new KernelArguments()
-        {
-            { "topic", "Dog" },
-            { "length", "3" },
-        });
+AzureOpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri("<your endpoint>"));
+AssistantClient assistantClient = client.GetAssistantClient();
+Assistant assistant = await client.GetAssistantAsync();
+OpenAIAssistantAgent agent = new(assistant, assistantClient, new KernelPromptTemplateFactory(), PromptTemplateConfig.SemanticKernelTemplateFormat)
+{
+    Arguments = new KernelArguments()
+    {
+        { "topic", "Dog" },
+        { "length", "3" },
+    }
+}
 ```
 ::: zone-end
 
 ::: zone pivot="programming-language-python"
 ```python
-agent = await OpenAIAssistantAgent.retrieve(
-    id=<assistant_id>,
-    kernel=Kernel(),
+# Create the client using Azure OpenAI resources and configuration
+client, model = AzureAssistantAgent.setup_resources()
+
+# Retrieve the assistant definition from the server based on the assistant ID
+definition = await client.beta.assistants.retrieve(
+    assistant_id="your-assistant-id",
+)
+
+# Create the AzureAssistantAgent instance using the client and the assistant definition
+agent = AzureAssistantAgent(
+    client=client,
+    definition=definition,
     arguments=KernelArguments(topic="Dog", length="3"),
 )
 ```
@@ -130,10 +138,9 @@ agent = await OpenAIAssistantAgent.retrieve(
 ::: zone-end
 
 
-## Agent Definition from a _Prompt Template_
-
-The same _Prompt Template Config_ used to create a _Kernel Prompt Function_ can also be leveraged to define an agent. This allows for a unified approach in managing both prompts and agents, promoting consistency and reuse across different components. By externalizing agent definitions from the codebase, this method simplifies the management of multiple agents, making them easier to update and maintain without requiring changes to the underlying logic. This separation also enhances flexibility, enabling developers to modify agent behavior or introduce new agents by simply updating the configuration, rather than adjusting the code itself.
+## Agent Definition from a Prompt Template
 
+The same Prompt Template Config used to create a Kernel Prompt Function can also be leveraged to define an agent. This allows for a unified approach in managing both prompts and agents, promoting consistency and reuse across different components. By externalizing agent definitions from the codebase, this method simplifies the management of multiple agents, making them easier to update and maintain without requiring changes to the underlying logic. This separation also enhances flexibility, enabling developers to modify agent behavior or introduce new agents by simply updating the configuration, rather than adjusting the code itself.
 #### YAML Template
 
 ```yaml
@@ -192,7 +199,7 @@ data = yaml.safe_load(generate_story_yaml)
 prompt_template_config = PromptTemplateConfig(**data)
 
 agent = ChatCompletionAgent(
-    kernel=_create_kernel_with_chat_completion(),
+    service=AzureChatCompletion(), # or other supported AI services
     prompt_template_config=prompt_template_config,
     arguments=KernelArguments(topic="Dog", length="3"),
 )
@@ -228,9 +235,6 @@ ChatCompletionAgent agent =
         }
     };
 
-// Create a ChatHistory object to maintain the conversation state.
-ChatHistory chat = [];
-
 KernelArguments overrideArguments =
     new()
     {
@@ -239,7 +243,7 @@ KernelArguments overrideArguments =
     });
 
 // Generate the agent response(s)
-await foreach (ChatMessageContent response in agent.InvokeAsync(chat, overrideArguments))
+await foreach (ChatMessageContent response in agent.InvokeAsync([], options: new() { KernelArguments = overrideArguments }))
 {
   // Process agent response(s)...
 }
@@ -249,10 +253,8 @@ await foreach (ChatMessageContent response in agent.InvokeAsync(chat, overrideAr
 ::: zone pivot="programming-language-python"
 
 ```python
-kernel = Kernel()
-
 agent = ChatCompletionAgent(
-    kernel=kernel,
+    service=AzureChatCompletion(),
     name="StoryTeller",
     instructions="Tell a story about {{$topic}} that is {{$length}} sentences long.",
     arguments=KernelArguments(topic="Dog", length="2"),