Microsoft Agent Framework는 AI 에이전트를 구축하기 위한 Microsoft 제작 오픈소스 SDK입니다.

이 기사에서는 그 Python용 구현체인 Agent Framework for Python을 다룹니다.

python-1.0.0이 2026-04-02에 출시되었으며, 그 후 2026-06-30에는 python-1.10.0까지 진행되었습니다.

단기간에 기능 추가도 많고, 파괴적 변경(Breaking Changes)도 어느 정도 있습니다.

이 기사에서는 python-1.0.0부터 python-1.10.0까지의 릴리스를 추적하며, 세세한 버그 수정이 아니라 사용자 관점에서 사용 편의성이나 이행(Migration) 시 주의점이 어떻게 변했는지를 정리합니다.

이 기사는 2026-07-02 시점에서 확인한 정보를 바탕으로 하고 있습니다.

대상은 정식 버전 릴리스 python-1.0.0 ~ python-1.10.0입니다.

버전을 고정하여 설치하는 경우는 다음과 같이 지정합니다.

pip install agent-framework==1.10.0

다른 버전을 확인하고 싶은 경우에는 1.10.0 부분을 대상 버전으로 교체합니다.

Microsoft Agent Framework는 Microsoft의 기존 에이전트 프레임워크인 Semantic Kernel과 AutoGen의 흐름을 통합한 차세대 에이전트 개발 기반입니다.

대략적으로 다음과 같은 특징이 있습니다.

• Workflow를 사용하여 복수의 Agent를 제어할 수 있음
• LLM에 의한 추론과 Workflow에 의한 제어를 분리하기 쉬움
• Azure AI Foundry와의 통합을 의식하고 있음
• 단, 코어 기능은 Azure에 국한되지 않음
• OpenAI API나 로컬 LLM과도 조합할 수 있음

Semantic Kernel이 가지고 있던 엔터프라이즈 지향적인 통합성과, AutoGen이 가지고 있던 멀티 에이전트 오케스트레이션(Orchestration) 능력을 합치려 하고 있다는 이해를 하고 있습니다.

먼저, 각 릴리스를 '이행 비용(Migration Cost)'과 '도입 이점(Introduction Merit)'으로 나열하면 다음과 같습니다.

여기에서의 스코어는 엄격한 평가가 아니라, 릴리스 노트를 읽기 위한 기준입니다.

단, 완전한 주관으로만 치우치지 않기 위해 다음 식으로 기계적으로 계산했습니다.

이행 비용 = BREAKING 항목 수 * 3 + Changed 항목 수 + 차분 커밋 수 / 20
도입 이점 = Added 항목 수 * 2 + Fixed 항목 수 * 0.7 + 주요 기능 보너스
X 좌표 = 이행 비용 / 최대 이행 비용 * 0.9
...

주요 기능 보너스는 Provider 추가, Hosted Agent, Skills, MCP, HarnessAgent, 평가·관측성·안전성 등 사용자의 선택지를 넓히는 변경에 0 ~ 2 점을 부여하고 있습니다.

여기서 차분 커밋 수는 GitHub Releases의 비교 링크에서 확인할 수 있는 릴리스 간의 커밋 수를 가리킵니다.

이 스코어는 어떤 릴리스를 중점적으로 읽어야 할지를 파악하기 위한 기준입니다.

실제로 도입·업데이트할 때는 자신이 사용 중인 기능과 관련된 릴리스 노트와 차이점을 반드시 확인하십시오.

빨간색: 메이저 릴리스, 파란색: 마이너 릴리스, 초록색: 패치 릴리스

이 정리로 보면, python-1.3.0과 python-1.8.0은 이행 비용 대비 도입 이점이 큰 릴리스입니다.

반면, python-1.10.0은 도입 이점도 크지만 파괴적 변경이 많아, 기존 코드를 가지고 있는 경우에는 신중하게 확인하고 싶은 릴리스입니다.

하위 호환성(Backward Compatibility) 관점에서는 대략 다음과 같이 보고 있습니다.

