initial scaffold and AF code for migration guide

Author: eavanvalkenburg

agent-framework/migration-guide/from-semantic-kernel/index.md

@@ -121,7 +121,7 @@ i.e: OpenAI Assistants Provider
 await thread.DeleteAsync();
 ```
 
-#### Agent Framework 
+#### Agent Framework
 
 > [!NOTE]
 > OpenAI Responses introduced a new conversation model that simplifies how conversations are handled. This simplifies hosted thread management compared to the now deprecated OpenAI Assistants model. For more information see the [OpenAI Assistants migration guide](https://platform.openai.com/docs/assistants/migration).
@@ -150,7 +150,7 @@ In semantic kernel to expose a function as a tool you must:
 KernelFunction function = KernelFunctionFactory.CreateFromMethod(GetWeather);
 KernelPlugin plugin = KernelPluginFactory.CreateFromFunctions("KernelPluginName", [function]);
 Kernel kernel = ... // Create kernel
-kernel.Plugins.Add(plugin); 
+kernel.Plugins.Add(plugin);
 
 ChatCompletionAgent agent = new() { Kernel = kernel, ... };
 ```
@@ -304,4 +304,287 @@ The agent framework supports all the abovementioned services via a single agent
 ::: zone-end
 ::: zone pivot="programming-language-python"
 
