ADR - Agent Framework (microsoft#5922)

### Motivation and Context
<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->

This ADR captures agent concepts as the project solidifies. Will be
updated as needed to remain _in sync_.

While the code exists as _ground-truth_, capturing the following
additional vectors can aid with translation to _Python_ and _Java_:

- Conceptual overview
- Objectives / requirements
- Analysis
- Intent

### Description
<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

This merges the initial _Agent_ ADR with the current direction with the
goal of capturing project essence for translation into _Python_ and
_Java_

### Contribution Checklist
<!-- Before submitting this PR, please make sure: -->

- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [x] I didn't break anyone 😄

---------

Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>

docs/decisions/diagrams/agent-abstractions.mmd

@@ -0,0 +1,64 @@
+classDiagram
+
+    Agent --> AgentChannel
+    class Agent {
+        <<Abstract>>        
+        +String Id
+        +String? Description
+        +String? Name
+        ~#IEnumerable~String~ GetChannelKeys()*
+        ~#Task~AgentChannel~ CreateChannelAsync()*
+    }
+
+    class AgentChannel {
+        <<Abstract>>
+        ~#IAsyncEnumerable~ChatMessageContent~ InvokeAsync(Agent agent)*
+        ~#IAsyncEnumerable~ChatMessageContent~ GetHistoryAsync()*
+        ~#Task ReceiveAsync(IReadOnlyList~ChatMessageContent~ history)*
+    }
+
+    Agent <|-- KernelAgent
+    class KernelAgent {
+        <<Abstract>>
+        +String? Instructions
+        +Kernel Kernel
+    }
+
+    class IChatHistoryHandler {
+        <<Interface>>
+        +IAsyncEnumerable~ChatMessageContent~ InvokeAsync(IReadOnlyList~ChatMessageContent~ history, )*
+    }
+
+    KernelAgent <|-- ChatHistoryKernelAgent
+    IChatHistoryHandler <|-- ChatHistoryKernelAgent
+    ChatHistoryKernelAgent --> ChatHistoryChannel
+    class ChatHistoryKernelAgent {
+        #IEnumerable~String GetChannelKeys()
+        #Task~AgentChannel~ CreateChannelAsync()
+        +IAsyncEnumerable~ChatMessageContent~ InvokeAsync(IReadOnlyList~ChatMessageContent~ history, )*
+    }
+
+    AgentChannel <|-- ChatHistoryChannel
+    class ChatHistoryChannel {
+        <<Final>>
+        -ChatHistory _history
+        ~#IAsyncEnumerable~ChatMessageContent~ InvokeAsync(Agent agent)
+        ~#IAsyncEnumerable~ChatMessageContent~ GetHistoryAsync()
+        ~#Task ReceiveAsync(IReadOnlyList~ChatMessageContent~ history)
+    }
+
+    AgentChat o-- AgentChannel
+    class AgentChat {
+        <<Abstract>>
+        #ChatHistory History
+        +bool IsActive
+        +ILoggerFactory LoggerFactory;
+        #ILogger Logger;
+        +void AddChatMessage(ChatMessageContent message)
+        +void AddChatMessages(IReadOnlyList~ChatMessageContent~ messages)
+        +IAsyncEnumerable~ChatMessageContent~ GetChatMessagesAsync()
+        +IAsyncEnumerable~ChatMessageContent~ GetChatMessagesAsync(Agent? agent)
+        +IAsyncEnumerable~ChatMessageContent~ InvokeAgentAsync()*
+        #IAsyncEnumerable~ChatMessageContent~ InvokeAgentAsync(Agent agent)
+    }
+

docs/decisions/diagrams/agent-aggregator.mmd

@@ -0,0 +1,28 @@
+classDiagram
+
+    Agent
+    AgentChannel
+
+    AggregatorAgent --> AggregatorMode
+    class AggregatorMode {
+        <<Enum>>
+        Flat
+        Nested
+    }
+
+    Agent <|-- AggregatorAgent
+    AggregatorAgent --> AggregatorChannel
+    class AggregatorAgent {
+        <<Final>>
+        +AggregatorMode Mode
+        #IEnumerable~String~ GetChannelKeys()
+        #Task~AgentChannel~ CreateChannelAsync()
+    }
+
+    AgentChannel <|-- AggregatorChannel
+    class AggregatorChannel {
+        <<Final>>
+        ~#IAsyncEnumerable~ChatMessageContent~ InvokeAsync(AggregatorAgent agent)
+        ~#IAsyncEnumerable~ChatMessageContent~ GetHistoryAsync()
+        ~#Task ReceiveAsync(IReadOnlyList~ChatMessageContent~ history)
+    }

docs/decisions/diagrams/agent-assistant.mmd

@@ -0,0 +1,43 @@
+classDiagram
+
+    Agent
+    AgentChannel
+    Agent <|-- KernelAgent
+
+    KernelAgent <|-- OpenAIAssistantAgent
+    OpenAIAssistantAgent --> OpenAIAssistantChannel
+    OpenAIAssistantAgent --> OpenAIAssistantDefinition  
+    class OpenAIAssistantAgent {
+        <<Final>>
+        +bool IsDeleted
+        +IReadOnlyList~string~ FileIds
+        ~IReadOnlyList~ToolDefinition~ Tools
+        +IReadOnlyDictionary~string,string~ Metadata
+        +Task~OpenAIAssistantAgent~ CreateAsync(Kernel kernel, OpenAIAssistantConfiguration config, OpenAIAssistantDefinition definition)$
+        +IAsyncEnumerable~OpenAIAssistantDefinition~ ListDefinitionsAsync(OpenAIAssistantConfiguration config,  maxResults = 100, string? lastId = null)$
+        +Task~OpenAIAssistantAgent~ RetrieveAsync(Kernel kernel, OpenAIAssistantConfiguration config, string id)$
+        +Task DeleteAsync()
+        #IEnumerable~String~ GetChannelKeys()
+        #Task~AgentChannel~ CreateChannelAsync()
+    }
+
+    AgentChannel <|-- OpenAIAssistantChannel
+    class OpenAIAssistantChannel {
+        <<Final>>
+        -string _threadId
+        #IAsyncEnumerable~ChatMessageContent~ InvokeAsync(OpenAIAssistantAgent agent)
+        #IAsyncEnumerable~ChatMessageContent~ GetHistoryAsync()
+        #Task ReceiveAsync(IReadOnlyList~ChatMessageContent~ history)
+    }
+
+    class OpenAIAssistantDefinition {
+        +string? ModelId
+        +string? Description
+        +string? Id
+        +string? Instructions
+        +string? Name
+        +bool EnableCodeInterpreter
+        +bool EnableRetrieval
+        +IEnumerable<string>? FileIds
+        +IReadOnlyDictionary<string, string>? Metadata
+    }

docs/decisions/diagrams/agent-chatcompletion.mmd

@@ -0,0 +1,16 @@
+classDiagram
+
+    Agent
+    Agent <|-- KernelAgent
+    KernelAgent <|-- ChatHistoryKernelAgent
+    IChatHistoryHandler <|-- ChatHistoryKernelAgent
+    ChatHistoryKernelAgent --> ChatHistoryChannel
+    AgentChannel
+    AgentChannel <|-- ChatHistoryChannel
+
+    ChatHistoryKernelAgent <|-- ChatCompletionAgent
+    class ChatCompletionAgent {
+        <<Final>>
+        +PromptExecutionSettings? ExecutionSettings
+        +IAsyncEnumerable~ChatMessageContent~ InvokeAsync(IReadOnlyList~ChatMessageContent~ history, ILogger logger)
+    }

docs/decisions/diagrams/agent-design.mmd

@@ -0,0 +1,27 @@
+classDiagram
+
+    Agent --> AgentChannel
+    class Agent {
+        <<Abstract>>        
+    }
+
+    Agent <|-- KernelAgent
+    class KernelAgent {
+        <<Abstract>>
+    }
+
+    class AgentChannel {
+        <<Abstract>>
+    }
+
+    AgentChat o-- AgentChannel
+    class AgentChat {
+        <<Abstract>>
+    }
+
+    AgentChat <|-- AgentGroupChat
+    AgentGroupChat o-- Agent
+    AgentGroupChat --> AgentGroupChatSettings
+    class AgentGroupChat {
+        <<Final>>
+    }

docs/decisions/diagrams/agent-groupchat.mmd

@@ -0,0 +1,43 @@
+classDiagram
+
+    Agent
+    AgentChannel
+    AgentChat
+
+    AgentChat <|-- AgentGroupChat
+    AgentGroupChat o-- Agent
+    AgentGroupChat --> AgentGroupChatSettings
+    class AgentGroupChat {
+        <<Final>>
+        +IReadOnlyList~Agent~ Agents
+        +AgentGroupChatSettings ExecutionSettings
+        +bool IsComplete
+        +void AddAgent(Agent agent)
+        +IAsyncEnumerable~ChatMessageContent~ InvokeAgentAsync()
+        +IAsyncEnumerable~ChatMessageContent~ InvokeAgentAsync(Agent agent)
+        +IAsyncEnumerable~ChatMessageContent~ InvokeAgentAsync(Agent agent, bool isJoining)
+    }
+
+    AgentGroupChatSettings --> SelectionStrategy
+    AgentGroupChatSettings --> TerminationStrategy
+    class AgentGroupChatSettings {
+        <<Final>>
+        +SelectionStrategy SelectionStrategy
+        +TerminationStrategy TerminationStrategy
+    }
+
+    class SelectionStrategy {
+        <<Abstract>>
+        #ILogger Logger
+        +Task~Agent~ NextAsync(IReadOnlyList~Agent~ agents, IReadOnlyList~ChatMessageContent~ history)*
+    }    
+
+    class TerminationStrategy {
+        <<Abstract>>
+        +bool AutomaticReset
+        +int MaximumIterations
+        +IReadOnlyList~Agent~? Agents
+        #ILogger Logger
+        +Task~bool~ ShouldTerminateAsync(Agent agent, IReadOnlyList~ChatMessageContent~ history)
+        #Task~bool~ ShouldAgentTerminateAsync(Agent agent, IReadOnlyList~ChatMessageContent~ history)*
+    }