restructure: rebase Python samples on upstream/main with numbered folder layout

- Rebase on upstream/main to incorporate latest content updates
  (AzureOpenAIResponsesClient adoption, orchestration reorganization,
   workflow/orchestration bug fixes)
- Move files from upstream structure into numbered folders:
  getting_started/agents/ -> 02-agents/providers/
  getting_started/workflows/ -> 03-workflows/
  getting_started/orchestrations/ -> 03-workflows/orchestrations/
  getting_started/azure_functions/ -> 04-hosting/azure_functions/
  getting_started/durabletask/ -> 04-hosting/durabletask/
  concepts/ -> 02-agents/
  demos/ -> 05-end-to-end/
- Update all internal path references (115+ files)
- Preserve 01-get-started custom tutorial files
- Keep a2a hosting samples

Author: eavanvalkenburg

python/samples/01-get-started/01_hello_agent.py

@@ -0,0 +1,53 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+
+"""
+Hello Agent — Simplest possible agent
+
+This sample creates a minimal agent using AzureOpenAIResponsesClient via an
+Azure AI Foundry project endpoint, and runs it in both non-streaming and streaming modes.
+
+Environment variables:
+  AZURE_AI_PROJECT_ENDPOINT        — Your Azure AI Foundry project endpoint
+  AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME — Model deployment name (e.g. gpt-4o)
+"""
+
+
+async def main() -> None:
+    # <create_agent>
+    credential = AzureCliCredential()
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"],
+        credential=credential,
+    )
+
+    agent = client.as_agent(
+        name="HelloAgent",
+        instructions="You are a friendly assistant. Keep your answers brief.",
+    )
+    # </create_agent>
+
+    # <run_agent>
+    # Non-streaming: get the complete response at once
+    result = await agent.run("What is the capital of France?")
+    print(f"Agent: {result}")
+    # </run_agent>
+
+    # <run_agent_streaming>
+    # Streaming: receive tokens as they are generated
+    print("Agent (streaming): ", end="", flush=True)
+    async for chunk in agent.run("Tell me a one-sentence fun fact.", stream=True):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print()
+    # </run_agent_streaming>
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/01-get-started/02_add_tools.py

@@ -0,0 +1,61 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from random import randint
+from typing import Annotated
+
+from agent_framework import tool
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+"""
+Add Tools — Give your agent a function tool
+
+This sample shows how to define a function tool with the @tool decorator
+and wire it into an agent so the model can call it.
+
+Environment variables:
+  AZURE_AI_PROJECT_ENDPOINT        — Your Azure AI Foundry project endpoint
+  AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME — Model deployment name (e.g. gpt-4o)
+"""
+
+
+# <define_tool>
+# NOTE: approval_mode="never_require" is for sample brevity.
+# Use "always_require" in production for user confirmation before tool execution.
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+# </define_tool>
+
+
+async def main() -> None:
+    credential = AzureCliCredential()
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"],
+        credential=credential,
+    )
+
+    # <create_agent_with_tools>
+    agent = client.as_agent(
+        name="WeatherAgent",
+        instructions="You are a helpful weather agent. Use the get_weather tool to answer questions.",
+        tools=get_weather,
+    )
+    # </create_agent_with_tools>
+
+    # <run_agent>
+    result = await agent.run("What's the weather like in Seattle?")
+    print(f"Agent: {result}")
+    # </run_agent>
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/01-get-started/03_multi_turn.py

@@ -0,0 +1,51 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+
+"""
+Multi-Turn Conversations — Use AgentThread to maintain context
+
+This sample shows how to keep conversation history across multiple calls
+by reusing the same thread object.
+
+Environment variables:
+  AZURE_AI_PROJECT_ENDPOINT        — Your Azure AI Foundry project endpoint
+  AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME — Model deployment name (e.g. gpt-4o)
+"""
+
+
+async def main() -> None:
+    # <create_agent>
+    credential = AzureCliCredential()
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"],
+        credential=credential,
+    )
+
+    agent = client.as_agent(
+        name="ConversationAgent",
+        instructions="You are a friendly assistant. Keep your answers brief.",
+    )
+    # </create_agent>
+
+    # <multi_turn>
+    # Create a thread to maintain conversation history
+    thread = agent.get_new_thread()
+
+    # First turn
+    result = await agent.run("My name is Alice and I love hiking.", thread=thread)
+    print(f"Agent: {result}\n")
+
+    # Second turn — the agent should remember the user's name and hobby
+    result = await agent.run("What do you remember about me?", thread=thread)
+    print(f"Agent: {result}")
+    # </multi_turn>
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/01-get-started/04_memory.py

