프레임워크

Microsoft Agent Framework 실전 가이드: 단일 Agent에서 멀티 Agent 워크플로까지

GitHub에서 13k Stars를 기록한微软의 공식 Agent 프레임워크인 MAF를 Python과 .NET 양대 스택으로 만나본다. 내장된 4가지编排 패턴을 중심으로, 최소 코드와 아키텍처 다이어그램으로 Demo를 production으로 끌어올리는 과정을 정리한다.

글자 크기

들어가며

지난주 Microsoft의 Agent Framework(MAF)가 GitHub Trending에 올랐다. 13,356 Stars, production-grade 포지셔닝. samples 디렉터리 대부분을 돌려본 결론부터 말하면, 현재 가장 "엔터프라이즈답게" 설계된 Agent 프레임워크다. 대신 추상화 레이어가 두텁고, 소규모 프로젝트엔 다소 무겁다.

해결하려는 문제

LangChain은 너무 자유롭고, AutoGen은 토이 같고, LangGraph는 학습 곡선이陡峭하다. 기업이 Agent를 production에 올리려면 provider 중립적이고, observability가 확보되며, human-in-the-loop를 지원하는 프레임워크가 필요하다. Microsoft의 agent-framework는 정확히 그 빈자리를 노린다.

세 가지로 풀어보면:

  • Observability: Workflow 노드의 모든 상태 변화가 이벤트로 broadcast되며, OpenTelemetry 통합이 내장됨
  • 복구 가능: Checkpointing 내장, workflow 중간에 죽어도 최근 스냅샷에서 재시작
  • 중단 가능: human-in-the-loop가 first-class 개념, 나중에 덧붙인 장식이 아님

LangChain 시대엔 이 세 가지를 직접 조립해야 했다. MAF는 Runtime 레이어에 이걸 녹여 넣었다.

사용법

pip install agent-framework, 30줄로 도구 호출 Agent 작성:

from agent_framework.azure import AzureAIAgent
from agent_framework import tool

@tool
def get_weather(city: str) -> str:
    return f"{city}:晴,25°C"

agent = AzureAIAgent(
    name="weather-bot",
    instructions="你是一个天气助手,使用工具回答问题。",
    tools=[get_weather],
)

async def main():
    response = await agent.run("北京今天天气怎么样?")
    print(response.text)

import asyncio
asyncio.run(main())

50줄을 더해 sequential workflow로 두 Agent가 주문을接力 처리하게 만든다:

from agent_framework import WorkflowBuilder, executor

@executor
async def intake(msg: str, ctx):
    await ctx.send_message(msg, target_id="validator")

@executor
async def validator(msg: str, ctx):
    if "fraud" in msg.lower():
        await ctx.yield_output("blocked")
    else:
        await ctx.send_message(msg, target_id="fulfill")

@executor
async def fulfill(msg: str, ctx):
    await ctx.yield_output(f"order {msg} shipped")

wf = (
    WorkflowBuilder()
    .set_start_executor(intake)
    .add_edge(intake, validator)
    .add_edge(validator, fulfill)
    .build()
)

async def main():
    async for ev in wf.run_stream("order-12345"):
        print(ev)

add_edge 같은 그래프 구조 API에 주목할 만하다. 이름만 다를 뿐 LangGraph 스타일의 DAG다.

동작 방식

세 레이어로 분해된다:

  • Agent: 단일 유닛. LLM client + 도구 세트 + system prompt 캡슐화
  • Workflow: 오케스트레이션 레이어. 그래프 구조로 Agent 간 데이터 흐름 정의
  • Runtime: 실행 환경. checkpoint, streaming, HITL, time-travel 담당

그래프 오케스트레이션의 내장 네 가지 토폴로지:

  1. Sequential: A → B → C, 파이프라인
  2. Concurrent: 여러 Agent로 broadcast 후 결과 병합
  3. Handoff: 컨텍스트에 따라 작업을 다른 Agent에 "인수인계" (AutoGen의 그룹 채팅과 유사)
  4. Group Chat: 여러 Agent의 라운드 테이블 토론, moderator 존재

Azure AI Foundry 배포는 단 2줄만 추가하면 된다. AzureAIAgent를 FoundryAgent로 바꾸고 환경 변수에 foundry endpoint를 설정하면 끝. 나머지 코드는 그대로다.

