Eduard van Valkenburg
d08200d00e
* Bump Python package versions for 1.12.0 release Bump packages represented in the 1.12.0 changelog, promote Foundry Hosting, Azure Content Understanding, Gemini, Mistral, Monty, and Tools to beta, and apply the requested beta cohort date stamp. Root and core move to 1.12.0, released and RC packages use their selected increments, alpha packages including Hosting MCP use the 260721 stamp, and core floors are raised only for proven consumers. Copilot-Session: 2dd9980a-b869-4c16-8642-75b7a6d6ebdf * fix version in readme * Add Responses conversation ID changes to release notes Include the breaking Hosting Responses conversation ID helper changes from #7234 in the Python 1.12.0 changelog. Copilot-Session: 2dd9980a-b869-4c16-8642-75b7a6d6ebdf
166 lines
6.6 KiB
Markdown
166 lines
6.6 KiB
Markdown
# 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
|
||
│ ├── af-hosting/ # Native Responses and Telegram hosting
|
||
│ ├── 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.
|
||
|
||
5. **Self-contained alternatives**: When a sample offers alternative entry
|
||
points (for example polling and webhook hosting), keep each entry point
|
||
self-contained. Do not extract a shared helper module solely to remove
|
||
duplication between sample variants.
|
||
|
||
## Default provider
|
||
|
||
All canonical samples (01-get-started) use **Microsoft Foundry project-backed chat** via `FoundryChatClient`
|
||
with a Microsoft Foundry project endpoint:
|
||
|
||
```python
|
||
import os
|
||
from agent_framework import Agent
|
||
from agent_framework.foundry import FoundryChatClient
|
||
from azure.identity import AzureCliCredential
|
||
|
||
credential = AzureCliCredential()
|
||
client = FoundryChatClient(
|
||
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
|
||
model=os.environ["FOUNDRY_MODEL"],
|
||
credential=credential,
|
||
)
|
||
agent = Agent(client=client, name="...", instructions="...")
|
||
```
|
||
|
||
Environment variables:
|
||
- `FOUNDRY_PROJECT_ENDPOINT` — Your Microsoft Foundry project endpoint
|
||
- `FOUNDRY_MODEL` — 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-foundry
|
||
```
|
||
|
||
Install only the specific Agent Framework distributions a sample uses; do not recommend the
|
||
`agent-framework` meta-package. Include `--pre` when any required distribution is prerelease.
|
||
For example, a Monty agent backed by Foundry uses:
|
||
|
||
```bash
|
||
pip install agent-framework-monty agent-framework-foundry --pre
|
||
```
|
||
|
||
## File structure
|
||
|
||
Every sample file follows this order:
|
||
|
||
1. PEP 723 inline script metadata (if external dependencies are needed)
|
||
2. Copyright header: `# Copyright (c) Microsoft. All rights reserved.`
|
||
3. Required imports
|
||
4. Module docstring explaining the purpose and key components
|
||
5. Helper functions
|
||
6. Main function(s) demonstrating functionality
|
||
7. Entry point: `if __name__ == "__main__": asyncio.run(main())`
|
||
|
||
Use PEP 723 inline script metadata for external sample-only dependencies; do not add sample-only dependencies to
|
||
the root `pyproject.toml` dev group.
|
||
PEP 723 dependencies must list the minimal specific Agent Framework distributions used by the script (for example,
|
||
`agent-framework-core`, `agent-framework-foundry`, or `agent-framework-openai`), never the `agent-framework`
|
||
meta-package.
|
||
|
||
## Syntax checking
|
||
|
||
Run sample checks from the `python/` directory:
|
||
|
||
```bash
|
||
uv run poe syntax -S
|
||
uv run poe pyright -S
|
||
```
|
||
|
||
## Documentation
|
||
|
||
Samples should be over-documented:
|
||
|
||
1. Include a README.md in each set of samples.
|
||
2. Mark code sections with numbered comments.
|
||
3. Include expected output at the end of the file.
|
||
|
||
## 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)`)
|
||
- Do not use `client.as_agent(...)` in samples; construct agents explicitly with `Agent(client=client, ...)`.
|
||
- Tool methods on hosted tools are now functions, not classes (e.g. `hosted_mcp_tool(...)` not `HostedMCPTool(...)`)
|
||
- When only using a description for the field of a `@tool` parameter, do not use `Field`; use the string directly.
|