Microsoft Agent Framework (Python)

Unified agent SDK that merges Semantic Kernel and AutoGen into one Pythonic library. Build single agents, multi-agent orchestration, cross-framework collaboration (A2A), and declarative workflows against the same primitives.

Install

pip install agent-framework

Version

Core 1.9.0 stable · agent-framework-foundry and agent-framework-openai bundled via agent-framework==1.9.0 · June 2026 · Python 3.10 – 3.13

Best for

Azure-native agents, multi-agent orchestration via WorkflowBuilder, cross-framework A2A, declarative YAML agents.

Earlier drafts had fabricated APIs

Pages under this guide previously documented agent_framework.graphs.AgentGraph, agent_framework.a2a.A2AProtocolAdapter, AzureAIAgentClient, ChatAgent, ai_function, and other names that do not exist. The real primary agent class in Python is Agent; the Azure chat client is FoundryChatClient from agent_framework.foundry. Pages were rewritten in April 2026 after introspecting agent-framework-core==1.1.0 and re-verified in May 2026 against 1.5.0. See Errata in the comprehensive guide for the running list.

azure-ai-agents integration add-on — class reference (6 volumes)

The azure-ai-agents package is an optional Microsoft add-on for the Azure AI Agents service. It is not a replacement for agent-framework — use it alongside the framework when you need direct access to Azure AI Agents service resources. Source-verified class deep dives covering 80+ classes/patterns across 6 volumes are available in the Integration Reference section below.

Where to start

New? Follow Zero → Hero below in order (~3–5 hours). Already shipping? Use Jump to a topic to go straight to what you need.

Zero → Hero

A guided reading order across the comprehensive guide, 2025 features, advanced and production docs. Each checkpoint is a section — read linearly or dive in wherever suits you.

1 · Setup & core fundamentals Install, architecture, unified SDK, authentication · 20 min

2 · Your first agent Agent basics, lifecycle, task execution · 20 min

3 · Model providers OpenAI, Azure OpenAI, Foundry, Anthropic, Ollama, Bedrock · 15 min

4 · Tools @tool, FunctionTool, approval gates, schemas, runtime context · 15 min

5 · MCP integration MCPStdioTool, MCPStreamableHTTPTool, MCPWebsocketTool · 20 min

6 · Skills Progressive-disclosure domain knowledge, scripts, resources · 15 min

7 · Middleware Agent / chat / function middleware, redaction, retries · 20 min

8 · Multi-agent orchestration Sequential, Concurrent, Handoff, GroupChat, Magentic · 30 min

9 · Human in the loop request_info, response_handler, orchestration HITL, tool approval · 20 min

10 · Checkpointing Persist and resume workflows across restarts · 15 min

11 · Compaction Sliding window, summarization, token-budget strategies · 15 min

11b · Sessions & history AgentSession, FileHistoryProvider, custom storage backends · 15 min

12 · Observability & telemetry OpenTelemetry spans, metrics, logs, Azure Monitor · 20 min

13 · Evaluation evaluate_agent, LocalEvaluator, @evaluator, ground-truth checks · 20 min

14 · Structured output Pydantic schemas, validation, type-safe responses · 15 min

15 · Graph workflows Directed graphs, streaming, time-travel · 25 min

15b · Functional workflows @workflow, @step, RunContext, HITL, checkpointing · 20 min

16 · Declarative agents YAML/JSON config, Pydantic validation · 15 min

17 · A2A protocol Interop with OpenAI SDK, Claude SDK, LangGraph, Google ADK · 20 min

18 · Production Azure Container Apps, scaling, security, DR · 30 min

19 · Class deep dives (Vol. 1) Agent, RawAgent, FunctionTool, WorkflowBuilder, RunContext, InlineSkill, MCPStdioTool — source-verified at 1.6.0 · 30 min

20 · Class deep dives (Vol. 2) FileHistoryProvider, AgentMiddleware, ChatMiddleware, FunctionMiddleware, CompactionProvider, ToolResultCompactionStrategy, TokenBudgetComposedStrategy, FileCheckpointStorage, LocalEvaluator, WorkflowRunResult — source-verified at 1.6.0 · 35 min

21 · Class deep dives (Vol. 3) BackgroundAgentsProvider, MemoryContextProvider + MemoryFileStore, TodoProvider + TodoFileStore, AgentModeProvider, SummarizationStrategy, ContextWindowCompactionStrategy, SlidingWindowStrategy, SelectiveToolCallCompactionStrategy, WorkflowViz, MCPStreamableHTTPTool + MCPWebsocketTool — source-verified at 1.7.0 · 40 min

22 · Class deep dives (Vol. 4) Message + Content, ChatOptions + ChatResponse + ChatResponseUpdate + UsageDetails, ResponseStream, AgentContext, FunctionalWorkflow + StepWrapper, WorkflowEvent taxonomy, SkillsSource composition layer, EvalItem + EvalResults + EvalScoreResult, TokenizerProtocol + CharacterEstimatorTokenizer, ConversationSplit + ConversationSplitter — source-verified at 1.7.0 · 45 min

23 · Class deep dives (Vol. 5) Executor + @handler + @executor, AgentExecutor + AgentExecutorRequest + AgentExecutorResponse, FanOutEdgeGroup + FanInEdgeGroup + SwitchCaseEdgeGroup, Runner + WorkflowMessage, SessionContext, AgentSession + register_state_type, BaseChatClient + SupportsChatGetResponse, SecretString + load_settings, WorkflowCheckpoint + CheckpointStorage, Exception hierarchy — source-verified at 1.7.0 · 50 min

24 · Class deep dives (Vol. 6) ExperimentalFeature + @experimental, WorkflowRunState + WorkflowErrorDetails, WorkflowExecutor + sub-workflow messages, AgentResponse + AgentResponseUpdate + ContinuationToken, BaseEmbeddingClient + embedding family, FunctionInvocationConfiguration, ClassSkill + SkillFrontmatter + FileSkillsSource + SkillsProvider, Annotation + TextSpanRegion, provider capability protocols, MiddlewareType + layer classes — source-verified at 1.7.0 · 55 min

29 · Class deep dives (Vol. 7) ContextProvider authoring, BackgroundTaskInfo + BackgroundTaskStatus, GroupChatBuilder + TerminationCondition, HandoffBuilder + HandoffConfiguration, MagenticBuilder + StandardMagenticManager + MagenticProgressLedger, SequentialBuilder + ConcurrentBuilder, AgentFactory + WorkflowFactory (declarative YAML), SecureAgentConfig + ContentLabel (prompt injection defence), FunctionalWorkflowAgent, ObservabilitySettings + configure_otel_providers — source-verified at 1.7.0 · 60 min

30 · Class deep dives (Vol. 8) AgentFileStore + FileSystemAgentFileStore + InMemoryAgentFileStore (file workspace), FileAccessProvider + FileSearchResult + FileSearchMatch (5-tool CRUD harness), MCPSkill + MCPSkillResource + MCPSkillsSource (SEP-2640 discovery), ToolMode + validate_tool_mode (tool-choice control), AgentEvalConverter + ExpectedToolCall + CheckResult + RubricScore (eval helpers), ChatContext (full chat middleware context), WorkflowAgent + WorkflowContext (workflow-as-agent), TruncationStrategy (oldest-first compaction), HistoryProvider + InMemoryHistoryProvider (history ABC), DelegatingSkillsSource + InMemorySkillsSource + FunctionInvocationContext (skills + progressive tools) — source-verified at 1.8.0 · 60 min

31 · Class deep dives (Vol. 9) OllamaChatClient + OllamaChatOptions (local LLM), PurviewPolicyMiddleware + PurviewChatPolicyMiddleware + PurviewSettings (compliance), DurableAIAgent + DurableAIAgentClient + DurableAIAgentWorker (durable actors), GitHubCopilotAgent + GitHubCopilotOptions (Copilot routing), HyperlightExecuteCodeTool + AllowedDomain + FileMount (Wasm sandboxing), HyperlightCodeActProvider (CodeAct context provider), Mem0ContextProvider (cloud semantic memory), RedisContextProvider + RedisHistoryProvider (Redis persistence), StandardMagenticManager + MagenticContext + MagenticProgressLedger (Magentic-One internals), FileSkillsSource + FilteringSkillsSource + AggregatingSkillsSource (skill discovery) — source-verified at 1.8.0 · 65 min

32 · Class deep dives (Vol. 10) Workflow + InProcRunnerContext (execution engine API), FunctionExecutor (plain-function graph nodes), FunctionInvocationLayer (custom chat-client mixin), MemoryStore + MemoryIndexEntry + MemoryTopicRecord (memory harness ABC), TodoStore + TodoItem + TodoFileStore + TodoSessionStore (todo harness), DeduplicatingSkillsSource, SkillsProvider (from_paths + multi-source), MCPTaskOptions (SEP-2663 long-running task lifecycle), InMemoryCheckpointStorage (test checkpointing), EvalScoreResult + CompactionStrategy + BaseAgent — source-verified at 1.8.1 · 70 min

33 · Class deep dives (Vol. 11) AgentTelemetryLayer + ChatTelemetryLayer + EmbeddingTelemetryLayer (OTel mixin layer — token/duration histograms, AGENT_PROVIDER_NAME, sensitive telemetry toggle), Edge + EdgeGroup + SingleEdgeGroup + InternalEdgeGroup (workflow graph primitives — conditional routing, serialisation round-trip, custom subclasses), Case + Default (runtime switch-case wrappers), EdgeRunner hierarchy (SingleEdgeRunner, FanOutEdgeRunner, FanInEdgeRunner, SwitchCaseEdgeRunner — delivery status, buffering semantics, concurrent dispatch), ExecutionContext (sub-workflow tracking — HITL pending_requests, collected_responses), WorkflowGraphValidator (7 pre-build checks: duplication, type compatibility, connectivity, self-loops, dead-ends, output validation), MCPTool + MCPSpecificApproval (base for all 3 MCP transports — full constructor reference, per-tool parsing, additional_tool_argument_names), SerializationMixin + SerializationProtocol (DTO round-trip — DEFAULT_EXCLUDE, INJECTABLE, dependency injection patterns), Evaluator + EvalItemResult + EvalNotPassedError (evaluation backend Protocol — custom evaluator impl, CI gate), PerServiceCallHistoryPersistingMiddleware (per-service-call history persistence — service_stores_history flag, sentinel conversation ID) — source-verified at 1.8.1 · 75 min

34 · Class deep dives (Vol. 12) Skill + SkillResource + SkillScript ABCs (contract methods, custom backends), FileSkill (SKILL.md content cache, scripts XML block injection, case-insensitive lookup), InlineSkillResource + InlineSkillScript (static vs callable resources, in-process execution, auto-generated parameters_schema), FileSkillScript + SkillScriptRunner (file-backed scripts, fixed CLI array schema, async runner protocol), SupportsAgentRun (structural protocol — custom agent without inheritance, isinstance guard), RunnerContext (full execution context protocol — messaging, events, checkpointing, streaming, HITL), SwitchCaseEdgeGroupCase + SwitchCaseEdgeGroupDefault (serialisable branch descriptors — condition_name, to_dict/from_dict, missing-callable placeholder), ValidationTypeEnum + WorkflowValidationError hierarchy (6 validation categories, EdgeDuplicationError, TypeCompatibilityError, GraphConnectivityError, match-based handler), A2AAgent + A2AAgentSession + A2AExecutor (URL/AgentCard/client init, dual streaming clients, auth interceptors, multi-turn sessions, A2A server exposure), WorkflowRunnerException + WorkflowCheckpointException + MiddlewareException (leaf exception classes, supervisor pattern) — source-verified at 1.8.1 · 80 min

35 · Class deep dives (Vol. 13) OpenAIChatClient+OpenAIChatOptions+OpenAISettings+RawOpenAIChatClient (Responses API — 4-layer MRO, STORES_BY_DEFAULT, x-ms-served-model header, reasoning model options), OpenAIChatCompletionClient+OpenAIChatCompletionOptions (Chat Completions API — logprobs, prediction, stateless vs stateful table), OpenAIEmbeddingClient+OpenAIEmbeddingOptions+OpenAIContinuationToken+OpenAIContentFilterException (embeddings+RAG, background polling, Azure content filter handling), AnthropicClient+AnthropicChatOptions+RawAnthropicClient (Anthropic Messages API — extended thinking, top_k, service_tier, beta flags), ClaudeAgent+ClaudeAgentOptions+RawClaudeAgent (Claude Code CLI agent — tool allow/blocklist, MCP servers, permission_mode, sandbox, workflow participation), AnthropicFoundryClient+AnthropicBedrockClient+AnthropicVertexClient (multi-cloud Claude — Azure Foundry AAD, Bedrock IAM, Vertex ADC, failover pattern), GroupChatOrchestrator+AgentBasedGroupChatOrchestrator+GroupChatState+AgentOrchestrationOutput (group-chat internals — round-robin and LLM selection, frozen state snapshot), HandoffAgentExecutor+HandoffAgentUserRequest+HandoffSentEvent+OrchestrationState (handoff internals — autonomous mode, HITL, event observability, checkpoint round-trip), MagenticOrchestrator+MagenticAgentExecutor+MagenticOrchestratorEvent+MagenticPlanReviewRequest+MagenticPlanReviewResponse (Magentic deeper — outer/inner loop, reset signal, plan signoff HITL, progress ledger serialisation), HttpRequestHandler+DefaultHttpRequestHandler+MCPToolHandler+DefaultMCPToolHandler+ExternalInputRequest+ToolApprovalRequest (declarative handlers — SSRF guard, MCP discovery, tool approval gate, agent HITL) — source-verified at 1.8.1 · 85 min

36 · Class deep dives (Vol. 14) State (superstep caching — set/get/commit/discard/export_state/import_state, delete sentinel, checkpoint integration), OutputDesignation (output routing — is_terminal/is_intermediate/classify, compatibility mode vs explicit output_from, intermediate_output_from), MessageType enum + WorkflowMessage (STANDARD vs RESPONSE types, plural trace_contexts for fan-in OTel linking, to_dict/from_dict round-trip), DictConvertible + encode_value (dict/JSON round-trip mixin — from_dict, clone deep/shallow, to_json/from_json, recursive encoding), MiddlewareWrapper + BaseMiddlewarePipeline (callable→middleware adapter, has_middlewares gate, auto-wrapping in _register_middleware_with_wrapper), AgentMiddlewarePipeline + ChatMiddlewarePipeline + FunctionMiddlewarePipeline (concrete pipeline execute() — streaming support, matches() cache key, MiddlewareTermination short-circuit), MiddlewareDict + categorize_middleware (TypedDict bag — mixed-type list sorting, callable type inference, multiple source merge), FunctionRequestResult TypedDict (action return/continue/stop, errors_in_a_row, result_message, function_call_count — tool-loop integration), OtelAttr + MessageListTimestampFilter (GenAI semantic convention enum — all 35 attribute names; logging filter for 1µs timestamp offsets in structured logs), PolicyEnforcementFunctionMiddleware + ConfidentialityLabel + ContentVariableStore + VariableReferenceContent + LabeledMessage + InspectVariableInput (prompt injection IFC defence — variable indirection store, confidentiality PUBLIC/PRIVATE/USER_IDENTITY, block vs approval-on-violation modes, SecureAgentConfig one-liner setup) — source-verified at 1.8.1 · 90 min

