Python: restructure: Python samples into progressive 01-05 layout (#3862)

* restructure: Python samples into progressive 01-05 layout

- 01-get-started/: 6 numbered steps (hello agent → hosting)
- 02-agents/: all agent concept samples (tools, middleware, providers, etc.)
- 03-workflows/: ALL existing workflow samples preserved as-is
- 04-hosting/: azure-functions, durabletask, a2a
- 05-end-to-end/: demos, evaluation, hosted agents
- Old files moved to _to_delete/ for review
- Added AGENTS.md with structure documentation
- autogen-migration/ and semantic-kernel-migration/ preserved at root

* fix: switch to AzureOpenAI Foundry, fix CI failures

- Switch all 01-get-started samples to AzureOpenAIResponsesClient with
  Azure AI Foundry project endpoint (AZURE_AI_PROJECT_ENDPOINT +
  AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME + AzureCliCredential)
- Add _to_delete/ and 05-end-to-end/ to pyrightconfig.samples.json excludes
- Fix test paths in packages/ that referenced old getting_started/ dirs:
  durabletask conftest + streaming test, azurefunctions conftest,
  devui conftest + capture_messages + openai_sdk_integration
- Fix workflow_as_agent_human_in_the_loop.py import (sibling import)
- Update hosting READMEs and tool comment paths
- Replace root README.md with new structure overview
- Update AGENTS.md to document Azure OpenAI Foundry as default provider

* cleanup: remove _to_delete folder, copy resource files to active dirs

All files in _to_delete/ were either:
- Exact duplicates of files in the new structure (240 files)
- Same file with only comment path updates (100 files)
- One import-fix diff (workflow_as_agent_human_in_the_loop.py)
- One superseded minimal_sample.py

Resource files (sample.pdf, countries.json, employees.pdf, weather.json)
copied to 02-agents/sample_assets/ and 02-agents/resources/ since active
samples reference them.

* fix: address PR review comments, centralize resources, remove root duplicates

- Fix type annotation in 04_memory.py (string union -> proper types)
- Fix old sample paths in observability files
- Fix grammar/spelling in observability samples
- Move sample_assets/ and resources/ to shared/ folder
- Remove 8 duplicate observability files from 02-agents root
- Update resource path references in multimodal_input and provider samples

* fix: update broken links from old getting_started paths to new structure

- Update relative paths in READMEs: getting_started/ → 01-get-started/,
  02-agents/, 03-workflows/, 04-hosting/, 05-end-to-end/
- Fix absolute GitHub URLs in package READMEs
- Fix broken link in ollama package README

* fix: convert absolute GitHub URLs to relative paths for link checker

Absolute URLs to python/samples/ on main branch 404 until PR merges.
Converted to relative paths that linkspector can verify locally.

* fix: update link for handoff sample moved to orchestrations/

* fix: update chatkit-integration README path from demos/ to 05-end-to-end/

* fix: update broken links in orchestrations README to match flat directory structure

python/samples/02-agents/context_providers/mem0/mem0_basic.py

@@ -0,0 +1,82 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import uuid
+
+from agent_framework import tool
+from agent_framework.azure import AzureAIAgentClient
+from agent_framework.mem0 import Mem0Provider
+from azure.identity.aio import AzureCliCredential
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_threads.py.
+@tool(approval_mode="never_require")
+def retrieve_company_report(company_code: str, detailed: bool) -> str:
+    if company_code != "CNTS":
+        raise ValueError("Company code not found")
+    if not detailed:
+        return "CNTS is a company that specializes in technology."
+    return (
+        "CNTS is a company that specializes in technology. "
+        "It had a revenue of $10 million in 2022. It has 100 employees."
+    )
+
+
+async def main() -> None:
+    """Example of memory usage with Mem0 context provider."""
+    print("=== Mem0 Context Provider Example ===")
+
+    # Each record in Mem0 should be associated with agent_id or user_id or application_id or thread_id.
+    # In this example, we associate Mem0 records with user_id.
+    user_id = str(uuid.uuid4())
+
+    # For Azure authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
+    # authentication option.
+    # For Mem0 authentication, set Mem0 API key via "api_key" parameter or MEM0_API_KEY environment variable.
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIAgentClient(credential=credential).as_agent(
+            name="FriendlyAssistant",
+            instructions="You are a friendly assistant.",
+            tools=retrieve_company_report,
+            context_provider=Mem0Provider(user_id=user_id),
+        ) as agent,
+    ):
+        # First ask the agent to retrieve a company report with no previous context.
+        # The agent will not be able to invoke the tool, since it doesn't know
+        # the company code or the report format, so it should ask for clarification.
+        query = "Please retrieve my company report"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+        # Now tell the agent the company code and the report format that you want to use
+        # and it should be able to invoke the tool and return the report.
+        query = "I always work with CNTS and I always want a detailed report format. Please remember and retrieve it."
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Agent: {result}\n")
+
+        # Mem0 processes and indexes memories asynchronously.
+        # Wait for memories to be indexed before querying in a new thread.
+        # In production, consider implementing retry logic or using Mem0's
+        # eventual consistency handling instead of a fixed delay.
+        print("Waiting for memories to be processed...")
+        await asyncio.sleep(12)  # Empirically determined delay for Mem0 indexing
+
+        print("\nRequest within a new thread:")
+        # Create a new thread for the agent.
+        # The new thread has no context of the previous conversation.
+        thread = agent.get_new_thread()
+
+        # Since we have the mem0 component in the thread, the agent should be able to
+        # retrieve the company report without asking for clarification, as it will
+        # be able to remember the user preferences from Mem0 component.
+        query = "Please retrieve my company report"
+        print(f"User: {query}")
+        result = await agent.run(query, thread=thread)
+        print(f"Agent: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())