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/AGENTS.md

@@ -0,0 +1,116 @@
+# Samples Structure & Design Choices — Python
+
+> This file documents the structure and conventions of the Python samples so that
+> agents (AI or human) can maintain them without rediscovering decisions.
+
+## Directory layout
+
+```
+python/samples/
+├── 01-get-started/          # Progressive tutorial (steps 01–06)
+├── 02-agents/               # Deep-dive concept samples
+│   ├── tools/               # Tool patterns (function, approval, schema, etc.)
+│   ├── middleware/           # One file per middleware concept
+│   ├── conversations/       # Thread, storage, suspend/resume
+│   ├── providers/           # One sub-folder per provider (azure_ai/, openai/, etc.)
+│   ├── context_providers/   # Memory & context injection
+│   ├── orchestrations/      # Multi-agent orchestration patterns
+│   ├── observability/       # Tracing, telemetry
+│   ├── declarative/         # Declarative agent definitions
+│   ├── chat_client/         # Raw chat client usage
+│   ├── mcp/                 # MCP server/client patterns
+│   ├── multimodal_input/    # Image, audio inputs
+│   └── devui/               # DevUI agent/workflow samples
+├── 03-workflows/            # Workflow samples (preserved from upstream)
+│   ├── _start-here/         # Introductory workflow samples
+│   ├── agents/              # Agents in workflows
+│   ├── checkpoint/          # Checkpointing & resume
+│   ├── composition/         # Sub-workflows
+│   ├── control-flow/        # Edges, conditions, loops
+│   ├── declarative/         # YAML-based workflows
+│   ├── human-in-the-loop/   # HITL patterns
+│   ├── observability/       # Workflow telemetry
+│   ├── parallelism/         # Fan-out, map-reduce
+│   ├── state-management/    # State isolation, kwargs
+│   ├── tool-approval/       # Tool approval in workflows
+│   └── visualization/       # Workflow visualization
+├── 04-hosting/              # Deployment & hosting
+│   ├── a2a/                 # Agent-to-Agent protocol
+│   ├── azure-functions/     # Azure Functions samples
+│   └── durabletask/         # Durable task framework
+├── 05-end-to-end/           # Complete applications
+│   ├── chatkit-integration/
+│   ├── evaluation/
+│   ├── hosted_agents/
+│   ├── m365-agent/
+│   ├── purview_agent/
+│   └── workflow_evaluation/
+├── autogen-migration/       # Migration guides (do not restructure)
+├── semantic-kernel-migration/
+└── _to_delete/              # Old samples awaiting review
+```
+
+## Design principles
+
+1. **Progressive complexity**: Sections 01→05 build from "hello world" to
+   production. Within 01-get-started, files are numbered 01–06 and each step
+   adds exactly one concept.
+
+2. **One concept per file** in 01-get-started and flat files in 02-agents/.
+
+3. **Workflows preserved**: 03-workflows/ keeps the upstream folder names
+   and file names intact. Do not rename or restructure workflow samples.
+
+4. **Single-file for 01-03**: Only 04-hosting and 05-end-to-end use multi-file
+   projects with their own README.
+
+## Default provider
+
+All canonical samples (01-get-started) use **Azure OpenAI Responses** via `AzureOpenAIResponsesClient`
+with an Azure AI Foundry project endpoint:
+
+```python
+import os
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+
+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="...", 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)
+
+For authentication, run `az login` before running samples.
+
+## Snippet tags for docs integration
+
+Samples embed named snippet regions for future `:::code` integration:
+
+```python
+# <snippet_name>
+code here
+# </snippet_name>
+```
+
+## Package install
+
+```bash
+pip install agent-framework --pre
+```
+
+The `--pre` flag is needed during preview. `openai` is a core dependency.
+
+## Current API notes
+
+- `Agent` class renamed from `ChatAgent` (use `from agent_framework import Agent`)
+- `Message` class renamed from `ChatMessage` (use `from agent_framework import Message`)
+- `call_next` in middleware takes NO arguments: `await call_next()` (not `await call_next(context)`)
+- Prefer `client.as_agent(...)` over `Agent(client=client, ...)`
+- Tool methods on hosted tools are now functions, not classes (e.g. `hosted_mcp_tool(...)` not `HostedMCPTool(...)`)