버전	하위 호환성(Backward Compatibility) 리스크	이유
python-1.0.0	높음	정식 버전화에 따라 RC 호환 API 및 오래된 의존성(Dependency)이 정리됨.
python-1.0.1	중간	FileCheckpointStorage의 제한적 역직렬화(Deserialization)로 인해, 체크포인트(Checkpoint) 저장 내용에 따라 수정이 필요할 수 있음.
python-1.1.0	중간	CosmosCheckpointStorage 또한 제한적 역직렬화로 변경됨.
python-1.1.1	낮음	주로 평가(Evaluation), UI 연동, raw result 처리 개선.
python-1.2.0	낮음	Functional workflow API 등의 추가가 중심.
python-1.2.1	낮음~중간	변경(Changed) 항목은 많으나, 이용자 영향은 샘플 및 주변 환경에 국한됨.
python-1.2.2	중간	Orchestration 종단 출력의 AgentResponse 표준화로 인해, 반환값(Return value)에 의존하는 코드에 영향을 줄 수 있음.
python-1.3.0	중간	experimental skills API가 multi-source화되어, Skills 이용자의 확인이 필요함.
python-1.4.0	높음	Skills, DevUI, A2A 주변의 파괴적 변경(Breaking Changes)이 집중됨.
python-1.5.0	낮음	눈에 띄는 파괴적 변경은 적으며, MCP 주변의 안정화가 중심.
python-1.6.0	중간	instrumentation 기본 활성화로 인해, 운영 시 로그(Log), 트레이스(Trace), 비용에 영향을 줄 수 있음.
python-1.7.0	중간	Declarative actions 및 alias kind의 변경이 Declarative 이용자에게 영향을 미침.
python-1.8.0	높음	GitHub Copilot SDK v1.0화, experimental Skill API의 비동기(Async)화 등이 있음.
python-1.8.1	낮음	MCP의 관측성(Observability) 및 안전성 개선이 중심.
python-1.9.0	높음	MCP sampling, FileAccess tools, Declarative workflow 주변에 영향이 있음.
python-1.10.0	높음	Skills, FileAccess, FileMemory, HarnessAgent, Foundry Hosted Agent V2 프로토콜 업그레이드 등에 파괴적 변경이 집중됨.

릴리스 단위로 보면 세부적인 수정은 많지만, 이용자 관점에서는 다음의 흐름이 중요합니다.

관점	무엇이 바뀌었는가	주요 해당 버전
안정화 (Stabilization)	RC (Release Candidate)에서 정식 버전으로 승격되어, --pre 옵션 없이 도입할 수 있는 것을 전제로 함. 반면, RC 호환의 오래된 API나 의존 관계는 제거됨.	python-1.0.0
체크포인트 (Checkpoint)의 안전성	FileCheckpointStorage / CosmosCheckpointStorage의 pickle 역직렬화 (deserialization)가 제한되어, 커스텀 타입을 저장하는 경우 allowed_checkpoint_types를 명시해야 함.	python-1.0.1 , python-1.1.0
워크플로 (Workflow)를 에이전트 (Agent)로 사용하기 용이해짐	workflow.as_agent()에 context_providers 및 description이 추가되었으며, 오케스트레이션 (Orchestration)의 종단 출력도 AgentResponse로 통합됨.	python-1.1.0 , python-1.2.2
대응 프로바이더 및 연동 대상 증가	Gemini, Foundry Toolboxes, Hosted Agent V2, A2A bridge, Mistral embedding 등이 추가되어, 접속 대상 및 에이전트 간 연동 범위가 확장됨.	python-1.1.0 〜 python-1.8.0
평가 및 관측성 (Observability) 강화	evaluate_workflow의 ground-truth 대응, OpenTelemetry 연동, instrumentation 기본 활성화, MCP OTel span 등 운영 시 추적이 용이해짐.	python-1.1.1 , python-1.2.0 , python-1.6.0 , python-1.8.1
Skills / MCP / Harness Agent 주변 확장	Skills API, MCP 스킬 탐색, HarnessAgent, background agent, file access, loop, approval 등이 단기간에 크게 확장됨.	python-1.3.0 〜 python-1.10.0
도구 실행 (Tool execution)의 안전성	MCP sampling guardrails, file-access tools의 approval, SkillsProvider tools의 approval 기본 설정화 등 외부 조작을 억제하는 방향으로 진행됨.	python-1.9.0 , python-1.10.0
Foundry Hosted Agent의 진화	Hosted Agent V2, Toolbox, MCP, conversation session helper, Adaptive evals 등 Foundry 상에서 운용하기 위한 부품이 증가함.	python-1.1.0 , python-1.2.0 , python-1.7.0 , python-1.10.0

