sample-structure

# 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