AI Agents for Beginners - 14. Microsoft Agent Framework

AI Agents for Beginners - 14. Microsoft Agent Framework

Source: microsoft/ai-agents-for-beginners - 14-microsoft-agent-framework

Understanding Microsoft Agent Framework

Orchestration Types

Sequential
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A1[Agent 1] --> A2[Agent 2] --> A3[Agent 3]

Concurrent
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  D[Dispatcher] --> A1[Agent 1] & A2[Agent 2] & A3[Agent 3]

Group Chat
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Agent A] <--> B[Agent B]
  B <--> C[Agent C]
  A <--> C

Handoff
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A1[Agent 1] -->|subtask done| A2[Agent 2] -->|subtask done| A3[Agent 3]

Magnetic
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart TD
  M[Manager] --> TL[Task List]
  TL --> S1[Sub-Agent 1] & S2[Sub-Agent 2] & S3[Sub-Agent 3]

Production Features

Observability
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Agent] --> T[Tool Call] --> O[OTel Trace] --> D[Dashboard]

Security
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  R[Request] --> RB[RBAC Check] --> A[Agent]

Durability
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  R[Run] --> P[Pause] --> RS[Resume] --> C[Complete]

Control
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Agent] --> H[Human Approval] --> C[Continue]

Interoperability

Cloud-agnostic
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Agent] --> C1[Container] & C2[On-prem] & C3[Multi-Cloud]

Provider-agnostic
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Agent] --> P1[Azure OpenAI] & P2[OpenAI] & P3[MiniMax]

Open Standards
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Agent] <--> S1[A2A] & S2[MCP]

Plugins & Connectors
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Agent] --> P1[Fabric] & P2[SharePoint] & P3[Pinecone/Qdrant]

Key Concepts of Microsoft Agent Framework

Agents

Creating Agents

Running Agents

Non-Streaming (agent.run)
Mermaid
%%{init: {'look': 'handDrawn'}}%%
sequenceDiagram
    participant User
    participant Agent
    participant LLM
    User->>Agent: run("question")
    Agent->>LLM: request
    Note over LLM: generates full response
    LLM-->>Agent: complete response
    Agent-->>User: result.text (all at once)

Streaming (agent.run_stream)
Mermaid
%%{init: {'look': 'handDrawn'}}%%
sequenceDiagram
    participant User
    participant Agent
    participant LLM
    User->>Agent: run_stream("question")
    Agent->>LLM: request
    loop token by token
        LLM-->>Agent: chunk
        Agent-->>User: update.text (partial)
    end

Tools

Agent Threads

Sequence Diagram
Mermaid
%%{init: {'look': 'handDrawn'}}%%
sequenceDiagram
    participant User
    participant Agent
    participant Thread

    User->>Agent: run("Where to go?", thread=thread)
    Agent->>Thread: append message
    Agent-->>User: response

    User->>Agent: run("What about hotels?", thread=thread)
    Agent->>Thread: append message + read history
    Agent-->>User: response (with context)

    Agent->>Thread: serialize()
    Thread-->>Agent: serialized_thread
    Note over Thread: Can be reused in subsequent sessions

Agent Middleware

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
    subgraph FunctionMiddleware["Function Middleware"]
        direction LR
        Pre1["Pre-processing\n(Logging, etc.)"] --> Func["Actual Function\nExecution"] --> Post1["Post-processing\n(Inspect results)"]
    end
    subgraph ChatMiddleware["Chat Middleware"]
        direction LR
        Pre2["Pre-processing\n(Check message count)"] --> LLM["LLM\nCall"] --> Post2["Post-processing\n(Log response)"]
    end
    Agent --> FunctionMiddleware
    Agent --> ChatMiddleware

Agent Memory

In-Memory Storage
Mermaid
%%{init: {'look': 'handDrawn'}}%%
sequenceDiagram
    participant User
    participant Agent
    participant Thread
    User->>Agent: run(message, thread=thread)
    Agent->>Thread: store message
    Agent-->>User: response
    Note over Thread: Cleared when app terminates

Persistent Messages
Mermaid
%%{init: {'look': 'handDrawn'}}%%
sequenceDiagram
    participant User
    participant Agent
    participant ChatMessageStore
    User->>Agent: Session 1
    Agent->>ChatMessageStore: save messages
    Note over Agent: session ends
    User->>Agent: Session 2
    Agent->>ChatMessageStore: load history
    ChatMessageStore-->>Agent: previous messages
    Agent-->>User: response (with context)

Dynamic Memory
Mermaid
%%{init: {'look': 'handDrawn'}}%%
sequenceDiagram
    participant User
    participant Agent
    participant Mem0
    participant LLM
    User->>Agent: run(message)
    Agent->>Mem0: fetch memories
    Mem0-->>Agent: relevant context
    Agent->>LLM: messages + memory context
    LLM-->>Agent: response
    Agent-->>User: response

Agent Observability

Workflows

Executors

Edges

Direct Edge
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Executor A] --> B[Executor B]

Conditional Edge
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Executor A] -->|"condition met"| B[Executor B]
  A -->|"condition not met"| A

Switch-case Edge
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Executor A] -->|"case 1"| B[Executor B]
  A -->|"case 2"| C[Executor C]
  A -->|"case 3"| D[Executor D]

Fan-out Edge
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Executor A] --> B[Executor B]
  A --> C[Executor C]
  A --> D[Executor D]

Fan-in Edge
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
  A[Executor A] --> D[Executor D]
  B[Executor B] --> D
  C[Executor C] --> D