+## Key differences
+
+Here is a summary of the key differences between the Semantic Kernel Agent Framework and the Microsoft Agent Framework to help you migrate your code.
+
+### 1. Package and Import Updates
+
+#### Semantic Kernel
+
+Semantic Kernel packages are installed as `semantic-kernel` and imported as `semantic_kernel`. The package also has a number of `extras` that you can install to install the different dependencies for different AI providers and other features.
+
+```python
+from semantic_kernel import Kernel
+from semantic_kernel.agents import ChatCompletionAgent
+```
+
+#### Agent Framework
+
+Agent Framework package is installed as `agent-framework` and imported as `agent_framework`.
+Agent Framework is built up differently, it has a core package `agent-framework-core` that contains the core functionality, and then there are multiple packages that rely on that core package, such as `agent-framework-azure-ai`, `agent-framework-mem0`, `agent-framework-copilotstudio`, etc. When you run `pip install agent-framework` it will install the core package and *all* packages, so that you can get started with all the features quickly. When you are ready to reduce the number of packages because you know what you need, you can install only the packages you need, so for instance if you only plan to use Azure AI Foundry and Mem0 you can install only those two packages: `pip install agent-framework-azure-ai agent-framework-mem0`, `agent-framework-core` is a dependency to those two, so will automatically be installed.
+
+Even though the packages are split up, the imports are all from `agent_framework`, or it's modules. So for instance to import the client for Azure AI Foundry you would do:
+
+```python
+from agent_framework.azure import AzureAIAgentClient
+```
+
+Many of the most commonly used types are imported directly from `agent_framework`:
+
+```python
+from agent_framework import ChatMessage, ChatAgent
+```
+
+### 2. Agent Type Consolidation
+
+#### Semantic Kernel
+Semantic Kernel provides specific agent classes for various services, e.g. ChatCompletionAgent, AzureAIAgent, OpenAIAssistantAgent, etc. See [Agent types in Semantic Kernel](/semantic-kernel/agents/agent-types).
+
+#### Agent Framework
+In Agent Framework the majority of agents are built using the `ChatAgent` which can be used with all the `ChatClient` based services, such as Azure AI Foundry, OpenAI ChatCompletion and OpenAI Responses. We currently have two other agents, `CopilotStudioAgent` for use with Copilot Studio and `A2AAgent` for use with A2A.
+
+All the built-in agents are based on the BaseAgent (`from agent_framework import BaseAgent`). And all agents are consistent with the `AgentProtocol` (`from agent_framework import AgentProtocol`) interface.
+
+### 2. Agent Creation Simplification
+
+#### Semantic Kernel
+
+Every agent in Semantic Kernel depends on a `Kernel` instance and will have
+an empty `Kernel` if not provided.
+
+```python
+# TODO: Add Semantic Kernel example
+```
+
+
+#### Agent Framework
+
+Agent creation in Agent Framework can be done in two ways, directly:
+
+```python
+from agent_framework.azure import AzureAIAgentClient
+from agent_framework import ChatMessage, ChatAgent
+
+agent = ChatAgent(chat_client=AzureAIAgentClient(credential=AzureCliCredential()), instructions="You are a helpful assistant")
+```
+or, with the convenience methods provided by chat clients:
+
+```python
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(instructions="You are a helpful assistant")
+```
+
+The direct method, exposes all possible parameters you can set for your agent, while the convenience method has a subset, you can still pass in the same set of parameters, because internally we call the direct method.
+
+### 3. Agent Thread Creation
+
+#### Semantic Kernel
+
+The caller has to know the thread type and create it manually.
+
+```python
+# TODO: Add thread creation examples
+```
+
+#### Agent Framework
+
+The agent can be asked to create a new thread for you.
+
+```python
+agent = ...
+thread = agent.get_new_thread()
+```
+
+a thread is then created in one of three ways:
+1. if the agent has a thread_id (or conversation_id or something similar) set, it will create a thread in the underlying service with that id.
+    Once a thread has a `service_thread_id`, you can no longer use it to store messages in memory.
+    And this only applies to agents that have a service-side thread concept. such as Azure AI Foundry Agents and OpenAI Assistants.
+2. if the agent has a `chat_message_store_factory` set, it will use that factory to create a message store and use that to create an in-memory thread.
+    It can then no longer be used with a agent with the `store` parameter set to `True`.
+3. if neither of the above is set, we consider it `uninitialized` and depending on how it is used, it will either become a in-memory thread or a service thread.
+
+#### Agent Framework
+
+> [!NOTE]
+> OpenAI Responses introduced a new conversation model that simplifies how conversations are handled. This simplifies hosted thread management compared to the now deprecated OpenAI Assistants model. For more information see the [OpenAI Assistants migration guide](https://platform.openai.com/docs/assistants/migration).
+
+Agent Framework doesn't have a thread deletion API in the `AgentThread` type as not all providers support hosted threads or thread deletion and this will become more common as more providers shift to responses based architectures.
+
+If you require thread deletion and the provider allows this, the caller **should** keep track of the created threads and delete them later when necessary via the provider's sdk.
+
+i.e: OpenAI Assistants Provider
+```python
+# TODO: Add thread deletion via provider SDK example
+```
+
+### 5. Tool Registration
+
+#### Semantic Kernel
+
+In semantic kernel to expose a function as a tool you must:
+
+1. Decorate the function with a `@kernel_function` decorator.
+2. Have a `Plugin` class or use the kernel plugin factory to wrap the function.
+3. Have a `Kernel` to add your plugin to.
+4. Pass the `Kernel` to the agent.
+
+```python
+# TODO: Add SK tool registration example
+```
+
+#### Agent Framework
+
+In agent framework in a single call you can register tools directly in the agent creation process. But we no longer have the concept of a plugin, to wrap multiple functions, but you can still do that if you want to.
+
+The simplest way to create a tool is just to create a python function:
+
+```python
+def get_weather(location: str) -> str:
+    """Get the weather for a given location."""
+    return f"The weather in {location} is sunny."
+
+agent = chat_client.create_agent(tools=get_weather)
+```
+> Note: the `tools` parameter is present on both the agent creation, the `run` and `run_stream` methods, as well as the `get_response` and `get_streaming_response` methods, it allows you to supply tools both as a list or a single function.
+
+The name of the function will then become the name of the tool, and the docstring will become the description of the tool, you can also add a description to the parameters:
+
+```python
+from typing import Annotated
+
+def get_weather(location: Annotated[str, "The location to get the weather for."]) -> str:
+    """Get the weather for a given location."""
+    return f"The weather in {location} is sunny."
+```
+
+Finally, you can use the decorator to further customize the name and description of the tool:
+
+```python
+from typing import Annotated
+from agent_framework import ai_function
+
+@ai_function(name="weather_tool", description="Retrieves weather information for any location")
+def get_weather(location: Annotated[str, "The location to get the weather for."])
+    """Get the weather for a given location."""
+    return f"The weather in {location} is sunny."
+```
+
+This also works when you create a class with multiple tools as methods.
+
+When creating the agent, we can now provide the function tool to the agent, by passing it to the `tools` parameter.
+
+```python
+class Plugin:
+
+    def __init__(self, initial_state: str):
+        self.state: list[str] = [initial_state]
+
+    def get_weather(self, location: Annotated[str, "The location to get the weather for."]) -> str:
+        """Get the weather for a given location."""
+        self.state.append(f"Requested weather for {location}. ")
+        return f"The weather in {location} is sunny."
+
+    def get_weather_details(self, location: Annotated[str, "The location to get the weather details for."]) -> str:
+        """Get detailed weather for a given location."""
+        self.state.append(f"Requested detailed weather for {location}. ")
+        return f"The weather in {location} is sunny with a high of 25°C and a low of 15°C."
+
+plugin = Plugin("Initial state")
+agent = chat_client.create_agent(tools=[plugin.get_weather, plugin.get_weather_details])
+
+... # use the agent
+
+print("Plugin state:", plugin.state)
+```
+> Note: the functions within the class can also be decorated with `@ai_function` to customize the name and description of the tools.
+
+This mechanism is also useful for tools that need additional input that cannot be supplied by the LLM, such as connections, secrets, etc.
+
+### 6. Agent Non-Streaming Invocation
+
+Key differences can be seen in the method names from `invoke` to `run`, return types (e.g. `AgentRunResponse`) and parameters.
+
+#### Semantic Kernel
+
+The Non-Streaming uses an async iterator pattern for returning multiple agent messages.
+
+```python
+# TODO: Add SK non-streaming invocation example
+```
+
+#### Agent Framework
+
+The Non-Streaming returns a single `AgentRunResponse` with the agent response that can contain multiple messages.
+The text result of the run is available in `response.text` or `str(AgentRunResponse)`.
+All messages created as part of the response are returned in the `response.messages` list.
+This may include tool call messages, function results, reasoning updates and final results.
+
+```python
+agent = ...
+
+response = await agent.run(user_input, thread)
+print("Agent response:", response.text)
+
+```
+
+### 7. Agent Streaming Invocation
+
+Key differences in the method names from `invoke` to `run_stream`, return types (`AgentRunResponseUpdate`) and parameters.
+
+#### Semantic Kernel
+
+```python
+# TODO: Add SK streaming invocation example
+```
+
+#### Agent Framework
+
+Similar streaming API pattern with the key difference being that it returns `AgentRunResponseUpdate` objects including more agent related information per update.
+
+All contents produced by any service underlying the Agent are returned. The textual result of the agent is available by concatenating the `response.text` values. And you can gather the updates up to a full response if needed.
+
+```python
+from agent_framework import AgentRunResponse
+agent = ...
+updates = []
+async for update in agent.run_stream(user_input, thread):
+    updates.append(update)
+    print(update.text)  # Update is str() friendly
+
+full_response = AgentRunResponse.from_agent_run_response_updates(updates)
+print("Full agent response:", full_response.text)
+```
+
+You can even do that directly:
+
+```python
+from agent_framework import AgentRunResponse
+agent = ...
+full_response = AgentRunResponse.from_agent_response_generator(agent.run_stream(user_input, thread))
+print("Full agent response:", full_response.text)
+```
+
+
+### 9. Options Configuration
+
+**Problem**: Complex options setup in SK
+
+```python
+# TODO: Add SK options configuration example
+```
+
+**Solution**: Simplified options in AF
+
+In agent framework, we allow the passing of all parameters directly to the relevant methods, so that you do not have to import anything extra, or create any options objects, unless you want to. Internally we use a `ChatOptions` object, that you can also create and pass in if you want to. This is also created in a `ChatAgent` to hold the options and can be overridden per call.
+
+```python
+agent = ...
+
+response = await agent.run(user_input, thread, max_tokens=1000, frequency_penalty=0.5)
+```
+
+> Note: The above is specific to a `ChatAgent`, because other agents may have different options, they should all accepts `messages` as a parameter, since that is defined in the `AgentProtocol`.
+
 ::: zone-end