37 · Class deep dives (Vol. 15) AGUIChatClient+AGUIEventConverter+AGUIHttpService (AG-UI streaming stateful UI protocol — per-session converter, SSE delivery, stateless mode), AgentFrameworkAgent+AgentFrameworkWorkflow+state_update+add_agent_framework_fastapi_endpoint (FastAPI/Teams hosting — pending-approval registry, streaming SSE, CORS), ThreadItemConverter+simple_to_agent_input+stream_agent_response (ChatKit thread-item streaming — multimodal mapping, delta merging), DevServer+serve+register_cleanup (local OpenAI-compatible debug server — multi-agent, CORS security fix, graceful teardown), GAIA+GAIATelemetryConfig+TaskRunner+TaskResult+Prediction+Evaluation (GAIA benchmark lab — telemetry config, async runner, result aggregation), CopilotStudioAgent (Copilot Studio bridge — COPILOTSTUDIOAGENT__ env prefix, conversation turn streaming), AzureAISearchContextProvider (semantic/agentic retrieval — AZURE_SEARCH_ env prefix, top_k/semantic_configuration_name), CosmosHistoryProvider (Cosmos DB history — AZURE_COSMOS_ env prefix, store_context_messages, store_context_from), DurableAIAgentClient+DurableAIAgentWorker+DurableAIAgentOrchestrationContext+AgentCallbackContext (durable task hosting — get_agent().run(), yield Task, callback protocol), AgentFunctionApp (Azure Functions serverless — enable_http_endpoints, enable_mcp_tool_trigger, health check) — source-verified at 1.8.1 · 90 min

38 · Class deep dives (Vol. 16) FoundryAgent+FoundryAgentOptions+RawFoundryAgent+RawFoundryAgentChatClient (hosted Azure AI Foundry agents — PromptAgent/HostedAgent modes, isolation_key per-session, allow_preview, client_type override), FoundryLocalClient+FoundryLocalChatOptions (on-device LLM via Foundry Local — bootstrap, prepare_model, device NPU/GPU/CPU, structured output), FoundryMemoryProvider (Foundry Memory Store semantic memory — memory_store_name, scope, update_delay, before/after_run lifecycle), FoundryEvals+GeneratedEvaluatorRef+evaluate_foundry_target (Foundry cloud eval harness — 19 built-in evaluator name constants, smart defaults, tool_call_accuracy auto-add), BedrockChatClient+BedrockChatOptions+BedrockGuardrailConfig+BedrockSettings (Bedrock Converse API — BEDROCK_REGION/BEDROCK_CHAT_MODEL env vars, guardrail sync/async streaming, unsupported-options table), BedrockEmbeddingClient+BedrockEmbeddingOptions+BedrockEmbeddingSettings (Bedrock Titan embeddings — BEDROCK_EMBEDDING_MODEL, normalize flag, MemoryContextProvider wiring), MagenticManagerBase (custom Magentic manager authoring — 4 abstract methods: plan/replan/create_progress_ledger/prepare_final_answer, checkpoint save/restore hooks), BaseGroupChatOrchestrator+GroupChatRequestSentEvent+GroupChatResponseReceivedEvent (group chat base class — max_rounds coercion, 4 @handler overloads, event dataclasses for observability), AgentRequestInfoResponse+CacheProvider (HITL approval model — approve()/from_messages()/from_strings() factories; CacheProvider Protocol for Purview integration), Purview exception hierarchy+acquire_token (PurviewAuthenticationError/PaymentRequiredError/RateLimitError/RequestError/ServiceError hierarchy; MSAL silent-then-interactive token flow) — source-verified at 1.8.1 · 95 min

39 · Class deep dives (Vol. 17) ToolApprovalMiddleware+ToolApprovalRule+ToolApprovalState (interactive tool approval gates — standing rules, queue drain, argument matching), AgentLoopMiddleware+JudgeVerdict+todos_remaining+background_tasks_running (LLM-judged self-improvement loops — fresh_context snapshot, with_judge, return_final_only), SamplingApprovalCallback+MCP sampling security (confused-deputy mitigation — deny-by-default, token cap, async callback), to_prompt_agent (Foundry PromptAgent publisher — RawFoundryChatClient required, model resolution, local MCP raises ValueError), FoundryEmbeddingClient+FoundryEmbeddingOptions+FoundryEmbeddingSettings+RawFoundryEmbeddingClient (multimodal text+image embeddings — mixed batch split/reassemble, image_model precedence), ContentUnderstandingContextProvider+AnalysisSection+DocumentStatus (Azure Content Understanding — auto-detect analyzer, deferred analysis, auto-registered list_documents tool), FileSearchConfig+FileSearchBackend+OpenAIFileSearchBackend+FoundryFileSearchBackend (vector store upload/delete backends — create_and_poll, custom backend), AgentFrameworkTracer (Agent Lightning OTel bridge — OBSERVABILITY_SETTINGS singleton, init/teardown lifecycle), TaskRunner+patch_env_set_state+unpatch_env_set_state (Tau2 airline benchmark harness — three-part conversation assembly, reinit() chaining, evaluate reward), 8 new FoundryChatClient hosted tool factories (get_mcp_tool, get_azure_ai_search_tool, get_sharepoint_tool, get_fabric_tool, get_memory_search_tool, get_computer_use_tool, get_browser_automation_tool, get_a2a_tool) — first volume source-verified at 1.9.0 · 100 min

40 · Class deep dives (Vol. 18) Skill+SkillFrontmatter+SkillScriptRunner (Agent Skills spec — name/description/compatibility validation, file-script runner protocol), InlineSkill (@skill.resource/@skill.script decorators — XML content synthesis, content caching), InMemorySkillsSource+AggregatingSkillsSource+FilteringSkillsSource+DeduplicatingSkillsSource (skills pipeline — fan-in, predicate filter, first-one-wins dedup), AgentFileStore+InMemoryAgentFileStore+FileSearchMatch+FileSearchResult (file storage ABC + in-memory backend — exclusive-create, async lock, __slots__ DTOs, custom Azure Blob example), FileAccessProvider (6-tool file workspace — save/read/delete/list/search, require_delete_approval gate, shared across sessions), BackgroundAgentsProvider+BackgroundTaskInfo+BackgroundTaskStatus (background sub-agent delegation — asyncio.Task fan-out, continue_task session resume, LOST status on process restart), MemoryStore+MemoryTopicRecord+MemoryIndexEntry (durable memory backing store ABC — Markdown serialization, slug normalization, pointer line rendering, custom dict-backed store example), WorkflowGraphValidator+EdgeDuplicationError+GraphConnectivityError+TypeCompatibilityError (7-check pre-build validation — DFS reachability, self-loop warnings, FanIn list-wrapping type check), MagenticBuilder+MagenticManagerBase+MagenticProgressLedger+MagenticProgressLedgerItem (Magentic One internals — 5-item progress ledger, abstract plan/replan/create_progress_ledger/prepare_final_answer, custom manager example), LocalEvaluator+EvalItem+EvalScoreResult+ConversationSplit+ExpectedToolCall (local evaluation framework — per_turn_items, LAST_TURN/FULL splits, @evaluator custom checks, evaluate_agent end-to-end) — source-verified at 1.9.0 · 95 min

41 · Class deep dives (Vol. 19) ConcurrentBuilder (fan-out/fan-in — with_aggregator callback/Executor, output_from, intermediate_output_from, with_request_info, checkpoint), SequentialBuilder (shared-conversation chains — chain_only_agent_responses, output_from, with_request_info per-agent, checkpoint), HandoffBuilder+HandoffConfiguration+HandoffSentEvent (decentralised handoff — add_handoff routing graph, with_start_agent, with_autonomous_mode per-agent turn limits, output_from), HandoffAgentUserRequest (HITL factories — create_response str/Message, terminate), OrchestrationState (unified checkpoint dataclass — conversation+round_index+metadata+task, to_dict/from_dict, pattern-specific metadata extension), AgentModeProvider+get_agent_mode+set_agent_mode (plan/execute mode harness — mode_descriptions Mapping, {available_modes}/{current_mode} template, default_mode resolution, external-change notification message), TodoItem+TodoInput+TodoCompleteInput (todo DTO primitives — SerializationMixin round-trip, stripping/validation rules, __eq__/__repr__), TodoStore+TodoSessionStore+TodoFileStore (backing store ABC — session state storage, file-backed JSON with path-traversal guard, Windows reserved name encoding, custom store example), TodoProvider (5-tool harness — todos_add/complete/remove/get_remaining/get_all, per-session asyncio.Lock via WeakKeyDictionary, custom store injection, combined with AgentModeProvider), MagenticResetSignal+StandardMagenticManager (stall-recovery sentinel + fully-customisable LLM manager — 7 prompt overrides, max_stall/reset/round_count, progress_ledger_retry_count, observe REPLANNED events) — source-verified at 1.9.0 · 100 min

42 · Class deep dives (Vol. 20) SupportsCodeInterpreterTool+SupportsWebSearchTool+SupportsImageGenerationTool+SupportsMCPTool+SupportsFileSearchTool+SupportsShellTool (6 @runtime_checkable hosted-tool Protocols — provider-agnostic isinstance guard + factory call), SupportsGetEmbeddings (typed embedding duck-typing Protocol — get_embeddings signature, Generic contravariant input), ReleaseCandidateFeature+FeatureStageWarning+ExperimentalWarning (feature staging system — deduplication via _WARNED_FEATURES, single-line formatter, CI error filter), EmbeddingGenerationOptions+Embedding+GeneratedEmbeddings (embedding DTO layer — TypedDict options, Generic vector Embedding, list[Embedding] subclass with usage), WorkflowEventSource (EXECUTOR vs FRAMEWORK origin str-Enum), SubWorkflowRequestMessage+SubWorkflowResponseMessage (hierarchical workflow HITL bridge — create_response type validation, executor_id multi-instance routing), RequestInfoMixin+response_handler decorator (executor-level HITL wiring — introspection vs explicit type modes, forward references, duplicate-handler guard), WorkflowAgent.RequestInfoFunctionArgs (HITL tool-call serialization dataclass — to_dict/from_dict, REQUEST_INFO_FUNCTION_NAME sentinel), EdgeGroupDeliveryStatus (OTel edge-delivery status enum — 6 values: DELIVERED/BUFFERED/DROPPED_TYPE_MISMATCH/DROPPED_CONDITION_FALSE/DROPPED_TARGET_MISMATCH/EXCEPTION), IntegrityLabel+LabelTrackingFunctionMiddleware (IFC security experimental — TRUSTED/UNTRUSTED labels, 3-tier propagation priority table, variable indirection auto-hide, get_security_tools, reset_context_label), MiddlewareTermination+WorkflowConvergenceException (control-flow short-circuit with result payload + runner max-iteration exceeded) — source-verified at 1.9.0 · 105 min