@@ -0,0 +1,91 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from collections.abc import MutableSequence
+from typing import Any
+
+from agent_framework import Context, ContextProvider, Message
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+
+"""
+Agent Memory with Context Providers
+
+Context providers let you inject dynamic instructions and context into each
+agent invocation. This sample defines a simple provider that tracks the user's
+name and enriches every request with personalization instructions.
+
+Environment variables:
+  AZURE_AI_PROJECT_ENDPOINT        — Your Azure AI Foundry project endpoint
+  AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME — Model deployment name (e.g. gpt-4o)
+"""
+
+
+# <context_provider>
+class UserNameProvider(ContextProvider):
+    """A simple context provider that remembers the user's name."""
+
+    def __init__(self) -> None:
+        self.user_name: str | None = None
+
+    async def invoking(self, messages: Message | MutableSequence[Message], **kwargs: Any) -> Context:
+        """Called before each agent invocation — add extra instructions."""
+        if self.user_name:
+            return Context(instructions=f"The user's name is {self.user_name}. Always address them by name.")
+        return Context(instructions="You don't know the user's name yet. Ask for it politely.")
+
+    async def invoked(
+        self,
+        request_messages: Message | list[Message] | None = None,
+        response_messages: "Message | list[Message] | None" = None,
+        invoke_exception: Exception | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Called after each agent invocation — extract information."""
+        msgs = [request_messages] if isinstance(request_messages, Message) else list(request_messages or [])
+        for msg in msgs:
+            text = msg.text if hasattr(msg, "text") else ""
+            if isinstance(text, str) and "my name is" in text.lower():
+                # Simple extraction — production code should use structured extraction
+                self.user_name = text.lower().split("my name is")[-1].strip().split()[0].capitalize()
+# </context_provider>
+
+
+async def main() -> None:
+    # <create_agent>
+    credential = AzureCliCredential()
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"],
+        credential=credential,
+    )
+
+    memory = UserNameProvider()
+
+    agent = client.as_agent(
+        name="MemoryAgent",
+        instructions="You are a friendly assistant.",
+        context_provider=memory,
+    )
+    # </create_agent>
+
+    thread = agent.get_new_thread()
+
+    # The provider doesn't know the user yet — it will ask for a name
+    result = await agent.run("Hello! What's the square root of 9?", thread=thread)
+    print(f"Agent: {result}\n")
+
+    # Now provide the name — the provider extracts and stores it
+    result = await agent.run("My name is Alice", thread=thread)
+    print(f"Agent: {result}\n")
+
+    # Subsequent calls are personalized
+    result = await agent.run("What is 2 + 2?", thread=thread)
+    print(f"Agent: {result}\n")
+
+    print(f"[Memory] Stored user name: {memory.user_name}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/01-get-started/05_first_workflow.py

@@ -0,0 +1,72 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    Executor,
+    WorkflowBuilder,
+    WorkflowContext,
+    executor,
+    handler,
+)
+from typing_extensions import Never
+
+"""
+First Workflow — Chain executors with edges
+
+This sample builds a minimal workflow with two steps:
+1. Convert text to uppercase (class-based executor)
+2. Reverse the text (function-based executor)
+
+No external services are required.
+"""
+
+
+# <create_workflow>
+# Step 1: A class-based executor that converts text to uppercase
+class UpperCase(Executor):
+    def __init__(self, id: str):
+        super().__init__(id=id)
+
+    @handler
+    async def to_upper_case(self, text: str, ctx: WorkflowContext[str]) -> None:
+        """Convert input to uppercase and forward to the next node."""
+        await ctx.send_message(text.upper())
+
+
+# Step 2: A function-based executor that reverses the string and yields output
+@executor(id="reverse_text")
+async def reverse_text(text: str, ctx: WorkflowContext[Never, str]) -> None:
+    """Reverse the string and yield the final workflow output."""
+    await ctx.yield_output(text[::-1])
+
+
+def create_workflow():
+    """Build the workflow: UpperCase → reverse_text."""
+    upper = UpperCase(id="upper_case")
+    return (
+        WorkflowBuilder(start_executor=upper)
+        .add_edge(upper, reverse_text)
+        .build()
+    )
+# </create_workflow>
+
+
+async def main() -> None:
+    # <run_workflow>
+    workflow = create_workflow()
+
+    events = await workflow.run("hello world")
+    print(f"Output: {events.get_outputs()}")
+    print(f"Final state: {events.get_final_state()}")
+    # </run_workflow>
+
+    """
+    Expected output:
+      Output: ['DLROW OLLEH']
+      Final state: WorkflowRunState.IDLE
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/01-get-started/06_host_your_agent.py

@@ -0,0 +1,57 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Host Your Agent — Azure Functions (Durable) hosting
+
+This sample shows how to host an agent inside Azure Functions using the
+Durable Task extension. AgentFunctionApp wraps your agent behind HTTP
+endpoints that Azure Functions exposes automatically.
+
+Prerequisites:
+  pip install agent-framework-azurefunctions --pre
+  Azure Functions Core Tools 4.x (for local development)
+  Azurite storage emulator (for local development)
+
+Environment variables:
+  AZURE_OPENAI_ENDPOINT              — Your Azure OpenAI endpoint
+  AZURE_OPENAI_CHAT_DEPLOYMENT_NAME  — Model deployment name (e.g. gpt-4o)
+
+For full Azure Functions samples with host.json, local.settings.json, and
+multi-agent orchestrations, see samples/04-hosting/azure_functions/.
+"""
+
+from typing import Any
+
+from agent_framework.azure import AgentFunctionApp, AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+
+# <create_agent>
+def _create_agent() -> Any:
+    """Create a hosted agent backed by Azure OpenAI."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        name="HostedAgent",
+        instructions="You are a helpful assistant hosted in Azure Functions.",
+    )
+# </create_agent>
+
+
+# <host_agent>
+# AgentFunctionApp registers your agent with Azure Functions and exposes
+# HTTP endpoints (e.g. POST /api/agents/HostedAgent/run) via the Durable
+# Task extension.
+app = AgentFunctionApp(agents=[_create_agent()])
+# </host_agent>
+
+"""
+To run locally:
+  1. Start the Azurite storage emulator
+  2. Copy local.settings.json.template to local.settings.json and fill in values
+  3. Run: func start
+
+Then invoke:
+  POST http://localhost:7071/api/agents/HostedAgent/run
+  Content-Type: text/plain
+
+  Hello! What can you do?
+"""