세세한 수정을 모두 나열하면 읽기 어려워지므로, 여기서는 "이용자에게 무엇이 바뀌는가"에 집중합니다.

Version	사용자 관점의 요약	마이그레이션 시 주의사항
python-1.0.0	정식 버전으로 안정화. agent-framework / core / OpenAI / Foundry를 프로덕션용 패키지로 취급할 수 있게 됨.	RC(Release Candidate)에서 업그레이드하는 경우, 의존성 하한선, Message(text=...), BaseContextProvider / BaseHistoryProvider 삭제에 주의.
python-1.0.1	Checkpoint 저장의 안정성이 향상되었고, Handoff workflow 관련 동작도 개선됨.	FileCheckpointStorage에 커스텀 타입을 저장하고 있는 경우, allowed_checkpoint_types를 지정하지 않으면 로드에 실패할 가능성이 있음.
python-1.1.0	Gemini, Foundry Toolboxes, Hosted Agent V2, workflow.as_agent() 확장 등 연결 대상과 Agent화의 범위가 넓어짐.	CosmosCheckpointStorage도 제한적 역직렬화(deserialization) 방식으로 변경됨. Cosmos checkpoint를 사용하는 경우 allowed_checkpoint_types를 확인해야 함.
python-1.1.1	evaluate_workflow의 기대 출력, AG-UI/A2A의 thread 전파, SKIP_PARSING 등 평가·UI 연동·raw result 처리 방식이 개선됨.	Hyperlight CodeAct의 공개 API 측면이 제한되었으므로, Hyperlight 이용 시 호출 측을 확인해야 함.
python-1.2.0	Functional workflow API, A2A bridge, GitHub Copilot Agent의 OTel 통합, Foundry의 OAuth consent event 대응이 포함됨.	Foundry hosted agent session 주변이 업데이트되었으므로, Hosted Agent 이용 시 세션 처리를 확인해야 함.
python-1.2.1	Hosted Agent Responses에서 file data type을 다룰 수 있게 되었으며, A2A hosting sample도 pip로 테스트하기 쉬워짐.	주로 의존성 업데이트가 많음. 프론트엔드 샘플 및 주변 도구를 포함한 환경 차이를 확인해야 함.
python-1.2.2	Orchestration의 최종 출력이 AgentResponse로 표준화되어, Workflow.as_agent()로부터 최종 답변을 다루기 쉬워짐.	Orchestration의 반환값에 의존하는 코드는 AgentResponse를 전제로 수정이 필요할 수 있음.
python-1.3.0	Skills의 multi-source화, Claude/Gemini/Mistral/Purview/Foundry 주변의 확장이 이루어져 대응 범위가 넓어짐.	experimental skills API가 파괴적(breaking)으로 재구성되었으므로, Skills를 사용 중인 경우 반드시 확인 필요.
python-1.4.0	file skill discovery, SkillFrontmatter, DevUI의 액세스 제어, A2A SDK v1.0 대응 등 주변 사양의 정합성이 개선됨.	Skills, DevUI, A2A를 사용하는 경우 파괴적 변경이 많음. 특히 공개 DevUI나 CORS 설정을 확인해야 함.
python-1.5.0	MCP prompt loading의 unsupported 케이스를 피하는 등, MCP 이용 시의 안정성이 개선됨.	눈에 띄는 파괴적 변경은 적으나, MCP 연동을 사용하는 경우 동작 차이를 확인해야 함.
python-1.6.0	Foundry Toolbox MCP의 인증 수단이 늘어났고, instrumentation이 기본적으로 활성화됨.	instrumentation 기본 활성화로 인해 로그·트레이스·텔레메트리(telemetry)의 출력 방식 및 비용을 확인해야 함.
python-1.7.0	HarnessAgent, background-agents harness provider, A2AAgentSession, prompt-agent conversion/deployment API 등 Agent 운용 형태가 다양해짐.

