| 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:
- Hello Agent — Create an agent, invoke it, stream the response
- Add Tools — Give the agent a function tool it can call
- Multi-Turn — Maintain conversation state with threads
- Memory — Inject persistent context via context providers
- First Workflow — Compose a multi-step workflow
- 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:
- Agent Middleware — Wraps the entire
Agent.run() call; can modify messages, options, thread
- Chat Middleware — Wraps calls to the underlying chat client; can modify messages, options
- 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
- Apply the content placement rules in
agent-framework/AGENTS.md, then
determine which learning layer the content belongs to
- For Get Started: only add a step if it introduces a truly foundational concept
- For Agent Concepts: group under the appropriate topic area
- For Workflows: coordinate with the workflow team
- Ensure both Python and .NET samples exist before publishing a docs page
- Update the corresponding code repo's skills file with language-specific details
