Skip to content

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

Merged
Eduard van Valkenburg (eavanvalkenburg) merged 9 commits into
microsoft:mainfrom
eavanvalkenburg:restructure/python-samples
Feb 12, 2026
Merged

Python: restructure: Python samples into progressive 01-05 layout#3862
Eduard van Valkenburg (eavanvalkenburg) merged 9 commits into
microsoft:mainfrom
eavanvalkenburg:restructure/python-samples

Conversation

@eavanvalkenburg

@eavanvalkenburgEduard van Valkenburg (eavanvalkenburg) commented Feb 11, 2026

Copy link
Copy Markdown
Member

Summary

Restructures Python samples into a progressive learning layout:

FolderPurposeSamples
01-get-started/Linear tutorial (hello → hosting)6 new files
02-agents/Deep-dive by concept (tools, middleware, providers, etc.)All existing concept samples
03-workflows/Workflow patterns (preserved as-is from upstream)All existing workflow samples
04-hosting/Deployment (Azure Functions, Durable Tasks, A2A)Moved from getting_started
05-end-to-end/Full applications + evaluationMoved from demos

Design Decisions

  • Progressive complexity: 01→05 builds from hello-world to production
  • One concept per file in sections 01-03
  • Default provider: OpenAI Responses via OpenAIResponsesClient
  • Workflows preserved: All existing workflow samples moved with original names/structure
  • Old files in _to_delete/ for reviewer reference — not deleted yet
  • AGENTS.md documents structure for AI/human maintainers

Not in scope

  • .NET samples (separate PR)
  • Workflow restructuring (will be separate)
  • Docs updates (separate PR in docs repo)

Related: docs PR MicrosoftDocs/semantic-kernel-pr#858

CopilotAI review requested due to automatic review settings February 11, 2026 19:09
@markwallace-microsoftMark Wallace (markwallace-microsoft) added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python labels Feb 11, 2026
@github-actionsgithub-actionsBot changed the title restructure: Python samples into progressive 01-05 layoutPython: restructure: Python samples into progressive 01-05 layoutFeb 11, 2026
CopilotAI reviewed Feb 11, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Restructures the Python samples into a progressive “01–05” learning layout and adds/relocates observability and workflow examples to match the new organization.

Changes:

  • Added a new progressive “01-get-started” track with 6 introductory samples and a README.
  • Added/relocated multiple “02-agents/observability” samples covering environment-based, parameter-based, zero-code, and Azure/Foundry tracing setups.
  • Added a workflow telemetry/observability sample under “02-agents”.

Reviewed changes

Copilot reviewed 15 out of 977 changed files in this pull request and generated 13 comments.

Show a summary per file
FileDescription
python/samples/02-agents/workflow_observability.pyNew workflow sample demonstrating OpenTelemetry spans and trace correlation.
python/samples/02-agents/observability/configure_otel_providers_with_parameters.pyNew sample configuring OTEL providers via parameters and custom exporters.
python/samples/02-agents/observability/configure_otel_providers_with_env_var.pyNew sample configuring OTEL providers via environment variables.
python/samples/02-agents/observability/azure_ai_agent_observability.pyNew Azure AI Project-based observability setup sample.
python/samples/02-agents/observability/agent_with_foundry_tracing.pyNew Foundry/App Insights tracing sample with PEP 723 header.
python/samples/02-agents/observability/agent_observability.pyNew agent observability quickstart sample.
python/samples/02-agents/observability/advanced_zero_code.pyNew “zero code” OpenTelemetry auto-instrumentation sample.
python/samples/02-agents/observability/advanced_manual_setup_console_output.pyNew manual OpenTelemetry SDK setup sample (console exporters).
python/samples/01-get-started/README.mdNew index README describing the progressive get-started sequence.
python/samples/01-get-started/06_host_your_agent.pyNew minimal A2A hosting stub sample.
python/samples/01-get-started/05_first_workflow.pyNew first workflow sample chaining executors.
python/samples/01-get-started/04_memory.pyNew context provider “memory” sample.
python/samples/01-get-started/03_multi_turn.pyNew multi-turn thread sample.
python/samples/01-get-started/02_add_tools.pyNew tools sample using @tool.
python/samples/01-get-started/01_hello_agent.pyNew hello-world agent sample (streaming + non-streaming).

Comment threadpython/samples/01-get-started/04_memory.py
Comment threadpython/samples/02-agents/observability/agent_with_foundry_tracing.py Outdated
Comment threadpython/samples/02-agents/observability/advanced_zero_code.py Outdated
Comment threadpython/samples/02-agents/observability/advanced_zero_code.py Outdated
Comment threadpython/samples/02-agents/observability/configure_otel_providers_with_env_var.py Outdated
Comment threadpython/samples/02-agents/observability/azure_ai_agent_observability.py Outdated
Comment threadpython/samples/02-agents/observability/agent_observability.py
Comment threadpython/samples/02-agents/observability/agent_observability.py
Comment threadpython/samples/02-agents/workflow_observability.py Outdated
Comment threadpython/samples/02-agents/workflow_observability.py Outdated
@markwallace-microsoft

Mark Wallace (markwallace-microsoft) commented Feb 11, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

Python Test Coverage

Python Test Coverage Report •
FileStmtsMissCoverMissing
TOTAL21258327784%
report-only-changed-files is enabled. No files were changed during this commit :)

Python Unit Test Overview

TestsSkippedFailuresErrorsTime
4101225 💤0 ❌0 🔥1m 12s ⏱️

moonbox3
Evan Mattson (moonbox3) reviewed Feb 12, 2026
View reviewed changes

@moonbox3Evan Mattson (moonbox3) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I fixed samples, clients and bugs in #3873. We'll need to get those changes in, and then we can pull into this.

@eavanvalkenburg
restructure: Python samples into progressive 01-05 layout
1afe31a
- 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
@eavanvalkenburg
fix: switch to AzureOpenAI Foundry, fix CI failures
3f74a76
- 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
@eavanvalkenburg
cleanup: remove _to_delete folder, copy resource files to active dirs
d83f296
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.
@eavanvalkenburg
fix: address PR review comments, centralize resources, remove root du…
5ad0976
…plicates
- 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
@eavanvalkenburg
fix: update broken links from old getting_started paths to new structure
4c0f311
- 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
@eavanvalkenburg
fix: convert absolute GitHub URLs to relative paths for link checker
c95714e
Absolute URLs to python/samples/ on main branch 404 until PR merges.
Converted to relative paths that linkspector can verify locally.
@eavanvalkenburg
fix: update link for handoff sample moved to orchestrations/
13cbfa4
@eavanvalkenburg
fix: update chatkit-integration README path from demos/ to 05-end-to-…
31f023a
…end/
Merged via the queue into microsoft:main with commit a2856d3Feb 12, 2026
28 of 29 checks passed
@crickmanChris (crickman) mentioned this pull request Feb 17, 2026
Closed
6 tasks
@crickmanChris (crickman) mentioned this pull request Feb 17, 2026
Closed
@eavanvalkenburg
Eduard van Valkenburg (eavanvalkenburg) deleted the restructure/python-samples branch June 30, 2026 09:02
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code reviewCopilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@moonbox3Evan Mattson (moonbox3)moonbox3 approved these changes
@giles17Giles Odigwe (giles17)giles17 approved these changes

Assignees

No one assigned

Labels

documentationUsage: [Issues, PRs], Target: documentation in the code base and learn docspythonUsage: [Issues, PRs], Target: Python

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@eavanvalkenburg@markwallace-microsoft@moonbox3@giles17