declarative actions의 Python 독자 사양이 삭제되었으며, alias kind가 C# 기준으로 조정되었습니다. Declarative를 사용하는 경우 마이그레이션에 주의하십시오. |
python-1.8.0 |
MCP skills discovery, progressive tool exposure, AgentFileStore/FileAccessProvider, Bedrock structured output, Mistral embedding 등이 추가되었습니다. | GitHub Copilot SDK v1.0화, experimental Skill API의 async화가 파괴적 변경(breaking change)입니다. Skills/GitHub Copilot 이용 시 확인이 필요합니다. |
python-1.8.1 |
MCP의 OTel span, long-running task, tool kwargs allowlist 등, MCP 연동의 관측성(observability)·안전성·안정성이 개선되었습니다. | 큰 파괴적 변경은 없으나, MCP tool 인수의 필터링 과정에서 불필요한 kwargs에 의존하고 있었다면 주의가 필요합니다. |
python-1.9.0 |
AgentLoopMiddleware, tool approval middleware, harness로의 shell/tool approval 통합 등, Agent를 루프 실행하거나 승인 절차를 거쳐 구동하기가 더 쉬워졌습니다. | MCP sampling은 기본적으로 거부되며, FileAccess tools의 사양도 .NET에 맞춰 변경되었습니다. MCP/FileAccess/Declarative 이용자는 확인이 필요합니다. |
python-1.10.0 |
Background agent loop, Foundry session helper, Adaptive evals, Durable Task worker, Azure AI Search API version 대응 등, 운영·평가·호스팅 측면이 강화되었습니다. | Skills/FileAccess/FileMemory/HarnessAgent/Foundry Hosted Agent V2 주변에서 파괴적 변경이 집중되었습니다. experimental 영역을 사용하는 경우 특히 신중하게 버전을 올려야 합니다. |

모든 변경 사항을 읽는 것은 힘들기 때문에, 자신이 사용 중인 기능부터 확인 대상을 좁히는 것이 좋습니다.

특히 영향이 클 것으로 예상되는 사용자는 다음과 같습니다.

• Workflow / Orchestration을 Agent로 사용하는 사람: python-1.2.2의 AgentResponse 표준화, workflow.as_agent() 주변의 변경 사항을 확인하십시오.
• Checkpoint를 영속화(persistence)하고 있는 사람: python-1.0.1과 python-1.1.0의 제한적 역직렬화(restricted deserialization)에 주의하십시오.
• Skills / MCP / HarnessAgent를 사용하는 사람: python-1.3.0 이후, 특히 python-1.8.0 ~ python-1.10.0은 파괴적 변경이 많습니다.
• Foundry Hosted Agent를 사용하는 사람: Hosted Agent V2, Toolbox, MCP, conversation session helper, V2 protocol upgrade를 추적해야 합니다.
• DevUI / A2A / Declarative를 사용하는 사람: python-1.4.0과 python-1.7.0, python-1.9.0의 변경 사항이 마이그레이션에 영향을 주기 쉽습니다.
• 관측성이나 본산 운영을 중시하는 사람: python-1.6.0 이후, instrumentation이나 OTel 관련 동작을 확인하십시오.

파괴적 변경 건수만 놓고 보면, agent-framework-core 주변, 특히 Skills / MCP / HarnessAgent / FileAccess / FileMemory에 변경이 집중되어 있습니다.

이 영역은 편리한 기능 추가도 많지만, 한편으로는 아직 설계가 진행 중이라는 인상을 줍니다.