장점과 단점

장점:

  • Python과 .NET API 일관성이 높고, 양쪽 네이밍 컨벤션이 거의 대등
  • 엔터프라이즈급 기능 완비: checkpointing, streaming, human-in-the-loop, time-travel 모두 first-class
  • Microsoft 생태계 통합이 깊음: Foundry, Azure OpenAI, GitHub Copilot SDK 네이티브 지원

단점:

  • Python 패키지 크기가 다소 큼. agent_framework import만으로 의존성이 딸려옴
  • OpenAI 호환 레이어 외 provider(DeepSeek, Qwen 등)에 대한 문서 지원이 얇음
  • Go SDK가 분리된 repo인 점이 양날의 검: 메인 repo와 별도 유지보 페이스

가로 비교:

  • MAF: 그래프 + 4가지 토폴로지 / 학습 곡선 보통 / production 기능 강함
  • LangGraph: 커스텀 DAG / 학습 곡선陡 / production 기능 보통
  • AutoGen: 대화 기반 / 학습 곡선 낮음 / production 기능 약함
  • CrewAI: Role-based / 학습 곡선 낮음 / production 기능 보통

MAF가 잘 맞는 시나리오는 "원하는 오케스트레이션 패턴을 알고 있으니 네 가지 중 하나를 고르겠다"인 경우다. LangGraph는 "任意 토폴로지를 직접 정의하겠다"인 경우에 어울린다.

테스트 결과

로컬에서 samples/02-agents의 function calling 예제와 samples/03-workflows의 sequential workflow를 돌려봤다. 데이터는 다음과 같다:

  • 콜드 스타트 시간: AzureAIAgent 초기화 + 첫 모델 호출, 2.1초 (인증에 0.8초 소요)
  • 토큰 소비: 단일 라운드 날씨 조회 기준 약 320 input + 85 output, 도구 설명이 input의 40% 차지
  • Checkpoint 동작: workflow가 executor 노드를 완료할 때마다 자동 영속화, 재시작 시 중단점부터 이어서 실행되며 중복 실행 없음

체감상 API 설계는 LangGraph보다 훨씬 수렴적이다. 다만 디버깅 정보는 LangGraph dev UI만큼 직관적이지 않다. workflow 중간 상태는 직접 print해야 하고, 시각화는 외부 trace 툴에 연결해야 한다.

대상 사용자

적합:

  • .NET 팀 (Microsoft 정통, .NET SDK가 Python보다 먼저 GA)
  • 엔터프라이즈 프로젝트 (HITL, 감사 로그, observability 필요)
  • 금융·의료·법률 시나리오 (컴플라이언스 요건 높음)

부적합:

  • 프롬프트 몇 개만 돌릴 극단적 미니멀 사용자 (OpenAI SDK로 충분)
  • 순수 프론트엔드 Demo (MAF는 백엔드 프레임워크)
  • LangGraph처럼 고도로 커스텀된 DAG가 필요한 연구자

편집자의 생각

이번 Microsoft의 가장 큰 차별점은 기술력 자체가 아니라, Agent 프레임워크를 enterprise software 기준으로 재정의한다는 점이다. durability, observability, provider 추상화 — LangChain 시대에 거의 언급되지 않았던 단어들이다. 12개월 안에 production-grade Agent 프로젝트의 기본 선택이 LangGraph에서 MAF 혹은 유사 프레임워크로 넘어갈 것으로 본다.

리스크: Microsoft는 과거에 Bot Framework, Semantic Kernel 같은 미완성작을 낸 이력이 있다. 커뮤니티가 너무 빠르게分裂하면 Python 측은 LangChain에 밀릴 수 있다. Semantic Kernel도 "Microsoft 공식 + .NET 친화"라는 무기로 시작했지만 결국 LangChain에 밀렸다.

확실하지 않은 부분: 중국 로컬 LLM(DeepSeek, Qwen)에 대한 지원 깊이다. README에는 명시돼 있지 않다. OpenAI 호환 레이어로 이론상 동작은 하겠지만, 도구 호출 포맷과 중국어 system prompt 템플릿에 대한 전용 테스트는 보이지 않는다. 국내 배포를 고려한다면 이 부분부터 직접 검증해야 한다.

출처: GitHub - microsoft/agent-framework

출처: https://github.com/microsoft/agent-framework