AI Agents for Beginners - 14. Microsoft Agent Framework

AI Agents for Beginners - 14. Microsoft Agent Framework

출처: 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: 다음 세션에서 재사용 가능

Agent Middleware

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
    subgraph FunctionMiddleware["Function Middleware"]
        direction LR
        Pre1["전처리\n(로깅 등)"] --> Func["실제 함수\n실행"] --> Post1["후처리\n(결과 검사)"]
    end
    subgraph ChatMiddleware["Chat Middleware"]
        direction LR
        Pre2["전처리\n(메시지 수 확인)"] --> LLM["LLM\n호출"] --> Post2["후처리\n(응답 로깅)"]
    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: app 종료 시 소멸

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 각 Executor 순서대로
        Workflow->>Executor: invoke
        Executor-->>Logger: ExecutorInvokeEvent
        Note over Executor: 작업 처리
        Executor-->>Logger: ExecutorCompleteEvent
        Executor->>Workflow: output
    end
    alt Human 입력 필요
        Workflow-->>Logger: RequestInfoEvent
        Logger->>App: 사용자에게 질문
        App->>Workflow: send_responses_streaming()
    else 오류 발생
        Workflow-->>Logger: WorkflowErrorEvent
    end
    Workflow-->>Logger: WorkflowOutputEvent
    Workflow-->>App: 최종 결과

Advanced MAF Patterns

Sequential Orchestration

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
    U["User Input"] --> FD["Front Desk Agent\n추천 제공"]
    FD --> C["Concierge Agent\n검토 및 평가"]
    C --> O["최종 출력\n추천 + 전문가 검토"]

• Iterative Refinement: 두 번째 에이전트가 첫 번째 에이전트의 작업을 개선
• Specialization: 각 에이전트가 프로세스에서 특정 역할 담당
• Quality Control: 내장된 검토 및 검증 단계

Concurrent Orchestration

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
    U["User Input\n도쿄 여행 추천"] --> D["InputDispatcher\n팬아웃 브로드캐스트"]
    D --> A["Attractions Agent\n관광 명소·활동"]
    D --> B["Dining Agent\n음식·식당"]
    D --> C["History Agent\n역사·문화"]
    A --> O["통합 출력\n포괄적 여행 가이드"]
    B --> O
    C --> O

Handoff Orchestration

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart TD
    U["User Request"] --> CS["Customer Support Agent\n(Coordinator)"]
    CS -->|"항공권 예약 요청"| BA["Booking Agent\n✈️ 항공편 예약"]
    CS -->|"환불/분쟁 요청"| DA["Disputes Agent\n💰 환불 처리"]
    CS -->|"여행 확인 요청"| TA["Trip Check Agent\n🎯 일정 확인"]
    BA --> R["Resolution\n전문가 처리 완료"]
    DA --> R
    TA --> R

• Dynamic Routing: Customer Support 에이전트가 요청 의도를 분석해 전문가에게 연결
• Context Preservation: 전환 시에도 전체 대화 이력 유지 (사용자가 정보를 반복할 필요 없음)
• Specialization: 각 에이전트가 자신의 전문 영역만 처리

Middleware Injection

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart LR
    subgraph Regular["일반 사용자"]
        direction LR
        R1["Paris 요청"] --> R2["hotel_booking\n파리 가용 없음"] --> R3["alternative_agent\n대안 제안"]
    end
    subgraph Priority["우선 회원"]
        direction LR
        P1["Paris 요청"] --> P2["hotel_booking\n파리 가용 없음"] --> MW["🌟 Middleware\nOverride!"] --> P3["booking_agent\n예약 진행"]
    end

Human-in-the-Loop

• RequestInfoExecutor: 워크플로우를 일시 중지하고 RequestInfoEvent 발행
• RequestInfoMessage: 인간에게 보내는 요청 페이로드의 기본 클래스
• RequestResponse: request_id로 요청과 응답을 연결

Process Flowchart
Mermaid
%%{init: {'look': 'handDrawn'}}%%
flowchart TD
    Start["availability_agent\n가용성 확인"] -->|"가용 없음"| Conf["confirmation_agent\n확인 질문 생성"]
    Start -->|"가용 있음"| Book["booking_agent\n예약 권장"]
    Conf --> Prep["prepare_human_request\n타입 변환"]
    Prep --> RI["RequestInfoExecutor\n⏸️ PAUSE"]
    RI --> DM["DecisionManager\n인간 응답 처리"]
    DM -->|"yes"| Alt["alternative_agent\n대안 제안"]
    DM -->|"no"| Cancel["cancellation_agent\n취소 처리"]
    Alt --> End["display_result"]
    Cancel --> End
    Book --> End

Advanced MAF Patterns Summary

• Middleware Composition: 함수·채팅 미들웨어를 체인으로 연결해 로깅, 인증, 속도 제한 등 여러 핸들러를 조합
• Workflow Checkpointing: 워크플로우 이벤트·직렬화를 활용해 장시간 실행되는 프로세스를 저장하고 재개
• Dynamic Tool Selection: 도구 설명에 대한 RAG와 MAF의 도구 등록을 결합해 쿼리당 관련 도구만 제시
• Multi-Agent Handoff: 워크플로우 에지·조건부 라우팅으로 전문화된 에이전트 간 핸드오프 오케스트레이션

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

    MAF --> Core["핵심 개념"]
    MAF --> WF["워크플로우"]
    MAF --> Pattern["고급 패턴"]

    Core --> Agent["에이전트\n생성·실행·도구·스레드"]
    Core --> MW["미들웨어\nFunction·Chat"]
    Core --> Mem["메모리\nIn-memory·지속·동적"]
    Core --> Obs["관찰 가능성\nOpenTelemetry"]

    WF --> Exec["Executor\nAI Agent or 커스텀 로직"]
    WF --> Edge["Edge\n직접·조건부·팬아웃·팬인"]
    WF --> Evt["Event\nStarted·Output·Error"]

    Pattern --> Seq["Sequential\n순차 개선"]
    Pattern --> Conc["Concurrent\n병렬 팬아웃"]
    Pattern --> HO["Handoff\n동적 라우팅"]
    Pattern --> MWP["Middleware\n결과 Override"]
    Pattern --> HITL["Human-in-the-Loop\n인간 승인 통합"]