영역	주의 사항	주요 해당 버전
agent-framework-core	Message, checkpoint, orchestration output, Skills, MCP, FileAccess, HarnessAgent 등 사용자가 직접 접하는 추상화 계층에서 파괴적 변경 (breaking changes)이 많음.	python-1.0.0 , python-1.2.2 , python-1.3.0 , python-1.8.0 〜python-1.10.0
Skills / MCP	FileSkillsSource, McpSkillsSource, resource/script lookup, tool approval, sampling guardrails 등이 단기간에 변경됨. experimental 취급의 파괴적 변경도 많음.	python-1.3.0 , python-1.4.0 , python-1.8.0 〜python-1.10.0
HarnessAgent / background agents	HarnessAgent, background agent, loop, FileMemory/FileAccess 통합이 추가 및 변경됨. Agent를 자율적으로 실행하는 용도에서는 마이그레이션 영향이 큼.	python-1.7.0 , python-1.8.0 , python-1.9.0 , python-1.10.0
FileAccess / FileMemory	.NET과의 정합성, approval 기본값 설정, read-only auto-approval, surgical edits, 명명 규칙 통일 등 도구의 안전성과 API 형태가 변경됨.	python-1.9.0 , python-1.10.0
Checkpoint storage	pickle 역직렬화 (deserialization)가 제한되어, 커스텀 타입을 영속화(persistence)하는 경우에는 허용 목록 (allowlist) 지정이 필요함.	python-1.0.1 , python-1.1.0
Foundry Hosted Agent	Hosted Agent V2, Toolbox, MCP, conversation session helper 등이 늘어난 반면, V2 protocol upgrade는 파괴적 변경임.	python-1.1.0 , python-1.2.0 , python-1.7.0 , python-1.10.0
Declarative	Python 독자 actions 삭제, alias kind의 C# canonical name화, workflow execution fixes 등 선언적 워크플로우 (declarative workflow) 사용자에게 영향을 주기 쉬움.	python-1.7.0 , python-1.9.0
DevUI / A2A	DevUI의 액세스 제어 및 CORS 강화, A2A SDK v1.0 마이그레이션 등 개발 UI 및 에이전트 간 프로토콜 사용에 영향을 미침.	python-1.4.0
GitHub Copilot 연동	github-copilot-sdk v1.0.0화, tool approval hook 연동 등 Copilot 연동 사용자는 SDK 측의 변경 사항도 확인해야 함.	python-1.8.0 , python-1.10.0
Observability	instrumentation 기본 활성화, OTel span 추가, serialized tool format의 OTel GenAI 형식 정합성 등 트레이스 (trace) 출력 및 모니터링 설정에 영향을 미침.	python-1.6.0 , python-1.8.1 , python-1.10.0

릴리스 본문을 보면, 파괴적 변경의 대부분은 experimental이라고 명시된 영역에 집중되어 있습니다.

특히 다음 영역은 기능 추가 속도가 빠른 만큼, API 형태나 기본 동작 (default behavior)도 바뀌기 쉽습니다.

• Skills
• MCP
• HarnessAgent
• FileAccess / FileMemory
• Foundry의 일부 API

@experimental이 붙은 기능은 "편리하니까 사용해도 좋다"가 아니라, 다음의 전제하에 다루어야 한다고 생각합니다.

• 마이너 버전 업데이트에서도 파괴적 변경 (Breaking Changes)이 포함될 수 있음
• 프로덕션 (Production) 코드에서는 래퍼 (Wrapper) 계층을 두어 직접적인 의존성을 줄임
• 버전을 고정하고, 업데이트 시에는 릴리스 노트 (Release Notes)와 차이점을 반드시 확인함
• 샘플 코드의 추종뿐만 아니라, 반환값(Return Value)·예외(Exception)·기본 동작(Default Behavior)을 테스트로 고정함
• 공식적으로 안정화 (Stable) 단계로 승격되었는지 확인함

@experimental

은 "아직 미완성이니 사용하지 마라"는 의미가 아닙니다.

다만, 프로덕션 (Production) / 안정화 (Stable) API와 동일한 이행 내성 (Migration Resilience)을 기대하면 위험합니다.

모든 파괴적 변경 (BREAKING Changes)을 나열하면 내용이 길어지므로, 사용자 관점에서 특히 주의해야 할 항목들만 뽑아보았습니다.

