sample-structure

name	sample-structure
description	Conceptual organization of Agent Framework documentation and samples. For language-specific details (file naming, provider setup, code patterns), see each code repo's skills files.

Skill: Agent Framework Conceptual Structure

Purpose

This skill defines the conceptual organization of Agent Framework documentation and how it maps to the learning journey. Language-specific implementation details belong in each code repo's skills files — this file covers the shared conceptual model only.

Progressive Learning Model

The Agent Framework uses a 5-layer structure that progressively builds complexity. Both docs and code samples mirror this structure so users can move fluidly between reading and running code.

Layer 1: Get Started       → Linear tutorial, one concept per step
Layer 2: Agent Concepts    → Deep-dive reference, organized by topic
Layer 3: Workflows         → Multi-step orchestration patterns
Layer 4: Hosting           → Deployment, protocols, production infrastructure
Layer 5: End-to-End        → Complete applications combining all layers

Layer Characteristics

Layer	Purpose	Complexity	Audience
Get Started	"Follow these steps" — sequential, cumulative	Beginner	New users
Agent Concepts	"Go deeper on X" — one topic per page	Intermediate	Users building features
Workflows	"Orchestrate multiple steps" — pattern-based	Intermediate	Users composing agents
Hosting	"Deploy to production" — infrastructure-focused	Advanced	Users shipping
End-to-End	"See it all together" — reference applications	Advanced	Users architecting

Get Started Progression

Each step adds exactly one concept to the previous step:

1. Hello Agent — Create an agent, invoke it, stream the response
2. Add Tools — Give the agent a function tool it can call
3. Multi-Turn — Maintain conversation state with threads
4. Memory — Inject persistent context via context providers
5. First Workflow — Compose a multi-step workflow
6. Host Your Agent — Expose the agent via A2A protocol

Agent Concepts — Topic Areas

Concepts are grouped by architectural concern:

• Tools — Function tools, hosted tools, MCP, approval workflows, code interpreter, file search, web search
• Middleware — Request interception at agent, chat, and function layers; termination, guardrails, shared state
• Conversations — Threads, persistent storage, suspend/resume, chat history
• Providers — Client setup for each supported model provider
• Context Providers — Memory injection, RAG patterns
• Orchestrations — Multi-agent patterns (handoff, sequential, concurrent)
• Observability — Tracing, OpenTelemetry, Foundry tracing
• Declarative — YAML/JSON-defined agents and workflows
• Multimodal — Image, audio, and file inputs

Architecture: Tools & Middleware Layers

The Agent Framework uses a layered middleware architecture with three interception points:

1. Agent Middleware — Wraps the entire Agent.run() call; can modify messages, options, thread
2. Chat Middleware — Wraps calls to the underlying chat client; can modify messages, options
3. Function Middleware — Wraps individual tool invocations; can modify arguments, override results

Each layer has its own context object and supports call_next() for pipeline chaining. Middleware can return normally (upstream post-processing runs), raise MiddlewareTermination (skips all post-processing), or raise exceptions (propagated to caller).

Docs ↔ Samples Alignment

Every docs page under get-started/ maps 1:1 to a sample file in both Python and .NET. Deep-dive docs pages link to corresponding concept samples.

Docs Section	Code Repo Layer	Cross-link pattern
get-started/*.md	01-get-started/	Each step → next step + lateral deep-dive
agents/**/*.md	02-agents/	Each topic → matching concept sample(s)
workflows/*.md	03-workflows/	Each pattern → matching workflow sample
integrations/**/*.md	Current location depends on the feature	Keep existing sample references until the corresponding phased sample move lands
hosting/**/*.md	04-hosting/	Hosting guides → matching hosting sample

The documentation taxonomy can move before the sample taxonomy. During that transition, move docs and update doc-to-doc links, TOC entries, and redirects, but keep :::code paths and sample repository URLs unchanged until the sample move is available.

Navigation Pattern

Docs pages follow consistent navigation:

• Sequential: Every page has a "Next step" link for linear flow
• Lateral: Every page has "Go deeper" links to related topics
• Upward: Every deep-dive page links back to its section overview

When Adding New Content

1. Apply the content placement rules in agent-framework/AGENTS.md, then determine which learning layer the content belongs to
2. For Get Started: only add a step if it introduces a truly foundational concept
3. For Agent Concepts: group under the appropriate topic area
4. For Workflows: coordinate with the workflow team
5. Ensure both Python and .NET samples exist before publishing a docs page
6. Update the corresponding code repo's skills file with language-specific details