Events

Workflow Events — Hooking Points
Mermaid
%%{init: {'look': 'handDrawn'}}%%
sequenceDiagram
    participant App
    participant Workflow
    participant Executor
    participant Logger as Logger / Hook

    App->>Workflow: workflow.run_stream(input)
    Workflow-->>Logger: WorkflowStartedEvent
    loop Each Executor in sequence
        Workflow->>Executor: invoke
        Executor-->>Logger: ExecutorInvokeEvent
        Note over Executor: Process task
        Executor-->>Logger: ExecutorCompleteEvent
        Executor->>Workflow: output
    end
    alt Human input required
        Workflow-->>Logger: RequestInfoEvent
        Logger->>App: Prompt user with question
        App->>Workflow: send_responses_streaming()
    else Error occurs
        Workflow-->>Logger: WorkflowErrorEvent
    end
    Workflow-->>Logger: WorkflowOutputEvent
    Workflow-->>App: Final result

Advanced MAF Patterns

Sequential Orchestration

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
    U["User Input"] --> FD["Front Desk Agent\nProvide Recommendations"]
    FD --> C["Concierge Agent\nReview & Evaluate"]
    C --> O["Final Output\nRecommendation + Expert Review"]

• Iterative Refinement: The second agent refines the work of the first agent
• Specialization: Each agent handles a specific role in the process
• Quality Control: Built-in review and verification steps

Concurrent Orchestration

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
    U["User Input\nTokyo travel recommendations"] --> D["InputDispatcher\nFan-out broadcast"]
    D --> A["Attractions Agent\nAttractions & Activities"]
    D --> B["Dining Agent\nFood & Restaurants"]
    D --> C["History Agent\nHistory & Culture"]
    A --> O["Integrated Output\nComprehensive Travel Guide"]
    B --> O
    C --> O

Handoff Orchestration

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart TD
    U["User Request"] --> CS["Customer Support Agent\n(Coordinator)"]
    CS -->|"Flight booking request"| BA["Booking Agent\n✈️ Book flight"]
    CS -->|"Refund/dispute request"| DA["Disputes Agent\n💰 Process refund"]
    CS -->|"Trip confirmation request"| TA["Trip Check Agent\n🎯 Confirm itinerary"]
    BA --> R["Resolution\nSpecialist handling complete"]
    DA --> R
    TA --> R

• Dynamic Routing: The Customer Support agent analyzes request intent to route to specialists
• Context Preservation: Retains full conversation history across transitions (no need for users to repeat information)
• Specialization: Each agent focuses solely on its domain of expertise

Middleware Injection

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
    subgraph Regular["Regular User"]
        direction LR
        R1["Paris Request"] --> R2["hotel_booking\nParis unavailable"] --> R3["alternative_agent\nSuggest alternatives"]
    end
    subgraph Priority["Priority Member"]
        direction LR
        P1["Paris Request"] --> P2["hotel_booking\nParis unavailable"] --> MW["🌟 Middleware\nOverride!"] --> P3["booking_agent\nProceed with booking"]
    end

Human-in-the-Loop

• RequestInfoExecutor: Pauses the workflow and emits RequestInfoEvent
• RequestInfoMessage: Base class for request payloads sent to humans
• RequestResponse: Links requests and responses via request_id

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart TD
    Start["availability_agent\nCheck availability"] -->|"No availability"| Conf["confirmation_agent\nGenerate confirmation question"]
    Start -->|"Available"| Book["booking_agent\nRecommend booking"]
    Conf --> Prep["prepare_human_request\nType conversion"]
    Prep --> RI["RequestInfoExecutor\n⏸️ PAUSE"]
    RI --> DM["DecisionManager\nProcess human response"]
    DM -->|"yes"| Alt["alternative_agent\nSuggest alternatives"]
    DM -->|"no"| Cancel["cancellation_agent\nProcess cancellation"]
    Alt --> End["display_result"]
    Cancel --> End
    Book --> End

Advanced MAF Patterns Summary

• Middleware Composition: Chain function and chat middleware together to combine multiple handlers such as logging, authentication, and rate limiting
• Workflow Checkpointing: Leverage workflow events and serialization to save and resume long-running processes
• Dynamic Tool Selection: Combine RAG over tool descriptions with MAF tool registration to provide only relevant tools per query
• Multi-Agent Handoff: Handoff orchestration between specialized agents using workflow edges and conditional routing

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart TD
    MAF["Microsoft Agent\nFramework"]

    MAF --> Core["Core Concepts"]
    MAF --> WF["Workflows"]
    MAF --> Pattern["Advanced Patterns"]

    Core --> Agent["Agents\nCreate·Run·Tools·Threads"]
    Core --> MW["Middleware\nFunction·Chat"]
    Core --> Mem["Memory\nIn-memory·Persistent·Dynamic"]
    Core --> Obs["Observability\nOpenTelemetry"]

    WF --> Exec["Executor\nAI Agent or Custom Logic"]
    WF --> Edge["Edge\nDirect·Conditional·Fan-out·Fan-in"]
    WF --> Evt["Event\nStarted·Output·Error"]

    Pattern --> Seq["Sequential\nIterative Refinement"]
    Pattern --> Conc["Concurrent\nParallel Fan-out"]
    Pattern --> HO["Handoff\nDynamic Routing"]
    Pattern --> MWP["Middleware\nResult Override"]
    Pattern --> HITL["Human-in-the-Loop\nHuman Approval Integration"]