Version	변경 사항	영향
python-1.0.0	Message(text=...) 삭제, BaseContextProvider / BaseHistoryProvider alias 삭제	RC 시절의 코드를 그대로 사용하고 있는 경우 수정이 필요함.
python-1.0.1	FileCheckpointStorage의 제한적 역직렬화 (Deserialization)	커스텀 타입을 체크포인트 (Checkpoint)에 저장하고 있는 경우, allowed_checkpoint_types 설정이 필요함.
python-1.1.0	CosmosCheckpointStorage도 제한적 역직렬화로 변경	Cosmos DB 체크포인트를 사용하는 이용자도 마찬가지로 허용 목록 (Allowlist) 대응이 필요함.
python-1.2.2	오케스트레이션 (Orchestration) 최종 출력을 AgentResponse로 표준화	Workflow.as_agent()의 반환값에 의존하고 있는 코드에 영향을 미침.
python-1.3.0	실험적 스킬 (experimental skills) API의 멀티 소스 (multi-source)화	스킬 (Skills) 이용자는 API 구조를 재검토해야 함.
python-1.4.0	스킬 파일 디스커버리 (Skills file discovery) / 스킬 프론트매터 (SkillFrontmatter) 변경, DevUI 액세스 제어 강화, A2A SDK v1.0 이행	스킬 (Skills), DevUI, A2A를 사용하는 경우 일괄 확인이 필요함.
python-1.6.0	인스트루멘테이션 (instrumentation)이 기본적으로 활성화됨	프로덕션 환경의 로그(Log)·트레이스(Trace)·비용·개인정보 유입에 주의 필요.
python-1.7.0	Python 고유의 선언적 액션 (declarative actions) 삭제, alias kind를 C# 정형 이름 (canonical names)으로 변경	선언적 워크플로우 (Declarative workflow) 이용자는 이행이 필요함.
python-1.8.0	github-copilot-sdk v1.0.0화, 실험적 스킬 (experimental Skill) API 비동기 (async)화	GitHub Copilot 연동 및 스킬 (Skills) 이용자에게 영향을 미침.
python-1.9.0	MCP 샘플링 가드레일 (sampling guardrails), 파일 액세스 도구 (FileAccess tools) 변경, 선언적 워크플로우 (Declarative workflow) 수정	MCP / FileAccess / Declarative 이용자에게 영향을 미침.
python-1.10.0	FileSkillsSource, FileAccess, FileMemory, HarnessAgent, SkillsProvider 승인 (approval), Foundry Hosted Agent V2 프로토콜 업그레이드	실험적 (experimental) 영역과 Foundry Hosted Agent 이용자는 특히 주의 필요.

python-1.0.0에서 python-1.10.0까지를 살펴보면, 에이전트 프레임워크 (Agent Framework)는 정식 버전이 된 직후부터 상당히 빠른 속도로 진화하고 있습니다.

사용자 관점에서는 특히 다음과 같은 흐름이 중요합니다.

• 우선 안정화 단계에 따라 RC 호환 API가 정리됨
• 체크포인트 (Checkpoint) 관련 기능은 안전한 방향으로 조정됨
• 워크플로우 (Workflow) / 오케스트레이션 (Orchestration)은 에이전트 (Agent)로서 다루기 쉬워짐
• 스킬 (Skills) / MCP / HarnessAgent / FileAccess 관련 기능은 급격히 확장됨
• 도구 실행은 승인 (approval)이나 가드레일 (guardrails)을 통해 안전성을 중시하는 방향으로 기울어짐
• Foundry Hosted Agent 관련 기능은 운영 기능이 늘어나는 동시에 프로토콜 (protocol) 변경도 발생함

세세한 버그 수정은 많지만, 마이그레이션(migration) 시 가장 주의 깊게 살펴봐야 할 점은 자신이 사용 중인 추상화(abstraction)가 무엇인지입니다.

특히 @experimental 영역을 사용하고 있는 경우에는, 마이너 버전 업데이트(minor version up)라 하더라도 파괴적 변경(breaking changes)이 포함될 수 있다는 전제하에 릴리스 노트(release note)와 차이점(diff)을 확인하는 것이 좋다고 생각합니다.