43 · Class deep dives (Vol. 21) WorkflowContext[OutT,W_OutT] (per-executor execution context — send_message, yield_output, request_info, state R/W, source_executor_ids, is_streaming), FanInEdgeGroup+FanOutEdgeGroup (converging/broadcasting edge groups — min-source/target validation, selection_func dynamic routing), SwitchCaseEdgeGroup+SwitchCaseEdgeGroupCase+SwitchCaseEdgeGroupDefault (switch/case routing — sequential predicate evaluation, exactly-one-default invariant), TokenBudgetComposedStrategy (multi-strategy composition — early_stop, annotate_message_groups pipeline, strict-budget double-fallback), SelectiveToolCallCompactionStrategy+ToolResultCompactionStrategy (tool history reduction — exclude vs inline summary, keep_last_tool_call_groups), SlidingWindowStrategy+SummarizationStrategy (sliding window + LLM-backed summarization — preserve_system, target_count+threshold, bidirectional trace metadata), StepWrapper+FunctionalWorkflow+RunContext (functional workflow internals — caching by call_index, executor_bypassed on cache hit, checkpoint per step), MCPWebsocketTool+MCPStreamableHTTPTool (MCP network transports — WebSocket wss://, streamable HTTP/SSE with header_provider ContextVar injection), MCPTaskOptions (SEP-2663 long-running task lifecycle — default_ttl, max_task_wait, cancel_remote_task_on_local_cancellation), AgentResponseUpdate+ChatResponseUpdate+ContinuationToken (streaming chunk types — .text property, continuation_token resumption, author_name, finish_reason) — source-verified at 1.9.0 · 110 min

25 · azure-ai-agents integration — class reference Vol. 3 Add-on: AsyncFunctionTool, AzureFunctionTool, AzureAISearchTool, VectorStore, ThreadRun, RunStep, ResponseFormatJsonSchema, TruncationObject, MessageAttachment, AsyncAgentEventHandler — source-verified · 45 min

26 · azure-ai-agents integration — class reference Vol. 4 Add-on: enable_auto_function_calls, create_thread_and_process_run, FunctionTool dynamic registration, CodeInterpreterTool file upload, FileSearchTool+VectorStore lifecycle, AzureAISearchTool query modes, BingGroundingTool params, ConnectedAgentTool multi-agent, custom AgentEventHandler, AsyncToolSet concurrent execution — source-verified · 50 min

27 · azure-ai-agents integration — class reference Vol. 5 Add-on: Agent model, AgentThread, ToolOutput, VectorStoreFileBatch, VectorStoreFile, FileInfo, MessageDeltaChunk (.text property), RunStepDeltaChunk (code-interpreter streaming), SubmitToolOutputsAction (full dispatch loop), AgentRunStream + all 8 AgentEventHandler hooks — source-verified · 55 min

28 · azure-ai-agents integration — class reference Vol. 6 Add-on: OpenAPI auth hierarchy (anonymous/managed-identity/connection), BingGroundingSearchConfiguration, RunCompletionUsage + RunStepCompletionUsage, VectorStoreDataSource + VectorStoreConfigurations, expiry policy + static/auto chunking, AgentsNamedToolChoice, file-search step results + FileSearchRankingOptions, streaming event taxonomy (AgentStreamEvent + 4 sub-enums), RequiredFunctionToolCall manual dispatch, multimodal ThreadMessageOptions (image file + URL) — source-verified · 60 min

Jump to a topic

Model providers (OpenAI, Azure, Foundry, Anthropic, Ollama, Bedrock)

Multi-agent orchestration (5 builders)

Middleware — agent / chat / function

Tools — @tool & FunctionTool

MCP tools (stdio, streamable HTTP, websocket)

Skills — progressive-disclosure knowledge

Human in the loop — request_info & approval

Checkpointing — pause/resume workflows

Compaction — stay inside the context window

Sessions & history — AgentSession, FileHistoryProvider

Observability & telemetry (OpenTelemetry)

Evaluation — evaluate_agent, LocalEvaluator

Agent lifecycle

Pydantic structured output

Graph workflows

Functional workflows (@workflow / @step)

A2A cross-framework

Declarative YAML agents

Content safety

Async best practices

Class deep dives Vol. 1 (10 classes, source-verified)

Class deep dives Vol. 2 (10 more classes, source-verified)

Class deep dives Vol. 3 (10 harness + compaction + viz + MCP classes, 1.7.0)

Class deep dives Vol. 4 (Message/Content, chat layer, ResponseStream, AgentContext, FunctionalWorkflow, WorkflowEvent, SkillsSource, EvalItem, Tokenizer, ConversationSplit)

Class deep dives Vol. 5 (Executor + @handler, AgentExecutor, edge groups, Runner, SessionContext, AgentSession, BaseChatClient, SecretString, WorkflowCheckpoint, Exceptions)

Class deep dives Vol. 6 (ExperimentalFeature, WorkflowRunState, WorkflowExecutor, AgentResponse, BaseEmbeddingClient, FunctionInvocationConfiguration, ClassSkill, Annotation, capability protocols, middleware layers)

Class deep dives Vol. 7 (ContextProvider, BackgroundTaskInfo, GroupChatBuilder, HandoffBuilder, MagenticBuilder, SequentialBuilder, ConcurrentBuilder, AgentFactory, WorkflowFactory, SecureAgentConfig, FunctionalWorkflowAgent, ObservabilitySettings)

Class deep dives Vol. 8 — 1.8.0 (AgentFileStore, FileAccessProvider, MCPSkill, ToolMode, AgentEvalConverter, ChatContext, WorkflowAgent, TruncationStrategy, HistoryProvider, DelegatingSkillsSource + FunctionInvocationContext)

Class deep dives Vol. 9 — 1.8.0 (OllamaChatClient, PurviewPolicyMiddleware, DurableAIAgent+Worker+Client, GitHubCopilotAgent, HyperlightExecuteCodeTool, HyperlightCodeActProvider, Mem0ContextProvider, RedisContextProvider+HistoryProvider, StandardMagenticManager+MagenticContext, FileSkillsSource+FilteringSkillsSource)

Class deep dives Vol. 10 — 1.8.1 (Workflow + InProcRunnerContext, FunctionExecutor, FunctionInvocationLayer, MemoryStore + MemoryIndexEntry + MemoryTopicRecord, TodoStore + TodoFileStore + TodoSessionStore, DeduplicatingSkillsSource, SkillsProvider, MCPTaskOptions, InMemoryCheckpointStorage, EvalScoreResult + CompactionStrategy + BaseAgent)

Class deep dives Vol. 11 — 1.8.1 (AgentTelemetryLayer, Edge+EdgeGroup+SingleEdgeGroup+InternalEdgeGroup, Case+Default, EdgeRunner hierarchy, ExecutionContext, WorkflowGraphValidator, MCPTool+MCPSpecificApproval, SerializationMixin+SerializationProtocol, Evaluator+EvalItemResult+EvalNotPassedError, PerServiceCallHistoryPersistingMiddleware)

Class deep dives Vol. 12 — 1.8.1 (Skill+SkillResource+SkillScript ABCs, FileSkill, InlineSkillResource+InlineSkillScript, FileSkillScript+SkillScriptRunner, SupportsAgentRun, RunnerContext, SwitchCaseEdgeGroupCase+SwitchCaseEdgeGroupDefault, ValidationTypeEnum+WorkflowValidationError hierarchy, A2AAgent+A2AAgentSession+A2AExecutor, WorkflowRunnerException+WorkflowCheckpointException+MiddlewareException)

Class deep dives Vol. 13 — 1.8.1 (OpenAIChatClient+OpenAIChatOptions+OpenAISettings, OpenAIChatCompletionClient, OpenAIEmbeddingClient+ContentFilterResultSeverity, AnthropicClient+AnthropicChatOptions, ClaudeAgent+ClaudeAgentOptions, AnthropicFoundryClient+AnthropicBedrockClient+AnthropicVertexClient, GroupChatOrchestrator+AgentBasedGroupChatOrchestrator, HandoffAgentExecutor+OrchestrationState, MagenticOrchestrator+MagenticPlanReviewRequest, declarative HTTP/MCP/approval handlers)

Class deep dives Vol. 14 — 1.8.1 (State superstep cache, OutputDesignation output routing, MessageType+WorkflowMessage fan-in OTel, DictConvertible mixin, MiddlewareWrapper+BaseMiddlewarePipeline, pipeline classes, MiddlewareDict+categorize_middleware, FunctionRequestResult, OtelAttr+MessageListTimestampFilter, prompt-injection IFC defence security module)

Class deep dives Vol. 15 — 1.8.1 (AGUIChatClient+AGUIEventConverter+AGUIHttpService, AgentFrameworkAgent+AgentFrameworkWorkflow+state_update, ThreadItemConverter+simple_to_agent_input+stream_agent_response, DevServer+serve+register_cleanup, GAIA+GAIATelemetryConfig+TaskRunner, CopilotStudioAgent, AzureAISearchContextProvider, CosmosHistoryProvider, DurableAIAgentClient+Worker+OrchestrationContext+AgentCallbackContext, AgentFunctionApp)

Class deep dives Vol. 16 — 1.8.1 (FoundryAgent+FoundryAgentOptions, FoundryLocalClient, FoundryMemoryProvider, FoundryEvals+GeneratedEvaluatorRef, BedrockChatClient+BedrockChatOptions+BedrockGuardrailConfig, BedrockEmbeddingClient+BedrockEmbeddingOptions, MagenticManagerBase, BaseGroupChatOrchestrator+GroupChatRequestSentEvent+GroupChatResponseReceivedEvent, AgentRequestInfoResponse+CacheProvider, Purview exception hierarchy+acquire_token)

Class deep dives Vol. 17 — 1.9.0 (ToolApprovalMiddleware+ToolApprovalRule+ToolApprovalState, AgentLoopMiddleware+JudgeVerdict+todos_remaining+background_tasks_running, SamplingApprovalCallback+MCP sampling security, to_prompt_agent, FoundryEmbeddingClient+FoundryEmbeddingOptions+FoundryEmbeddingSettings, ContentUnderstandingContextProvider+AnalysisSection+DocumentStatus, FileSearchConfig+FileSearchBackend, AgentFrameworkTracer, TaskRunner+patch_env_set_state, 8 new FoundryChatClient hosted tool factories)

Class deep dives Vol. 18 — 1.9.0 (Skill+SkillFrontmatter+SkillScriptRunner, InlineSkill, skills source pipeline, AgentFileStore+InMemoryAgentFileStore+DTOs, FileAccessProvider, BackgroundAgentsProvider+BackgroundTaskInfo+BackgroundTaskStatus, MemoryStore+MemoryTopicRecord+MemoryIndexEntry, WorkflowGraphValidator+error types, MagenticBuilder+MagenticManagerBase+MagenticProgressLedger, LocalEvaluator+EvalItem+ConversationSplit+ExpectedToolCall)

Class deep dives Vol. 19 — 1.9.0 (ConcurrentBuilder, SequentialBuilder, HandoffBuilder+HandoffConfiguration, HandoffAgentUserRequest, OrchestrationState, AgentModeProvider+get_agent_mode+set_agent_mode, TodoItem+TodoInput+TodoCompleteInput, TodoStore+TodoSessionStore+TodoFileStore, TodoProvider, MagenticResetSignal+StandardMagenticManager)

Class deep dives Vol. 20 — 1.9.0 (capability Protocols: SupportsCodeInterpreterTool/SupportsWebSearchTool/SupportsImageGenerationTool/SupportsMCPTool/SupportsFileSearchTool/SupportsShellTool/SupportsGetEmbeddings; feature staging: ReleaseCandidateFeature/FeatureStageWarning/ExperimentalWarning; EmbeddingGenerationOptions/Embedding/GeneratedEmbeddings; WorkflowEventSource; SubWorkflowRequestMessage/SubWorkflowResponseMessage; RequestInfoMixin/response_handler; WorkflowAgent.RequestInfoFunctionArgs; EdgeGroupDeliveryStatus; IntegrityLabel/LabelTrackingFunctionMiddleware; MiddlewareTermination/WorkflowConvergenceException)

Class deep dives Vol. 21 — 1.9.0 (WorkflowContext[OutT,W_OutT]; FanInEdgeGroup+FanOutEdgeGroup; SwitchCaseEdgeGroup+SwitchCaseEdgeGroupCase+SwitchCaseEdgeGroupDefault; TokenBudgetComposedStrategy; SelectiveToolCallCompactionStrategy+ToolResultCompactionStrategy; SlidingWindowStrategy+SummarizationStrategy; StepWrapper+FunctionalWorkflow+RunContext; MCPWebsocketTool+MCPStreamableHTTPTool; MCPTaskOptions; AgentResponseUpdate+ChatResponseUpdate+ContinuationToken)

azure-ai-agents integration reference Vol. 3 (10 classes)

azure-ai-agents integration reference Vol. 4 (10 patterns)

azure-ai-agents integration reference Vol. 5 (data model + streaming)

azure-ai-agents integration reference Vol. 6 (auth, Bing config, token usage, data sources, chunking, tool choice, file-search results, streaming events, manual dispatch, multimodal)

Reference

Model providers Every first-party chat client — real constructors.

Multi-agent orchestration Sequential, Concurrent, Handoff, GroupChat, Magentic.

Middleware Agent / chat / function pipelines, short-circuit patterns.

Tools @tool decorator, FunctionTool, approval, schemas, context.

MCP integration Stdio, streamable HTTP, websocket — approval and headers.

Skills Progressive-disclosure knowledge via Skill / SkillsProvider.

Human in the loop request_info, response_handler, tool approval, resume.

Checkpointing File / in-memory storage, custom backends, resume semantics.

Compaction Sliding window, summarization, token-budget strategies.

Sessions & history AgentSession, history providers, multi-provider audit logs, cross-process serialization.

Observability & telemetry OpenTelemetry spans, metrics, logs, Azure Monitor integration.

Evaluation evaluate_agent, evaluate_workflow, LocalEvaluator, @evaluator.

Comprehensive guide Single-page technical reference — all core concepts.

2025 features A2A, graph workflows, declarative agents, OpenTelemetry.

Functional workflows @workflow, @step, RunContext HITL, as_agent(), checkpointing.

Advanced Azure AI Agents, production deployment patterns.

Recipes Copy-paste code for common scenarios.

Diagrams System architecture, lifecycle, orchestration.

Production guide Azure Container Apps, Kubernetes, CI/CD, compliance.

Class deep dives Vol. 1 Agent, RawAgent, FunctionTool, WorkflowBuilder, RunContext, InlineSkill, MCPStdioTool — 10 classes from source.

Class deep dives Vol. 2 FileHistoryProvider, AgentMiddleware, ChatMiddleware, FunctionMiddleware, CompactionProvider, ToolResultCompactionStrategy, TokenBudgetComposedStrategy, FileCheckpointStorage, LocalEvaluator, WorkflowRunResult — 10 more classes from source.

Class deep dives Vol. 3 (1.7.0) BackgroundAgentsProvider, MemoryContextProvider + MemoryFileStore, TodoProvider + TodoFileStore, AgentModeProvider, SummarizationStrategy, ContextWindowCompactionStrategy, SlidingWindowStrategy, SelectiveToolCallCompactionStrategy, WorkflowViz, MCPStreamableHTTPTool + MCPWebsocketTool — 10 classes source-verified at 1.7.0.

Class deep dives Vol. 4 (1.7.0) Message + Content, ChatOptions + ChatResponse + ChatResponseUpdate + UsageDetails, ResponseStream, AgentContext, FunctionalWorkflow + StepWrapper, WorkflowEvent taxonomy, SkillsSource composition layer, EvalItem + EvalResults + EvalScoreResult, TokenizerProtocol + CharacterEstimatorTokenizer, ConversationSplit + ConversationSplitter — 10 class groups source-verified at 1.7.0.

Class deep dives Vol. 5 (1.7.0) Executor + @handler + @executor, AgentExecutor + AgentExecutorRequest + AgentExecutorResponse, FanOutEdgeGroup + FanInEdgeGroup + SwitchCaseEdgeGroup, Runner + WorkflowMessage, SessionContext, AgentSession + register_state_type, BaseChatClient + SupportsChatGetResponse, SecretString + load_settings, WorkflowCheckpoint + CheckpointStorage, full exception hierarchy — 10 class groups source-verified at 1.7.0.

Class deep dives Vol. 6 (1.7.0) ExperimentalFeature + @experimental / @release_candidate, WorkflowRunState + WorkflowErrorDetails, WorkflowExecutor + SubWorkflow message pair, AgentResponse + AgentResponseUpdate + ContinuationToken, BaseEmbeddingClient + embedding type family, FunctionInvocationConfiguration, ClassSkill + SkillFrontmatter + FileSkillsSource + SkillsProvider, Annotation + TextSpanRegion, provider capability protocols (5 Supports* interfaces), MiddlewareType + AgentMiddlewareLayer + ChatMiddlewareLayer — 10 class groups source-verified at 1.7.0.

Class deep dives Vol. 7 (1.7.0) ContextProvider custom authoring, BackgroundTaskInfo + BackgroundTaskStatus, GroupChatBuilder + TerminationCondition + GroupChatSelectionFunction, HandoffBuilder + HandoffConfiguration (autonomous mode), MagenticBuilder + StandardMagenticManager + MagenticProgressLedger, SequentialBuilder + ConcurrentBuilder (fan-out/synthesise), AgentFactory + WorkflowFactory (declarative YAML), SecureAgentConfig + ContentLabel + IntegrityLabel + LabelTrackingFunctionMiddleware (prompt injection defence), FunctionalWorkflowAgent, ObservabilitySettings + configure_otel_providers — 10 class groups source-verified at 1.7.0.

Class deep dives Vol. 8 (1.8.0) AgentFileStore + FileSystemAgentFileStore + InMemoryAgentFileStore (file storage ABC + 2 backends), FileAccessProvider + FileSearchResult + FileSearchMatch (5-tool file workspace harness), MCPSkill + MCPSkillResource + MCPSkillsSource (MCP-native SEP-2640 skill discovery), ToolMode + validate_tool_mode (tool-choice TypedDict), AgentEvalConverter + ExpectedToolCall + CheckResult + RubricScore (evaluation helper layer), ChatContext (full chat-middleware context + stream hooks), WorkflowAgent + WorkflowContext (workflow-as-agent with typed generic context), TruncationStrategy (oldest-first token/message compaction), HistoryProvider + InMemoryHistoryProvider (history provider ABC + in-memory default), DelegatingSkillsSource + InMemorySkillsSource + FunctionInvocationContext + progressive tools — 10 class groups source-verified at 1.8.0.

Class deep dives Vol. 9 (1.8.0) OllamaChatClient + OllamaChatOptions (local LLM bridge), PurviewPolicyMiddleware + PurviewChatPolicyMiddleware + PurviewSettings (enterprise content compliance), DurableAIAgent + DurableAIAgentClient + DurableAIAgentWorker (durable workflow actors), GitHubCopilotAgent + GitHubCopilotOptions (Copilot routing), HyperlightExecuteCodeTool + AllowedDomain + FileMount (Wasm sandboxed code execution), HyperlightCodeActProvider (CodeAct context provider), Mem0ContextProvider (cloud semantic memory), RedisContextProvider + RedisHistoryProvider (Redis persistence), StandardMagenticManager + MagenticContext + MagenticProgressLedger (Magentic-One internals), FileSkillsSource + FilteringSkillsSource + AggregatingSkillsSource — 10 class groups source-verified at 1.8.0.

Class deep dives Vol. 10 (1.8.1) Workflow + InProcRunnerContext (graph execution engine; run(), as_agent(), as_tool()), FunctionExecutor (@executor decorator internals; explicit type override), FunctionInvocationLayer (tool-calling loop mixin for custom chat clients), MemoryStore + MemoryIndexEntry + MemoryTopicRecord (memory harness ABC + data model), TodoStore + TodoItem + TodoInput + TodoFileStore + TodoSessionStore (todo harness; file-backed and session-backed), DeduplicatingSkillsSource (first-one-wins deduplication), SkillsProvider (context provider; from_paths; instruction_template; require_script_approval), MCPTaskOptions (SEP-2663 long-running task lifecycle), InMemoryCheckpointStorage (test/dev checkpointing; save/load/delete/get_latest), EvalScoreResult + CompactionStrategy + BaseAgent (eval dimensions, custom compaction protocol, minimal agent base) — 10 class groups source-verified at 1.8.1.

Class deep dives Vol. 11 (1.8.1) AgentTelemetryLayer + ChatTelemetryLayer + EmbeddingTelemetryLayer (OTel mixin layer — AGENT_PROVIDER_NAME, token/duration histograms, sensitive telemetry toggle), Edge + EdgeGroup + SingleEdgeGroup + InternalEdgeGroup (workflow graph primitives — conditional routing, serialisation round-trip, EdgeGroup.register custom subclasses), Case + Default (runtime switch-case wrappers for add_switch_case_edge_group), EdgeRunner hierarchy (SingleEdgeRunner, FanOutEdgeRunner, FanInEdgeRunner, SwitchCaseEdgeRunner — EdgeGroupDeliveryStatus enum, buffer semantics, concurrent fan-out), ExecutionContext (sub-workflow tracking — HITL pending_requests / collected_responses / expected_response_count), WorkflowGraphValidator (7 pre-build checks: edge duplication, type compatibility, connectivity, self-loops, dead-ends, output validation — error taxonomy), MCPTool + MCPSpecificApproval (shared base for all 3 MCP transports — full constructor parameter table, per-tool result parsing, additional_tool_argument_names forwarding), SerializationMixin + SerializationProtocol (DTO round-trip foundation — DEFAULT_EXCLUDE, INJECTABLE, dependency injection patterns, custom serialisable tool), Evaluator + EvalItemResult + EvalNotPassedError (evaluation backend Protocol — custom evaluator implementation, CI gate pattern), PerServiceCallHistoryPersistingMiddleware (per-service-call history persistence — service_stores_history flag, sentinel conversation ID, audit logging use-cases) — 10 class groups source-verified at 1.8.1.

Class deep dives Vol. 12 (1.8.1) Skill + SkillResource + SkillScript ABCs (contract methods: get_content, get_resource, get_script, read, run, parameters_schema — custom skill backends), FileSkill (SKILL.md content cache, scripts XML block injection, case-insensitive resource/script lookup), InlineSkillResource + InlineSkillScript (static vs callable resources, mutual-exclusivity validation, in-process script execution, lazy auto-generated parameters_schema, _accepts_kwargs precomputation), FileSkillScript + SkillScriptRunner (file-backed scripts, fixed CLI array schema, async runner protocol, isinstance verification), SupportsAgentRun (structural protocol — custom agents without framework inheritance, isinstance guard, workflow and A2A integration), RunnerContext (full workflow execution context protocol — message routing, event pipeline, checkpointing API, streaming mode toggle, HITL request/response, custom test stub), SwitchCaseEdgeGroupCase + SwitchCaseEdgeGroupDefault (serialisable branch descriptors vs runtime Case/Default — condition_name auto-extraction, to_dict/from_dict round-trip, missing-callable placeholder, condition re-registration pattern), ValidationTypeEnum + WorkflowValidationError hierarchy (6 enum values, EdgeDuplicationError + edge_id, TypeCompatibilityError + source/target type lists, GraphConnectivityError, match-based dispatcher, custom reporting), A2AAgent + A2AAgentSession + A2AExecutor (URL/AgentCard/client init, dual streaming/non-streaming httpx clients, auth interceptors, timeout config, A2AAgentSession context_id/task_id/task_state round-trip, A2A server exposure with A2AExecutor + run_kwargs), WorkflowRunnerException + WorkflowCheckpointException + MiddlewareException (leaf exception classes — checkpoint I/O failure patterns, MiddlewareException vs MiddlewareTermination distinction, supervisor exception dispatcher) — 10 class groups source-verified at 1.8.1.

Class deep dives Vol. 13 (1.8.1) OpenAIChatClient + OpenAIChatOptions + OpenAISettings + RawOpenAIChatClient (agent_framework.openai — Responses API 4-layer MRO, STORES_BY_DEFAULT server-side state, x-ms-served-model Azure header, per-request reasoning options, Responses vs Completions comparison table), OpenAIChatCompletionClient + OpenAIChatCompletionOptions + RawOpenAIChatCompletionClient (Chat Completions API — logprobs, prediction, stateless design), OpenAIEmbeddingClient + OpenAIEmbeddingOptions + OpenAIContinuationToken + ContentFilterResultSeverity + OpenAIContentFilterException (embeddings+RAG+MemoryContextProvider, background polling, Azure content filter exception hierarchy), AnthropicClient + AnthropicChatOptions + RawAnthropicClient (agent_framework.anthropic — Anthropic Messages API, extended thinking ThinkingConfigEnabled, top_k, service_tier, additional_beta_flags per-request), ClaudeAgent + ClaudeAgentOptions + RawClaudeAgent (Claude Code CLI agent — allowed_tools/disallowed_tools, mcp_servers McpServerConfig, permission_mode, sandbox, multi-agent workflow participation), AnthropicFoundryClient + AnthropicBedrockClient + AnthropicVertexClient (multi-cloud Claude — Azure Foundry AAD token provider, Bedrock IAM profile, Vertex ADC/GoogleCredentials, multi-cloud failover pattern), GroupChatOrchestrator + AgentBasedGroupChatOrchestrator + GroupChatState + GroupChatRequestMessage + AgentOrchestrationOutput (orchestrations internals — function-driven vs LLM-driven selection, frozen GroupChatState snapshot, structured AgentOrchestrationOutput Pydantic model), HandoffAgentExecutor + HandoffAgentUserRequest + HandoffSentEvent + OrchestrationState (handoff internals — autonomous_mode + turn_limit, HITL create_response/terminate helpers, event observability, OrchestrationState to_dict/from_dict checkpoint), MagenticOrchestrator + MagenticAgentExecutor + MagenticOrchestratorEvent + MagenticPlanReviewRequest + MagenticPlanReviewResponse + MagenticProgressLedgerItem (Magentic deeper — outer/inner loop, MagenticResetSignal for replanning, plan signoff HITL approve/revise, ledger item serialisation), HttpRequestHandler + DefaultHttpRequestHandler + HttpRequestInfo + HttpRequestResult + MCPToolHandler + DefaultMCPToolHandler + MCPToolInvocation + MCPToolResult + ToolApprovalRequest + ToolApprovalResponse + ExternalInputRequest + ExternalInputResponse + AgentExternalInputRequest + AgentExternalInputResponse (declarative handlers — 3 construction modes for DefaultHttpRequestHandler, SSRF guard pattern, MCP LRU cache+LIST_TOOLS_TOOL_NAME discovery, tool approval gate, agent HITL) — 10 class groups source-verified at 1.8.1.

Class deep dives Vol. 14 (1.8.1) State (superstep cache — set/get/commit/discard/delete sentinel/export_state/import_state, BSP semantics, checkpoint integration), OutputDesignation (output routing rule — is_terminal/is_intermediate/classify, compatibility mode vs explicit output_from/intermediate_output_from), MessageType enum + WorkflowMessage (STANDARD vs RESPONSE, plural trace_contexts for fan-in OTel link propagation, to_dict/from_dict, backward-compat trace_context/source_span_id accessors), DictConvertible + encode_value (dict/JSON round-trip mixin — to_dict/from_dict/clone deep-shallow/to_json/from_json, recursive nested encoding), MiddlewareWrapper + BaseMiddlewarePipeline (callable→class adapter, has_middlewares gate, _register_middleware_with_wrapper auto-wrapping), AgentMiddlewarePipeline + ChatMiddlewarePipeline + FunctionMiddlewarePipeline (concrete pipelines — execute() for streaming/non-streaming, matches() cache-key check, MiddlewareTermination short-circuit), MiddlewareDict + categorize_middleware (TypedDict typed middleware bag — agent/function/chat buckets, callable type inference, multi-source merge), FunctionRequestResult TypedDict (action return/continue/stop, errors_in_a_row, result_message, function_call_count — tool-loop diagnostics), OtelAttr + MessageListTimestampFilter (GenAI semantic convention enum — all 35 attribute name constants; logging.Filter for 1µs timestamp offset ordering in log aggregators), PolicyEnforcementFunctionMiddleware + ConfidentialityLabel + ContentVariableStore + VariableReferenceContent + LabeledMessage + InspectVariableInput (IFC prompt-injection defence — variable indirection store, PUBLIC/PRIVATE/USER_IDENTITY confidentiality, block vs approval_on_violation modes, audit_log, SecureAgentConfig one-liner) — 10 class groups source-verified at 1.8.1.

Class deep dives Vol. 15 (1.8.1) AGUIChatClient + AGUIEventConverter + AGUIHttpService (AG-UI streaming stateful UI protocol — run(), stateless mode, SSE event delivery, per-session converter requirement), AgentFrameworkAgent + AgentFrameworkWorkflow + state_update() + add_agent_framework_fastapi_endpoint() (FastAPI/Teams hosting — pending-approval registry max 10,000, tags+dependencies params, CORS, env-var wiring), ThreadItemConverter + simple_to_agent_input() + stream_agent_response() (ChatKit thread-item streaming — multimodal ThreadItem mapping, delta merging), DevServer + serve() + register_cleanup() (local OpenAI-compatible debug server — multi-agent dict, CORS removed as security fix, graceful teardown), GAIA + GAIATelemetryConfig + TaskRunner + TaskResult + Prediction + Evaluation (GAIA benchmark lab — telemetry via GAIA(telemetry_config=...), async callable TaskRunner.__call__(), is_correct + score aggregation; install: agent-framework-lab), CopilotStudioAgent (Copilot Studio bridge — env-var prefix COPILOTSTUDIOAGENT__, propagate_session as_tool option), AzureAISearchContextProvider (semantic/agentic retrieval — env-var prefix AZURE_SEARCH_, top_k/semantic_configuration_name, retrieval_reasoning_effort: minimal|low|medium), CosmosHistoryProvider (Cosmos DB history — env-var prefix AZURE_COSMOS_, store_context_messages, store_context_from set), DurableAIAgentClient + DurableAIAgentWorker + DurableAIAgentOrchestrationContext + AgentCallbackContext + AgentResponseCallbackProtocol (durable task hosting — get_agent().run() blocking poll, yield Task in orchestration, add_agent() callback), AgentFunctionApp (Azure Functions serverless — agents=[]/workflow= init, enable_http_endpoints, enable_mcp_tool_trigger, enable_health_check) — 10 class groups source-verified at 1.8.1.

Class deep dives Vol. 16 (1.8.1) FoundryAgent + FoundryAgentOptions + RawFoundryAgent + RawFoundryAgentChatClient (hosted Azure AI Foundry agents — PromptAgent requires agent_version, HostedAgent uses allow_preview + isolation_key, client_type override for raw chat client), FoundryLocalClient + FoundryLocalChatOptions + FoundryLocalSettings (on-device LLM via Foundry Local SDK — bootstrap, prepare_model, device NPU/GPU/CPU auto-detect, FOUNDRY_LOCAL_MODEL env var, structured output), FoundryMemoryProvider (Azure AI Foundry Memory Store semantic memory context provider — memory_store_name, scope, update_delay, before_run search + after_run async write lifecycle), FoundryEvals + GeneratedEvaluatorRef + evaluate_foundry_target + evaluate_traces (Foundry cloud evaluation harness — 19 built-in evaluator name constants, smart defaults, tool_call_accuracy auto-added for tool-using agents, poll_interval, GeneratedEvaluatorRef for rubric evaluators), BedrockChatClient + BedrockChatOptions + BedrockGuardrailConfig + BedrockSettings (Amazon Bedrock Converse API — BEDROCK_REGION/BEDROCK_CHAT_MODEL env vars, guardrailConfig TypedDict, sync/async streamProcessingMode, unsupported-options table), BedrockEmbeddingClient + BedrockEmbeddingOptions + BedrockEmbeddingSettings (Bedrock Titan Embeddings v2 — BEDROCK_EMBEDDING_MODEL, normalize flag for unit-length vectors, MemoryContextProvider wiring), MagenticManagerBase (abstract base for custom Magentic managers — plan/replan/create_progress_ledger/prepare_final_answer abstract methods, max_stall_count/max_reset_count/max_round_count, on_checkpoint_save/restore hooks, wiring with MagenticBuilder), BaseGroupChatOrchestrator + GroupChatRequestSentEvent + GroupChatResponseReceivedEvent (group chat orchestrator base class — max_rounds coercion to ≥1, 4 @handler overloads for str/Message/list/response, event observability via dataclasses, TerminationCondition support), AgentRequestInfoResponse + CacheProvider (HITL approval data model — approve()/from_messages()/from_strings() static factories; CacheProvider async get/set/remove Protocol for Purview cache injection), Purview exception hierarchy + acquire_token (PurviewAuthenticationError 401/403, PurviewPaymentRequiredError 402, PurviewRateLimitError 429, PurviewRequestError other 4xx/5xx, PurviewServiceError base; acquire_token MSAL silent-then-interactive flow, custom scopes, on-disk SerializableTokenCache pattern) — 10 class groups source-verified at 1.8.1.

Class deep dives Vol. 17 (1.9.0) ToolApprovalMiddleware + ToolApprovalRule + ToolApprovalState (interactive tool approval — standing rules, argument wildcard matching, queue drain logic, SerializationMixin round-trip), AgentLoopMiddleware + JudgeVerdict + todos_remaining + background_tasks_running (LLM-judged self-improvement loops — fresh_context snapshot/restore, inject_progress, with_judge criteria placeholder, return_final_only aggregation), SamplingApprovalCallback + MCP sampling security (confused-deputy mitigation — deny-by-default callback, token cap, per-connection request counter, async callback support), to_prompt_agent (Foundry PromptAgent publisher — @experimental, RawFoundryChatClient required, model resolution order, local MCP raises ValueError), FoundryEmbeddingClient + FoundryEmbeddingOptions + FoundryEmbeddingSettings + RawFoundryEmbeddingClient (multimodal text+image embeddings — mixed batch split/reassemble, image detection via MIME prefix, image_model precedence, async context manager), ContentUnderstandingContextProvider + AnalysisSection + DocumentStatus (Azure Content Understanding — MEDIA_TYPE_ANALYZER_MAP auto-detect, before_run lifecycle, deferred vs blocking analysis, auto-registered list_documents tool), FileSearchConfig + FileSearchBackend + OpenAIFileSearchBackend + FoundryFileSearchBackend (vector store upload/delete backends — _OpenAICompatBackend shared surface, create_and_poll indexing wait, custom backend example), AgentFrameworkTracer (Agent Lightning OTel bridge — OBSERVABILITY_SETTINGS singleton toggle, init/teardown lifecycle order), TaskRunner + patch_env_set_state + unpatch_env_set_state (Tau2 airline benchmark harness — three-part conversation assembly, reinit() chaining, termination reasons, EvaluationType.ALL reward calculation), 8 new FoundryChatClient hosted tool factories (get_mcp_tool, get_azure_ai_search_tool, get_sharepoint_tool, get_fabric_tool, get_memory_search_tool, get_computer_use_tool, get_browser_automation_tool, get_a2a_tool — validation rules, hosted vs local MCP distinction) — 10 class groups source-verified at agent-framework 1.9.0.

Class deep dives Vol. 18 (1.9.0) Skill + SkillFrontmatter + SkillScriptRunner (Agent Skills spec — name/description/compatibility validation, file-script runner protocol, SkillFrontmatter from_yaml, custom Skill subclass), InlineSkill (@skill.resource/@skill.script decorators — XML content synthesis, _accepts_kwargs precomputation, content caching, lazy parameters_schema), InMemorySkillsSource + AggregatingSkillsSource + FilteringSkillsSource + DeduplicatingSkillsSource (skills pipeline — fan-in, predicate filter, first-one-wins dedup, shared pipeline factory), AgentFileStore + InMemoryAgentFileStore + FileSearchMatch + FileSearchResult (file storage ABC + in-memory backend — exclusive-create asyncio.Lock, __slots__ DTOs, custom Azure Blob backend), FileAccessProvider (6-tool file workspace — save/read/delete/list/search, require_delete_approval gate, shared across sessions), BackgroundAgentsProvider + BackgroundTaskInfo + BackgroundTaskStatus (background sub-agent delegation — asyncio.Task fan-out, continue_task session resume, LOST status on process restart), MemoryStore + MemoryTopicRecord + MemoryIndexEntry (durable memory backing store ABC — Markdown serialization, slug normalization, pointer line rendering, custom dict-backed store), WorkflowGraphValidator + EdgeDuplicationError + GraphConnectivityError + TypeCompatibilityError (7-check pre-build validation — DFS reachability, self-loop warnings, FanIn list-wrapping type check, full error taxonomy), MagenticBuilder + MagenticManagerBase + MagenticProgressLedger + MagenticProgressLedgerItem (Magentic One internals — 5-item progress ledger, abstract plan/replan/create_progress_ledger/prepare_final_answer, custom manager example), LocalEvaluator + EvalItem + EvalScoreResult + ConversationSplit + ExpectedToolCall (local evaluation framework — per_turn_items, LAST_TURN/FULL splits, @evaluator custom checks, evaluate_agent end-to-end) — 10 class groups source-verified at agent-framework 1.9.0.

Class deep dives Vol. 19 (1.9.0) ConcurrentBuilder (fan-out/fan-in — with_aggregator sync/async callback, output_from/intermediate_output_from routing, with_request_info, checkpoint), SequentialBuilder (shared-conversation chain — chain_only_agent_responses, output_from, with_request_info per-agent filter, checkpoint), HandoffBuilder + HandoffConfiguration + HandoffSentEvent (decentralised routing — add_handoff graph, with_start_agent, with_autonomous_mode per-agent turn limits, output_from, event observability), HandoffAgentUserRequest (HITL factories — create_response str/Message/list, terminate), OrchestrationState (unified checkpoint dataclass — conversation/round_index/metadata/task, to_dict/from_dict, pattern-specific extension), AgentModeProvider + get_agent_mode + set_agent_mode (plan/execute mode harness — mode_descriptions Mapping, {available_modes}/{current_mode} template, default_mode, external-change notification), TodoItem + TodoInput + TodoCompleteInput (DTO primitives — SerializationMixin, stripping/validation, __eq__/__repr__), TodoStore + TodoSessionStore + TodoFileStore (backing store ABC — session state, file JSON with path-traversal guard, Windows reserved name encoding, custom backend), TodoProvider (5-tool harness — todos_add/complete/remove/get_remaining/get_all, per-session asyncio.Lock via WeakKeyDictionary, combined with AgentModeProvider), MagenticResetSignal + StandardMagenticManager (stall-recovery sentinel + 7 prompt overrides, max_stall/reset/round_count, progress_ledger_retry_count, observe REPLANNED events) — 10 class groups source-verified at agent-framework 1.9.0.

Class deep dives Vol. 20 (1.9.0) 6 hosted-tool capability Protocols (SupportsCodeInterpreterTool, SupportsWebSearchTool, SupportsImageGenerationTool, SupportsMCPTool, SupportsFileSearchTool, SupportsShellTool — @runtime_checkable isinstance guards + factory method signatures), SupportsGetEmbeddings (typed embedding duck-typing Protocol — get_embeddings Generic params, custom client example), ReleaseCandidateFeature + FeatureStageWarning + ExperimentalWarning (feature staging — _WARNED_FEATURES deduplication, single-line formatter install, pytest filter patterns), EmbeddingGenerationOptions + Embedding + GeneratedEmbeddings (embedding DTOs — TypedDict options, Generic[T] vector type, list[Embedding] subclass with usage+options), WorkflowEventSource (EXECUTOR vs FRAMEWORK str-Enum — OTel span attribute, match pattern), SubWorkflowRequestMessage + SubWorkflowResponseMessage (hierarchical HITL bridge — create_response with isinstance type check, executor_id for multi-instance routing), RequestInfoMixin + response_handler decorator (executor-level HITL wiring — handler discovery via _discover_response_handlers, introspection vs explicit type modes, forward reference support, is_request_supported guard), WorkflowAgent.RequestInfoFunctionArgs (HITL tool-call serialization dataclass — to_dict/from_dict round-trip, empty request_id ValueError, REQUEST_INFO_FUNCTION_NAME sentinel constant), EdgeGroupDeliveryStatus (OTel edge-delivery enum — DELIVERED/BUFFERED/DROPPED_TYPE_MISMATCH/DROPPED_CONDITION_FALSE/DROPPED_TARGET_MISMATCH/EXCEPTION, span processor aggregation), IntegrityLabel + LabelTrackingFunctionMiddleware (IFC security @experimental — TRUSTED/UNTRUSTED integrity enum, 3-tier label propagation priority table, variable indirection auto-hide, get_security_tools + reset_context_label + list_variables), MiddlewareTermination + WorkflowConvergenceException (MiddlewareTermination.result early-return payload; WorkflowConvergenceException.inner_exception + log_level=DEBUG) — 10 class groups source-verified at agent-framework 1.9.0.

Class deep dives Vol. 21 (1.9.0) WorkflowContext[OutT, W_OutT] (per-executor execution context — send_message/yield_output/request_info API, state R/W with commit/discard, source_executor_ids fan-in list, is_streaming flag), FanInEdgeGroup + FanOutEdgeGroup (converging/broadcasting edge groups — min_sources/min_targets validation, selection_func dynamic routing, to_dict/from_dict serialization), SwitchCaseEdgeGroup + SwitchCaseEdgeGroupCase + SwitchCaseEdgeGroupDefault (switch/case routing — sequential predicate evaluation, exactly-one-default invariant, missing-condition placeholder, condition re-registration), TokenBudgetComposedStrategy (multi-strategy composition — early_stop short-circuit, annotate_message_groups pipeline pass-through, strict-budget double-fallback), SelectiveToolCallCompactionStrategy + ToolResultCompactionStrategy (tool history reduction — exclude list vs inline summary replacement, keep_last_tool_call_groups sliding retention), SlidingWindowStrategy + SummarizationStrategy (sliding window + LLM-backed summarization — preserve_system, target_count+threshold trigger, bidirectional summary trace metadata), StepWrapper + FunctionalWorkflow + RunContext (functional workflow internals — per-step caching by call_index, executor_bypassed on cache hit, checkpoint_storage per step, as_agent() wrapper), MCPWebsocketTool + MCPStreamableHTTPTool (MCP network transports — WebSocket wss:// reconnect loop, streamable HTTP/SSE with header_provider ContextVar injection), MCPTaskOptions (SEP-2663 long-running task lifecycle — tasks/call → tasks/get polling → tasks/result, default_ttl validation, max_task_wait, cancel_remote_task_on_local_cancellation), AgentResponseUpdate + ChatResponseUpdate + ContinuationToken (streaming chunk types — .text property, continuation_token for background polling resumption, author_name in multi-agent streams, finish_reason) — 10 class groups source-verified at agent-framework 1.9.0.

azure-ai-agents integration — class reference Vol. 1 Add-on: AgentsClient, FunctionTool, ToolSet, CodeInterpreterTool, FileSearchTool, BingGroundingTool, ConnectedAgentTool, AgentEventHandler, ThreadMessage, OpenApiTool — 10 source-verified classes.

azure-ai-agents integration — class reference Vol. 3 Add-on: AsyncFunctionTool, AzureFunctionTool, AzureAISearchTool, VectorStore, ThreadRun, RunStep, ResponseFormatJsonSchema, TruncationObject, MessageAttachment, AsyncAgentEventHandler — 10 source-verified classes.

azure-ai-agents integration — class reference Vol. 4 Add-on: enable_auto_function_calls, create_thread_and_process_run, FunctionTool, ToolSet, CodeInterpreterTool, FileSearchTool+VectorStore, AzureAISearchTool, BingGroundingTool, ConnectedAgentTool, AgentEventHandler, AsyncToolSet — 10 source-verified patterns.

azure-ai-agents integration — class reference Vol. 5 Add-on: Agent model, AgentThread, ToolOutput, VectorStoreFileBatch + VectorStoreFileCount, VectorStoreFile + VectorStoreFileError, FileInfo, MessageDeltaChunk, RunStepDeltaChunk, SubmitToolOutputsAction, AgentRunStream + AgentEventHandler — 10 data model and streaming classes from source.

azure-ai-agents integration — class reference Vol. 6 Add-on: OpenAPI auth hierarchy, BingGroundingSearchConfiguration, RunCompletionUsage, VectorStoreDataSource + VectorStoreConfigurations, expiry + chunking strategies, AgentsNamedToolChoice, file-search run step results, streaming event taxonomy, RequiredFunctionToolCall manual dispatch, multimodal ThreadMessageOptions — 40+ classes source-verified at 1.1.0.

What’s shipped (June 2026 introspection)

• Stable core APIs — agent-framework-core 1.9.0. Upgraded from 1.8.1 on 2026-06-19. All public symbols verified against installed agent-framework==1.9.0; 275 total public symbols (+14 vs 1.8.1). New in 1.9.0: ToolApprovalMiddleware, ToolApprovalRule, ToolApprovalState, AgentLoopMiddleware, JudgeVerdict, todos_remaining, background_tasks_running, SamplingApprovalCallback, to_prompt_agent, FoundryEmbeddingClient, FoundryEmbeddingOptions, FoundryEmbeddingSettings, RawFoundryEmbeddingClient, plus 8 new FoundryChatClient hosted tool factory methods. See Class Deep Dives Vol. 17 for source-verified coverage of all new 1.9.0 symbols. Previously stable in 1.8.1: 261 total public symbols. Previously new in 1.8.0: AgentFileStore, FileSystemAgentFileStore, InMemoryAgentFileStore, FileAccessProvider, FileSearchResult, FileSearchMatch, MCPSkill, MCPSkillResource, MCPSkillsSource, ToolMode, AgentEvalConverter, CheckResult, ExpectedToolCall, RubricScore, ChatContext, WorkflowAgent, WorkflowContext, TruncationStrategy, HistoryProvider, InMemoryHistoryProvider, DelegatingSkillsSource, InMemorySkillsSource, FunctionInvocationContext, FunctionInvocationLayer. See Class Deep Dives Vol. 8 and Vol. 10 for source-verified coverage.
• First-party chat clients — agent_framework.foundry.FoundryChatClient, agent_framework.openai.OpenAIChatClient, agent_framework.anthropic.AnthropicClient, plus Bedrock / Ollama in the 1.0.0b provider line.
• Skills (experimental) — MemoryStore, SkillResource, InlineSkillResource, ClassSkill, InlineSkill, FileSkill now emit ExperimentalWarning on import — do not depend on these APIs in production yet.
• Middleware — @chat_middleware / @agent_middleware / @function_middleware decorators and base classes; pass middleware=[...] (must be a list in 2026 releases).
• Workflows — WorkflowBuilder with .add_edge / .add_chain / .add_fan_in_edges / .add_fan_out_edges / .add_switch_case_edge_group / .add_multi_selection_edge_group; checkpoint via FileCheckpointStorage / InMemoryCheckpointStorage.
• Functional workflows (experimental) — @workflow / @step decorators and RunContext for HITL and state — write workflows as plain async Python functions without graph wiring.
• Declarative agents (beta) — agent_framework.declarative.AgentFactory / WorkflowFactory load from YAML.
• A2A (beta) — one class, agent_framework.a2a.A2AAgent, wraps a remote A2A endpoint as a local Agent.

Breaking changes in 2026 releases

• display_name parameter removed from agents.
• middleware= now requires a list — no longer accepts a single instance.
• AgentRunResponse / AgentRunResponseUpdate renamed to AgentResponse / AgentResponseUpdate.
• AggregateContextProvider removed — compose ContextProvider instances directly.
• context_providers stays plural in agent-framework-core==1.5.0 (verified against source). An earlier draft of this guide incorrectly said it was renamed to singular.
• output_executors= in WorkflowBuilder is deprecated in 1.5.0 — replace with output_from=. The old parameter still works but emits a warning.
• Migrating from standalone Semantic Kernel or AutoGen? See the official guide — ~2–4 hours for a typical app.

Install, minimal example

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

async def main():
    agent = Agent(
        client=OpenAIChatClient(),          # positional or keyword
        instructions="You are a helpful assistant.",
    )
    response = await agent.run("What is the Microsoft Agent Framework?")
    print(response.text)

asyncio.run(main())

Previous drafts of this page used a ChatAgent(chat_client=...) minimal example. ChatAgent is not a public class in agent-framework-core 1.4.0 — the primary agent class is Agent and the keyword is client= (not chat_client=).

Ready for the full walk-through? Start with Core Fundamentals →

---

Revision history

Date	Version	Changes
2026-06-23	1.2.8	Added Class Deep Dives Vol. 21 (source-verified at agent-framework==1.9.0): WorkflowContext[OutT, W_OutT] (per-executor execution context — send_message/yield_output/request_info API, state R/W with commit/discard, source_executor_ids fan-in list, is_streaming flag, current_agent_name); FanInEdgeGroup + FanOutEdgeGroup (converging/broadcasting edge groups — min_sources/min_targets positive-value validation, selection_func dynamic routing callback, to_dict/from_dict serialization round-trip); SwitchCaseEdgeGroup + SwitchCaseEdgeGroupCase + SwitchCaseEdgeGroupDefault (switch/case routing — sequential predicate evaluation, exactly-one-default invariant, missing-condition placeholder raises RuntimeError on call, condition re-registration pattern); TokenBudgetComposedStrategy (multi-strategy composition — early_stop short-circuit, annotate_message_groups pipeline pass-through, strict-budget double-fallback with final truncation); SelectiveToolCallCompactionStrategy + ToolResultCompactionStrategy (tool history reduction — exclude list vs inline summary replacement, keep_last_tool_call_groups sliding retention, exclude_tools/include_tools selector); SlidingWindowStrategy + SummarizationStrategy (sliding window + LLM-backed summarization — preserve_system, target_count+threshold trigger, bidirectional summary trace metadata injection); StepWrapper + FunctionalWorkflow + RunContext (functional workflow internals — per-step caching by call_index, executor_bypassed event on cache hit, checkpoint_storage per step, as_agent() wrapper, RunContext.set_state/get_state); MCPWebsocketTool + MCPStreamableHTTPTool (MCP network transports — WebSocket wss:// reconnect loop, streamable HTTP/SSE with header_provider ContextVar injection, shared MCPTool base); MCPTaskOptions (SEP-2663 long-running task lifecycle — tasks/call → tasks/get polling → tasks/result, default_ttl positive-value validation, max_task_wait, cancel_remote_task_on_local_cancellation, fire-and-forget pattern); AgentResponseUpdate + ChatResponseUpdate + ContinuationToken (streaming chunk types — .text property, continuation_token for background polling resumption, author_name in multi-agent streams, finish_reason). Zero→Hero extended to step 43; Jump-to-topic, Zero→Hero, and Reference grids updated. Description bumped to 21 volumes / 220+ classes.
2026-06-22	1.2.7	Added Class Deep Dives Vol. 20 (source-verified at agent-framework==1.9.0): 6 hosted-tool capability Protocols (SupportsCodeInterpreterTool, SupportsWebSearchTool, SupportsImageGenerationTool, SupportsMCPTool, SupportsFileSearchTool, SupportsShellTool — all @runtime_checkable, provider-agnostic isinstance guard + factory method call patterns, custom client satisfying multiple Protocols); SupportsGetEmbeddings (typed embedding duck-typing Protocol — get_embeddings with contravariant input TypeVar, covariant EmbeddingT, opaque EmbeddingProtocolOptionsT, additional_properties required attribute, isinstance guard); ReleaseCandidateFeature + FeatureStageWarning + ExperimentalWarning (feature staging system — _WARNED_FEATURES set deduplication per (category, feature_id), _install_feature_stage_formatter single-line formatter, ExperimentalWarning subclasses FeatureStageWarning subclasses FutureWarning, ReleaseCandidateFeature empty in 1.9.0, _FEATURE_STAGE_ATTR/_FEATURE_ID_ATTR runtime introspection, pytest filterwarnings("error", ...) CI pattern); EmbeddingGenerationOptions + Embedding[T] + GeneratedEmbeddings[T, O] (embedding DTO layer — EmbeddingGenerationOptions TypedDict with model/dimensions, Embedding Generic dimensions auto-computed from len(vector), GeneratedEmbeddings extends list[Embedding[T]] with options/usage/additional_properties, cosine similarity and int8 quantization examples); WorkflowEventSource (EXECUTOR vs FRAMEWORK str-Enum — travels in WorkflowEvent.source, OTel span attribute usage, match dispatch pattern); SubWorkflowRequestMessage + SubWorkflowResponseMessage (@dataclass hierarchical HITL bridge — create_response(data) validates isinstance(data, source_event.response_type) raises TypeError, executor_id for multi-instance parent routing, WorkflowExecutor auto-appends SubWorkflowRequestMessage to output types); RequestInfoMixin + response_handler decorator (_discover_response_handlers scans class at Executor.__init__, is_request_response_capable bool, is_request_supported(request_type, response_type), response_handler introspection vs explicit type mode with string forward reference support, duplicate (request_type, response_type) raises ValueError); WorkflowAgent.RequestInfoFunctionArgs (nested @dataclass — request_id/request_event fields, to_dict()/from_dict() JSON round-trip, from_dict raises ValueError on missing fields or empty request_id, REQUEST_INFO_FUNCTION_NAME = "request_info" class constant, middleware interceptor pattern); EdgeGroupDeliveryStatus (Enum with 6 members: DELIVERED/BUFFERED/DROPPED_TYPE_MISMATCH/DROPPED_CONDITION_FALSE/DROPPED_TARGET_MISMATCH/EXCEPTION — OTel SpanProcessor aggregation, production exception delivery alert); IntegrityLabel + LabelTrackingFunctionMiddleware (@experimental(FIDES) — IntegrityLabel.TRUSTED/UNTRUSTED str-Enum, 3-tier priority table for label propagation (embedded > source_integrity > input join), LabelTrackingFunctionMiddleware(default_integrity, default_confidentiality, auto_hide_untrusted=True, hide_threshold), get_context_label()/reset_context_label()/get_security_tools()/list_variables()/get_variable_metadata(var_id)); MiddlewareTermination + WorkflowConvergenceException (MiddlewareTermination(message, *, result=None) raises to short-circuit middleware chain with optional early-return payload; WorkflowConvergenceException(message, inner_exception, log_level=10) raised when runner exceeds max iterations — blocklist middleware example, production convergence guard). Zero→Hero extended to step 42; Jump-to-topic, Zero→Hero, and Reference grids updated. Description bumped to 20 volumes / 210+ classes.
2026-06-19	1.2.6	Upgraded agent-framework 1.8.1 → 1.9.0 (275 total public symbols; +14 new). Added Class Deep Dives Vol. 17 (source-verified at agent-framework==1.9.0): ToolApprovalMiddleware + ToolApprovalRule + ToolApprovalState + helper functions (create_always_approve_tool_response, create_always_approve_tool_with_arguments_response) — interactive tool approval gate with standing rules, argument wildcard matching (arguments=None), no-argument rule (arguments={}), server_label scoping for hosted tools, SerializationMixin round-trip; AgentLoopMiddleware + JudgeVerdict + todos_remaining + background_tasks_running — LLM-judged self-improvement loop with DEFAULT_MAX_ITERATIONS=10, DEFAULT_JUDGE_MAX_ITERATIONS=5, JUDGE_VERDICT_DONE/JUDGE_VERDICT_MORE sentinels, fresh_context snapshot via to_dict(), inject_progress session vs. no-session behaviour, with_judge class method with CRITERIA_PLACEHOLDER="{{criteria}}", return_final_only=False aggregation; SamplingApprovalCallback + new MCP sampling security parameters — confused-deputy mitigation, deny-by-default, token cap, per-connection request counter, async callback support; to_prompt_agent (@experimental(feature_id=ExperimentalFeature.TO_PROMPT_AGENT)) — raises TypeError if client is not RawFoundryChatClient, model resolved from agent.default_options.get("model") or agent.client.model, local MCPTool instances raise ValueError; FoundryEmbeddingClient + FoundryEmbeddingOptions + FoundryEmbeddingSettings + RawFoundryEmbeddingClient — multimodal text+image embeddings, mixed batch split/reassemble, image detection via "image/" MIME prefix, image_model precedence, env vars FOUNDRY_EMBEDDING_MODEL/FOUNDRY_IMAGE_EMBEDDING_MODEL/FOUNDRY_MODELS_ENDPOINT; ContentUnderstandingContextProvider + AnalysisSection + DocumentStatus (agent-framework-azure-contentunderstanding package) — MEDIA_TYPE_ANALYZER_MAP auto-detect analyzer, DocumentStatus ANALYZING/UPLOADING/READY/FAILED enum, deferred=True for background analysis, auto-registered list_documents tool; FileSearchConfig + FileSearchBackend + OpenAIFileSearchBackend + FoundryFileSearchBackend — FileSearchConfig.from_openai()/from_foundry() static factories, _OpenAICompatBackend shared upload/delete surface, create_and_poll indexing wait, custom backend ABC; AgentFrameworkTracer (agent_framework.lab.lightning) — AgentOpsTracer subclass, OBSERVABILITY_SETTINGS.enable_otel toggle in init()/teardown() lifecycle; TaskRunner + patch_env_set_state + unpatch_env_set_state (agent_framework.lab.tau2) — three-part conversation assembly (initial greeting + full message store + final user message), reinit() returns self, TerminationReason.MAX_STEPS/AGENT_STOP/USER_STOP/TOO_MANY_ERRORS, evaluate() via EvaluationType.ALL; 8 new FoundryChatClient hosted tool factory methods (get_mcp_tool, get_azure_ai_search_tool, get_sharepoint_tool, get_fabric_tool, get_memory_search_tool, get_computer_use_tool, get_browser_automation_tool, get_a2a_tool) — each with validation rules and hosted vs. local MCP distinction. Zero→Hero extended to step 39; Jump-to-topic and Reference grids updated. Version card and description bumped to 1.9.0.
2026-06-18	1.2.5	Added Class Deep Dives Vol. 16 (source-verified at agent-framework==1.8.1): FoundryAgent + FoundryAgentOptions + RawFoundryAgent + RawFoundryAgentChatClient (agent_framework.foundry hosted agents — PromptAgent requires agent_version, HostedAgent uses allow_preview=True, isolation_key per-session typed option, client_type=RawFoundryAgentChatClient override pattern), FoundryLocalClient + FoundryLocalChatOptions + FoundryLocalSettings (on-device LLM via Foundry Local SDK — bootstrap, prepare_model, device NPU/GPU/CPU, FOUNDRY_LOCAL_MODEL env var, structured Pydantic output via response_format=), FoundryMemoryProvider (Azure AI Foundry Memory Store semantic memory context provider — memory_store_name/scope/update_delay, DEFAULT_SOURCE_ID="foundry_memory", before_run search + after_run async write lifecycle, async context manager for AIProjectClient ownership), FoundryEvals + GeneratedEvaluatorRef + evaluate_foundry_target + evaluate_traces (Foundry cloud eval harness — 19 source-verified built-in evaluator name constants across agent-behavior/tool-usage/quality/safety categories, smart default relevance+coherence+task_adherence, auto-add tool_call_accuracy when tools present, poll_interval=5.0/timeout=180.0, GeneratedEvaluatorRef(name=..., version=...) for rubric evaluators), BedrockChatClient + BedrockChatOptions + BedrockGuardrailConfig + BedrockSettings (Amazon Bedrock Converse API — BEDROCK_REGION default "us-east-1", BEDROCK_CHAT_MODEL env var, BedrockGuardrailConfig TypedDict: guardrailIdentifier/guardrailVersion/trace/streamProcessingMode; 8 unsupported options declared as None typed), BedrockEmbeddingClient + BedrockEmbeddingOptions + BedrockEmbeddingSettings (Bedrock Titan Embeddings v2 — OTEL_PROVIDER_NAME="aws.bedrock", BEDROCK_EMBEDDING_MODEL env var, normalize: bool for unit-length vectors, MemoryContextProvider wiring pattern), MagenticManagerBase (abstract base for custom Magentic-One managers — 4 abstract methods: plan/replan/create_progress_ledger/prepare_final_answer; max_stall_count=3/max_reset_count/max_round_count; on_checkpoint_save()→dict/on_checkpoint_restore(state) checkpoint hooks; wire with MagenticBuilder(manager=...)), BaseGroupChatOrchestrator + GroupChatRequestSentEvent + GroupChatResponseReceivedEvent (group chat abstract base — max_rounds coerced to max(1, max_rounds), TERMINATION_CONDITION_MET_MESSAGE/MAX_ROUNDS_MET_MESSAGE class constants, 4 @handler overloads: str/Message/list[Message]/AgentExecutorResponse; GroupChatRequestSentEvent(round_index, participant_name) + GroupChatResponseReceivedEvent(round_index, participant_name) observability dataclasses), AgentRequestInfoResponse + CacheProvider (AgentRequestInfoResponse HITL approval data model — approve() pass-through / from_messages(list[Message]) / from_strings(list[str]) static factories; CacheProvider async get/set(ttl_seconds)/remove Protocol for Purview cache injection; in-memory test implementation pattern), Purview exception hierarchy + acquire_token (PurviewAuthenticationError 401/403 ← IntegrationInvalidAuthException, PurviewPaymentRequiredError 402, PurviewRateLimitError 429, PurviewRequestError other HTTP, PurviewServiceError base ← IntegrationException; acquire_token() MSAL PublicClientApplication silent-then-interactive flow, custom scopes, SerializableTokenCache on-disk pattern, exponential back-off retry). Zero→Hero extended to step 38; Jump-to-topic and Reference grids updated.
2026-06-17	1.2.4	Added Class Deep Dives Vol. 15 (source-verified at agent-framework==1.8.1): AGUIChatClient + AGUIEventConverter + AGUIHttpService (AG-UI streaming stateful UI protocol — run(), stateless mode, SSE event delivery, per-session AGUIEventConverter instantiation requirement), AgentFrameworkAgent + AgentFrameworkWorkflow + state_update() + add_agent_framework_fastapi_endpoint() (FastAPI/Teams hosting — pending-approval registry max 10,000, tags/dependencies params, CORS, env-var wiring), ThreadItemConverter + simple_to_agent_input() + stream_agent_response() (ChatKit thread-item streaming — multimodal ThreadItem mapping, delta merging), DevServer + serve() + register_cleanup() (local OpenAI-compatible debug server — multi-agent dict, CORS removed as security fix, graceful teardown via register_cleanup; install: agent-framework[devui]), GAIA + GAIATelemetryConfig + TaskRunner + TaskResult + Prediction + Evaluation (GAIA benchmark lab — telemetry via GAIA(telemetry_config=...), async callable TaskRunner.__call__(), TaskResult.prediction + Evaluation.is_correct; install: agent-framework-lab), CopilotStudioAgent (Copilot Studio bridge — env-var prefix COPILOTSTUDIOAGENT__, propagate_session as_tool param), AzureAISearchContextProvider (semantic/agentic retrieval — env-var prefix AZURE_SEARCH_, top_k/semantic_configuration_name params, retrieval_reasoning_effort "minimal"/"low"/"medium"), CosmosHistoryProvider (Cosmos DB-backed history — env-var prefix AZURE_COSMOS_, store_context_messages, store_context_from), DurableAIAgentClient + DurableAIAgentWorker + DurableAIAgentOrchestrationContext + AgentCallbackContext + AgentResponseCallbackProtocol (durable task hosting — get_agent().run() blocking poll, yield Task not AgentResponse, add_agent() callback), AgentFunctionApp (Azure Functions serverless — agents=[]/workflow= init, enable_http_endpoints, enable_mcp_tool_trigger, enable_health_check). Zero→Hero extended to step 37; Jump-to-topic and Reference grids updated.
2026-06-16	1.2.3	Added Class Deep Dives Vol. 14 (source-verified at agent-framework==1.8.1): State (superstep-caching workflow state — set()/get()/commit()/discard()/delete() deletion sentinel/export_state()/import_state(), BSP visibility model, checkpoint integration), OutputDesignation (output routing rule — is_terminal()/is_intermediate()/classify(), compatibility mode when outputs=None, output_from=/intermediate_output_from= wiring), MessageType enum + WorkflowMessage enhanced coverage (STANDARD vs RESPONSE classification, plural trace_contexts/source_span_ids for fan-in OTel link propagation, to_dict()/from_dict() round-trip, backward-compat .trace_context/.source_span_id accessors), DictConvertible + encode_value (dict/JSON round-trip mixin — to_dict()/from_dict()/clone(deep=True)/to_json()/from_json(), encode_value recursive nested encoding), MiddlewareWrapper + BaseMiddlewarePipeline (callable-to-class adapter via __init__(func) + process(), abstract _register_middleware, has_middlewares gate, _register_middleware_with_wrapper auto-promotion), AgentMiddlewarePipeline + ChatMiddlewarePipeline + FunctionMiddlewarePipeline (concrete pipeline execute() — streaming/non-streaming support, matches() sequence cache-key, MiddlewareTermination short-circuit, empty pipeline fast path), MiddlewareDict TypedDict + categorize_middleware (typed agent/function/chat bucket structure, multi-source merge, callable signature inference, unknown-type fallback to agent bucket), FunctionRequestResult TypedDict (fields: action return/continue/stop, errors_in_a_row, result_message, update_role, function_call_results, function_call_count — total=False so all optional, stop-condition diagnostics), OtelAttr + MessageListTimestampFilter (str-Enum with all 35 GenAI semantic convention attribute names — OPERATION/PROVIDER_NAME/INPUT_TOKENS/OUTPUT_TOKENS/TOOL_NAME/AGENT_ID/LLM_OPERATION_DURATION etc; logging.Filter that adds INDEX_KEY * 1µs offset to record.created for correct log ordering in aggregators), PolicyEnforcementFunctionMiddleware + ConfidentialityLabel + ContentVariableStore + VariableReferenceContent + LabeledMessage + InspectVariableInput (IFC prompt-injection defence — ContentVariableStore.store()/retrieve(), VariableReferenceContent variable-ID indirection, ConfidentialityLabel.PUBLIC/PRIVATE/USER_IDENTITY, LabeledMessage label-tracked Message, InspectVariableInput Pydantic schema, PolicyEnforcementFunctionMiddleware allow_untrusted_tools/block_on_violation/approval_on_violation/audit_log, SecureAgentConfig one-liner setup). Zero→Hero extended to step 36; Jump-to-topic and Reference grids updated.
2026-06-15	1.2.2	Added Class Deep Dives Vol. 13 (source-verified at agent-framework==1.8.1): OpenAIChatClient + OpenAIChatOptions + OpenAISettings + RawOpenAIChatClient (agent_framework.openai — Responses API 4-layer MRO, STORES_BY_DEFAULT server-side state, x-ms-served-model Azure header, per-request reasoning options, Responses vs Completions comparison table), OpenAIChatCompletionClient + OpenAIChatCompletionOptions + RawOpenAIChatCompletionClient (Chat Completions API — logprobs, prediction, logit_bias, stateless design, structured output), OpenAIEmbeddingClient + OpenAIEmbeddingOptions + OpenAIContinuationToken + ContentFilterResultSeverity + OpenAIContentFilterException (embeddings+RAG via MemoryContextProvider, background polling via response_id, Azure content filter exception hierarchy), AnthropicClient + AnthropicChatOptions + RawAnthropicClient (agent_framework.anthropic — Anthropic Messages API, extended thinking via ThinkingConfigEnabled, top_k, service_tier, per-request additional_beta_flags), ClaudeAgent + ClaudeAgentOptions + RawClaudeAgent (Claude Code CLI-backed agent — allowed_tools/disallowed_tools, mcp_servers McpServerConfig, permission_mode, sandbox, multi-agent workflow participation), AnthropicFoundryClient + AnthropicBedrockClient + AnthropicVertexClient (multi-cloud Claude — Azure Foundry azure_ad_token_provider, Bedrock aws_profile, Vertex ADC GoogleCredentials, multi-cloud failover pattern), GroupChatOrchestrator + AgentBasedGroupChatOrchestrator + GroupChatState + GroupChatRequestMessage + AgentOrchestrationOutput (orchestrations internals — function-driven vs LLM-driven selection, frozen GroupChatState snapshot, AgentOrchestrationOutput Pydantic model for structured selection), HandoffAgentExecutor + HandoffAgentUserRequest + HandoffSentEvent + OrchestrationState (handoff internals — autonomous_mode + autonomous_mode_turn_limit, HITL create_response()/terminate() helpers, HandoffSentEvent observability, OrchestrationState.to_dict()/from_dict() checkpoint), MagenticOrchestrator + MagenticAgentExecutor + MagenticOrchestratorEvent + MagenticOrchestratorEventType + MagenticProgressLedgerItem + MagenticPlanReviewRequest + MagenticPlanReviewResponse (Magentic deeper — outer/inner loop, MagenticResetSignal for replanning, plan signoff approve()/revise() HITL, ledger item to_dict()/from_dict()), HttpRequestHandler + DefaultHttpRequestHandler + HttpRequestInfo + HttpRequestResult + MCPToolHandler + DefaultMCPToolHandler + MCPToolInvocation + MCPToolResult + ToolApprovalRequest + ToolApprovalResponse + ExternalInputRequest + ExternalInputResponse + AgentExternalInputRequest + AgentExternalInputResponse (declarative handlers — 3 DefaultHttpRequestHandler construction modes, SSRF guard pattern, MCP LRU cache + LIST_TOOLS_TOOL_NAME discovery, tool approval gate, agent HITL). Zero→Hero extended to step 35; Jump-to-topic and Reference grids updated.
2026-06-14	1.2.1	Added Class Deep Dives Vol. 12 (source-verified at agent-framework==1.8.1): Skill + SkillResource + SkillScript ABCs (the type-system foundation — get_content() / get_resource() / get_script() contracts; SkillResource.read() **kwargs forwarding; SkillScript.run() dict vs list dispatch; parameters_schema extension point; custom DB-backed Skill example), FileSkill (filesystem-backed skill — SKILL.md content cache; <scripts> XML block appended when scripts present; first-access cache lock; case-insensitive get_resource()/get_script()), InlineSkillResource + InlineSkillScript (code-defined primitives — InlineSkillResource content/function mutual exclusivity; _accepts_kwargs precomputed flag; InlineSkillScript lazy parameters_schema via FunctionTool introspection; TypeError on list args), FileSkillScript + SkillScriptRunner (file-backed execution — absolute-path validation; fixed CLI array schema {"type":"array","items":{"type":"string"}}; sync/async runner protocol; isinstance(fn, SkillScriptRunner) verification), SupportsAgentRun (structural agent protocol — id/name/description attributes; dual run() overloads; custom agent without framework inheritance; isinstance() guard; workflow graph integration), RunnerContext (full workflow execution context protocol — 25-method contract: message routing, event pipeline, checkpointing, streaming mode, HITL request/response, yield-output classification; minimal TestRunnerContext test stub; set_runtime_checkpoint_storage override pattern), SwitchCaseEdgeGroupCase + SwitchCaseEdgeGroupDefault (serialisable branch descriptors — condition_name auto-extracted from callable.__name__; to_dict()/from_dict() without live callable; missing-callable placeholder raises RuntimeError on invocation; condition re-registration pattern using a registry dict), ValidationTypeEnum + WorkflowValidationError hierarchy (EDGE_DUPLICATION, EXECUTOR_DUPLICATION, TYPE_COMPATIBILITY, GRAPH_CONNECTIVITY, HANDLER_OUTPUT_ANNOTATION, OUTPUT_VALIDATION; EdgeDuplicationError.edge_id; TypeCompatibilityError.source_types/target_types; GraphConnectivityError; match-based dispatcher; custom ValidationReport dataclass), A2AAgent + A2AAgentSession + A2AExecutor (A2A protocol integration — url/agent_card/client init paths; dual streaming/non-streaming httpx clients; auth_interceptor pattern; float/httpx.Timeout config; supported_protocol_bindings; A2AAgentSession context_id/task_id/task_state with to_dict()/from_dict() round-trip; A2AExecutor stream + run_kwargs server-side exposure), WorkflowRunnerException + WorkflowCheckpointException + MiddlewareException (leaf exception classes — WorkflowCheckpointException dual-inheritance from both WorkflowRunnerException and WorkflowException; checkpoint I/O failure graceful fallback; MiddlewareException vs MiddlewareTermination distinction; full supervisor dispatcher for all 7 framework exception types). Zero→Hero extended to step 34; Jump-to-topic and Reference grids updated.
2026-06-13	1.2.0	Added Class Deep Dives Vol. 11 (source-verified at agent-framework==1.8.1): AgentTelemetryLayer + ChatTelemetryLayer + EmbeddingTelemetryLayer (OTel mixin layer — AGENT_PROVIDER_NAME resolution, token/duration histograms, ObservabilitySettings.ENABLED short-circuit, enable_sensitive_telemetry), Edge + EdgeGroup + SingleEdgeGroup + InternalEdgeGroup (workflow graph primitives — conditional routing with should_route(), serialisation round-trip without callable, EdgeGroup.register custom subclasses, internal source edge semantics), Case + Default (runtime switch-case wrappers — live callables companion to serialisable SwitchCaseEdgeGroupCase/Default), EdgeRunner hierarchy (SingleEdgeRunner, FanOutEdgeRunner, FanInEdgeRunner, SwitchCaseEdgeRunner — EdgeGroupDeliveryStatus enum with 6 values, buffer-until-all-ready fan-in semantics, concurrent asyncio fan-out), ExecutionContext (sub-workflow tracking dataclass — execution_id, collected_responses, expected_response_count, pending_requests for HITL resume), WorkflowGraphValidator (7 pre-build checks: edge duplication → EdgeDuplicationError, type compatibility → TypeCompatibilityError, connectivity → GraphConnectivityError, self-loops warning, dead-ends info, output validation → WorkflowValidationError), MCPTool + MCPSpecificApproval (base class for all 3 MCP transports — full 15-parameter constructor table, functions list post-connect, per-tool result_parser override, additional_tool_argument_names hidden-context forwarding), SerializationMixin + SerializationProtocol (DTO round-trip foundation — DEFAULT_EXCLUDE, INJECTABLE, _SHALLOW_COPY_FIELDS, three dependency injection patterns, custom serialisable tool example, AgentSession round-trip), Evaluator + EvalItemResult + EvalNotPassedError (@runtime_checkable Protocol for evaluation backends, EvalItemResult per-item status/scores/error_code, CI gate pattern with evaluate_and_assert), PerServiceCallHistoryPersistingMiddleware (service_stores_history flag, sentinel conversation ID semantics, per-service-call vs full-turn persistence trade-offs). Zero→Hero extended to step 33; Jump-to-topic and Reference grids updated.
2026-06-12	1.1.9	Upgraded agent-framework 1.8.0 → 1.8.1 (patch release; no new public symbols). Added Class Deep Dives Vol. 10 (source-verified at agent-framework==1.8.1): Workflow + InProcRunnerContext (execution engine API — run() mutual-exclusion rules, input_types/output_types, as_agent(), as_tool(), state preservation, checkpoint resume, streaming), FunctionExecutor (@executor decorator internals — explicit input/output/workflow_output type override, sync function thread-pool wrapping, multi-node wiring), FunctionInvocationLayer (tool-calling loop mixin — get_response() API, custom chat client authoring via _get_response_core, per-call middleware merge, per-executor function_invocation_kwargs), MemoryStore + MemoryIndexEntry + MemoryTopicRecord (memory harness ABC — full 8-method contract, to_dict/from_dict round-trip, MemoryIndexEntry.from_topic_record, custom DictMemoryStore backend plugged into MemoryContextProvider), TodoStore + TodoItem + TodoInput + TodoFileStore + TodoSessionStore (todo harness — TodoFileStore path-safety and per-user scoping, TodoSessionStore session-state embedding, TodoInput title normalisation, ABC load_state/save_state/load_items), DeduplicatingSkillsSource (case-insensitive first-one-wins deduplication in AggregatingSkillsSource pipelines, custom key override subclass), SkillsProvider (context provider — from_paths class method with all parameters, instruction_template placeholder rules, require_script_approval, disable_caching, multi-source composition), MCPTaskOptions (SEP-2663 long-running task lifecycle — default_ttl, cancel_remote_task_on_local_cancellation, max_task_wait, positive-value validation, fire-and-forget pattern), InMemoryCheckpointStorage (in-memory checkpoint backend — save/load/list_checkpoints/list_checkpoint_ids/get_latest/delete; vs FileCheckpointStorage comparison table; HITL resume example), EvalScoreResult + CompactionStrategy + BaseAgent (EvalScoreResult rubric-dimension fields and custom @evaluator; CompactionStrategy protocol — custom in-place mutation + TokenBudgetComposedStrategy composition; BaseAgent — run() implementation contract, FixedResponseAgent test double, SequentialBuilder integration, to_dict() serialisation). Zero→Hero renumbered to step 32; Jump-to-topic, Zero→Hero, and Reference grids updated. Version card and description bumped to 1.8.1.
2026-06-05	1.1.8	Upgraded agent-framework 1.7.0 → 1.8.0. Added Class Deep Dives Vol. 8 (source-verified at agent-framework==1.8.0): AgentFileStore + FileSystemAgentFileStore + InMemoryAgentFileStore (file storage ABC and two first-party backends with path-safety and symlink rejection), FileAccessProvider + FileSearchResult + FileSearchMatch (5-tool CRUD+search harness provider, require_delete_approval flag, SerializationMixin DTOs), MCPSkill + MCPSkillResource + MCPSkillsSource (SEP-2640 Agent Skills over MCP — lazy SKILL.md fetch, resource name security validation, index-JSON discovery), ToolMode + validate_tool_mode (tool-choice TypedDict with mode/required_function_name/allowed_tools, normalization helper), AgentEvalConverter + ExpectedToolCall + CheckResult + RubricScore (eval bridge: convert_messages, to_eval_item, per-dimension RubricScore, structured CheckResult), ChatContext (full chat-middleware context — metadata, result override, stream_transform_hooks, stream_result_hooks, stream_cleanup_hooks), WorkflowAgent + WorkflowContext (BaseAgent wrapping a Workflow, pending_requests HITL, typed WorkflowContext[OutT, W_OutT] with send_message/yield_output), TruncationStrategy (oldest-first token/message compaction, preserve_system flag, compact_to target, TokenizerProtocol integration), HistoryProvider + InMemoryHistoryProvider (history-provider ABC with load_messages/store_inputs/store_outputs flags; InMemoryHistoryProvider default state-backed implementation with skip_excluded), DelegatingSkillsSource + InMemorySkillsSource + FunctionInvocationContext + progressive tools (add_tools/remove_tools @experimental PROGRESSIVE_TOOLS). Version card, description, and “What’s shipped” bumped to 1.8.0. Zero→Hero renumbered to step 30; Jump-to-topic and Reference grids updated.
2026-06-04	1.1.7	Added Class Deep Dives Vol. 7 (source-verified at agent-framework==1.7.0): ContextProvider custom authoring (before_run/after_run lifecycle, provider-scoped state, multi-provider ordering), BackgroundTaskInfo + BackgroundTaskStatus (task metadata data model, LOST status re-issue pattern, reading state from session.state), GroupChatBuilder + TerminationCondition + GroupChatSelectionFunction (LLM orchestrator, round-robin selection, HITL pause), HandoffBuilder + HandoffConfiguration (tool-based routing, autonomous_mode, multi-hop handoff topology), MagenticBuilder + StandardMagenticManager + MagenticProgressLedger (Magentic-One task/progress ledgers, stall detection, plan review HITL, custom progress_ledger_prompt), SequentialBuilder + ConcurrentBuilder (pipeline chaining, chain_only_agent_responses, fan-out/synthesise composition), AgentFactory + WorkflowFactory (agent-framework-declarative, YAML agent and workflow definitions, ProviderTypeMapping, WorkflowState, safe_mode), SecureAgentConfig + ContentLabel + IntegrityLabel + LabelTrackingFunctionMiddleware (agent_framework.security, IFC-based prompt injection defence, 3-tier label propagation, ContentVariableStore, approval-on-violation pattern), FunctionalWorkflowAgent (run() overloads, pending_requests HITL, drop-in orchestration participant), ObservabilitySettings + configure_otel_providers (OTLP bootstrap, custom exporters, metric View filters, enable_sensitive_telemetry). Zero→Hero updated to step 29; Jump-to-topic and Reference grids updated.
2026-06-03	1.1.6	Added Class Deep Dives Vol. 6 (source-verified at agent-framework-core==1.7.0): ExperimentalFeature + ReleaseCandidateFeature + @experimental/@release_candidate decorators (feature staging, warning suppression, per-feature-ID introspection, 9 experimental feature IDs at 1.7.0), WorkflowRunState + WorkflowErrorDetails (7-state run state machine, from_exception() factory, structured error logging patterns), WorkflowExecutor + SubWorkflowRequestMessage + SubWorkflowResponseMessage (hierarchical workflow composition, HITL across workflow boundaries, allow_direct_output semantics), AgentResponse + AgentResponseUpdate + ContinuationToken (full field reference, serialisation round-trip, structured output, streaming collapse, background-operation polling), BaseEmbeddingClient + SupportsGetEmbeddings + Embedding + EmbeddingGenerationOptions + GeneratedEmbeddings (custom embedding provider implementation, RAG duck-typing patterns), FunctionInvocationConfiguration TypedDict (all 7 fields, default values, max_iterations vs max_function_calls semantics, per-request override, additional_tools hidden-tool pattern), ClassSkill + SkillFrontmatter + FileSkillsSource + SkillsProvider (@ClassSkill.resource/@ClassSkill.script auto-discovery, directory-scanned SKILL.md files, mixed code+file SkillsProvider wiring), Annotation + TextSpanRegion (citation metadata, grounding attribution, region filtering), provider capability protocols (SupportsCodeInterpreterTool, SupportsWebSearchTool, SupportsImageGenerationTool, SupportsMCPTool, SupportsFileSearchTool — adaptive tool builder + capability probe patterns), MiddlewareType + AgentMiddlewareLayer + ChatMiddlewareLayer (pipeline execution order diagram, MiddlewareTermination short-circuit). Zero→Hero renumbered to 28 steps; Jump-to-topic and Reference grids updated.
2026-06-02	1.1.5	Added Class Deep Dives Vol. 5 (source-verified at agent-framework-core==1.7.0): Executor + @handler + @executor (introspection vs explicit type modes, WorkflowContext generic variants, checkpoint hooks, FunctionExecutor), AgentExecutor + AgentExecutorRequest + AgentExecutorResponse (all five built-in handlers, context modes, with_text() conversation-context preservation), FanOutEdgeGroup + FanInEdgeGroup + SwitchCaseEdgeGroup (dynamic selection functions, switch/case single-dispatch semantics, construction constraints), Runner + WorkflowMessage (Pregel superstep engine, convergence detection, concurrent message delivery, trace context fan-in), SessionContext (per-invocation provider pipeline, extend_messages attribution, cross-provider metadata), AgentSession + register_state_type (cross-call state, Pydantic round-trip, cold-start registration), BaseChatClient + SupportsChatGetResponse (custom model client implementation, structural protocol verification), SecretString + load_settings (repr masking, .env resolution order), WorkflowCheckpoint + CheckpointStorage (full dataclass fields, topology hash compatibility, HITL resume via pending events, custom storage protocol), full exception hierarchy (AgentFrameworkException tree, MiddlewareTermination short-circuit, WorkflowConvergenceException, UserInputRequiredException). Zero→Hero renumbered to 27 steps; Jump-to-topic and Reference grids updated.
2026-06-01	1.1.4	Added Class Deep Dives Vol. 4 (source-verified at agent-framework-core==1.7.0): Message + Content (multimodal factory methods, serialization), ChatOptions + ChatResponse + ChatResponseUpdate + UsageDetails (raw chat layer), ResponseStream (transform/cleanup/result hooks, .map(), .with_finalizer()), AgentContext (middleware context — all 14 mutable fields, short-circuit and streaming patterns), FunctionalWorkflow + StepWrapper (HITL replay, step-level caching, per-step checkpointing, .as_agent()), WorkflowEvent + WorkflowEventType + WorkflowEventSource (full event taxonomy, HITL dispatch loop pattern), SkillsSource + AggregatingSkillsSource + FilteringSkillsSource + DeduplicatingSkillsSource (skill composition pipeline), EvalItem + EvalItemResult + EvalResults + EvalScoreResult (evaluation data model), TokenizerProtocol + CharacterEstimatorTokenizer (tiktoken and HuggingFace integration examples), ConversationSplit + ConversationSplitter (LAST_TURN vs FULL splits, custom splitter protocol). Zero→Hero renumbered to 26 steps; Jump-to-topic and Reference grids updated.
2026-05-31	1.1.3	Added azure-ai-agents integration Class Deep Dives Vol. 6 (source-verified at azure-ai-agents==1.1.0): OpenAPI auth hierarchy (OpenApiAnonymousAuthDetails, OpenApiManagedAuthDetails, OpenApiConnectionAuthDetails), BingGroundingSearchConfiguration + BingGroundingSearchToolParameters, RunCompletionUsage + RunStepCompletionUsage, VectorStoreDataSource + VectorStoreConfigurations, expiry policy + static/auto chunking strategies, AgentsNamedToolChoice + AgentsToolChoiceOptionMode, file-search run step results (RunStepFileSearchToolCall → FileSearchToolCallContent), streaming event taxonomy (AgentStreamEvent + 4 sub-enums), RequiredFunctionToolCall + SubmitToolOutputsDetails manual dispatch, multimodal ThreadMessageOptions with MessageInputImageFileBlock + MessageInputImageUrlBlock. Zero→Hero renumbered to 25 steps; Jump-to-topic and Reference grids updated.
2026-05-30	1.1.2	Upgraded agent-framework 1.6.0 → 1.7.0. Added Class Deep Dives Vol. 3 (10 source-verified classes from 1.7.0): BackgroundAgentsProvider, MemoryContextProvider + MemoryFileStore, TodoProvider + TodoFileStore, AgentModeProvider, SummarizationStrategy, ContextWindowCompactionStrategy, SlidingWindowStrategy, SelectiveToolCallCompactionStrategy, WorkflowViz, MCPStreamableHTTPTool + MCPWebsocketTool. Updated version card, description, and “What’s shipped” section. Zero→Hero renumbered; Jump-to-topic and Reference grids updated.
2026-05-29	1.1.1	Corrected erroneous reframing of this guide as an azure-ai-agents site. agent-framework is the primary framework; azure-ai-agents is an optional integration add-on. Restored correct title, description, install command, minimal example, and framing. Removed false “Package name correction” Aside and migration notice. Reframed azure-ai-agents class deep dive volumes (1, 3, 4, 5) as integration add-on reference material rather than framework documentation.
2026-05-22	1.0.9	Version bumped 1.5.0 → 1.6.0; version card, description frontmatter, and “What’s shipped” section updated to 1.6.0. All 23 core symbols verified against installed agent-framework-core==1.6.0 (.routine-envs/check-0522-ms-agent); 242 public symbols confirmed; no API regressions. frameworks.ts updated v1.4.0 → v1.6.0. Note: DeprecationWarning from opentelemetry internal importlib.metadata dict interface (Python 3.11 compat) persists — upstream opentelemetry bug, not an agent-framework issue.
2026-05-20	1.0.8	Bumped all version references to agent-framework-core==1.5.0. Added output_from/intermediate_output_from documentation to WorkflowBuilder (replaces deprecated output_executors). Added full MemoryContextProvider section to HARNESS Providers guide including injected tools, consolidation_client, history_message_filter, and custom MemoryStore backend examples. Added RunContext.set_state key restriction (_ prefix raises ValueError) to Functional Workflows guide. Added combined checkpoint_id + responses HITL resume pattern. Added include_status_events explanation. Fixed FunctionInvocationConfiguration defaults (max_iterations=40, max_consecutive_errors_per_request=3). Added full FunctionTool constructor reference table with declaration_only, additional_properties, and middleware cost-tagging examples.
2026-05-17	1.0.7	Bumped all version references to agent-framework-core==1.4.0. Added get_run_context() code example to Functional Workflows guide (accessing RunContext from nested utility functions). Added annotate_message_groups low-level helper documentation to Compaction guide. Re-verified all API surfaces against installed agent-framework-core==1.4.0 source.
2026-05-09	1.0.6	Bumped all guides to agent-framework-core==1.3.0. agent-framework-foundry and agent-framework-openai promoted to stable 1.3.0. Rewrote Skills guide with breaking API changes: InlineSkill replaces Skill, SkillsProvider(source) positional arg replaces skills=/skill_paths=, SkillsProvider.from_paths() for file-based skills. Added AggregatingSkillsSource, FilteringSkillsSource, DeduplicatingSkillsSource coverage. Added RawAgent to comprehensive guide. Added MemoryStore/MemoryContextProvider long-term memory section. Fixed FunctionInvocationConfiguration usage (client-level only, not agent.run() parameter). Added WorkflowBuilder.add_chain() and add_multi_selection_edge_group() detail.
2026-05-04	1.0.5	Added dedicated Functional Workflows page covering @workflow, @step, RunContext, FunctionalWorkflow.as_agent(). Enhanced Graphs & Declarative page with WorkflowViz examples, add_chain, add_multi_selection_edge_group, @executor decorator, and Agent.as_tool(). All verified against agent-framework-core==1.2.2 source.
2026-05-01	1.0.4	Bumped pinned core/provider versions to agent-framework-core==1.2.2 and 1.0.0b260429 provider line. Expanded streaming, function-middleware, functional-workflow, and feature-stage code examples after re-introspecting the installed library.
2026-04-22	1.0.3	Added dedicated pages: Tools, Skills, Checkpointing, Compaction, Observability & Telemetry, Evaluation. Zero→Hero reflow to 18 steps; Jump-to-topic grid and Reference card grid updated.
2026-04-22	1.0.2	Added dedicated pages: Model Providers, Orchestration, Middleware, MCP, Human-in-the-loop. Verified against source of agent-framework-core==1.1.0; corrected context_providers plural-vs-singular errata.
2026-04-21	1.0.1	Index redesigned into Zero → Hero reading order + Jump-to-topic grid using Starlight cards.
2026-04-20	1.0.1	Version pin corrected to v1.0.1; verified via agent-framework PyPI package.
April 16, 2026	1.0 GA	Graduated from Preview; ChatClientAgentOptions.Instructions removed; first-party connectors; Azure App Service support.
November 2025	1.0 Preview	Initial Python guide; multi-agent orchestration.