agent-framework

Microsoft Agent Framework에 오신 것을 환영합니다!

Microsoft Agent Framework(MAF)는 .NET과 Python에서 프로덕션 수준의 AI 에이전트와 멀티 에이전트 워크플로를 구축하기 위한 개방형 다국어 프레임워크입니다.

Microsoft Agent Framework는 에이전트를 프로토타입에서 프로덕션으로 전환하는 팀을 위해 만들어졌습니다. Python, .NET, Go 전반에 걸쳐 에이전트 시스템을 구축, 오케스트레이션, 운영하기 위한 일관된 기반을 제공하며, 요구 사항이 변화함에 따라 아키텍처 선택의 폭을 열어둡니다. 또한 Microsoft Foundry, Azure OpenAI, OpenAI, GitHub Copilot SDK를 포함한 광범위한 에코시스템을 지원하며, 로컬 개발과 클라우드 배포 모두를 위한 샘플과 호스팅 패턴을 제공합니다.

참고

Go SDK의 문서, 샘플, 기여 가이드, 이슈 트래커를 포함한 자세한 내용은 microsoft/agent-framework-go를 방문하세요.

Agent Framework 전체 소개 영상 보기 (30분)

이 프레임워크가 적합한가요?
MAF는 다음과 같은 경우에 적합합니다:

프로덕션에서 실행할 에이전트와 워크플로를 구축하고 있는 경우,
단일 프롬프트나 상태 비저장 채팅 루프를 넘어서는 오케스트레이션이 필요한 경우,
순차, 동시, 핸드오프, 그룹 협업과 같은 그래프 기반 패턴을 원하는 경우,
내구성, 재시작 가능성, 관찰 가능성, 거버넌스, 휴먼 인 더 루프 제어를 중요하게 여기는 경우,
대규모 재작성 없이 아키텍처를 발전시킬 수 있도록 공급자 유연성이 필요한 경우.

주요 기능
공식 블로그에서 새로운 MAF 기능과 실제 구현 패턴을 살펴보세요.

Python 및 C#/.NET 지원 : 일관된 API로 Python과 C#/.NET 구현 모두를 완벽하게 지원

Python 패키지 | .NET 소스

Go 지원 : Go SDK의 문서, 샘플, 기여 가이드, 이슈 트래커를 포함한 자세한 내용은 microsoft/agent-framework-go를 방문하세요.
다양한 에이전트 공급자 지원 : 다양한 LLM 공급자를 지원하며 지속적으로 추가되고 있습니다

Python 예제 | .NET 예제

미들웨어 : 요청/응답 처리, 예외 처리, 사용자 정의 파이프라인을 위한 유연한 미들웨어 시스템

Python 미들웨어 | .NET 미들웨어

오케스트레이션 패턴 및 워크플로 : 순차, 동시, 핸드오프, 그룹 협업 패턴을 지원하는 그래프 기반 워크플로로 멀티 에이전트 시스템 구축; 체크포인팅, 스트리밍, 휴먼 인 더 루프, 타임 트래블 포함

Python 워크플로 | .NET 워크플로

Foundry 호스팅 에이전트 (신규) : 단 2줄의 추가 코드로 에이전트를 Foundry 호스팅 인프라에 배포 및 호스팅

Python 샘플 | .NET 샘플

관찰 가능성 : 분산 추적, 모니터링, 디버깅을 위한 내장 OpenTelemetry 통합

Python 관찰 가능성 | .NET 텔레메트리

선언적 에이전트 : YAML로 에이전트를 정의하여 더 빠른 설정과 버전 관리

선언적 에이전트 샘플

에이전트 스킬 : 파일, 인라인 코드, 클래스 라이브러리 등 여러 소스에서 에이전트가 발견하고 사용할 수 있는 도메인별 지식 기반 구축

스킬 설계

AF Labs : 벤치마킹, 강화 학습, 연구 이니셔티브를 포함한 최첨단 기능을 위한 실험적 패키지

Labs 디렉터리

DevUI : 에이전트 개발, 테스트, 워크플로 디버깅을 위한 대화형 개발자 UI

DevUI 실제 동작 보기

목차

시작하기

설치
학습 리소스
빠른 시작

기본 에이전트 - Python
기본 에이전트 - .NET

코딩 에이전트를 위한 에이전트 스킬
추가 예제 및 샘플
커뮤니티 및 피드백
문제 해결
기여자 리소스

시작하기
설치
Python

pip install agent-framework
# 표준 패키지 세트를 설치합니다. 실험적 모듈은 `agent-framework-lab`을 별도로 설치하세요.
# Windows에서 처음 설치 시 1분 정도 걸릴 수 있습니다.
.NET

dotnet add package Microsoft.Agents.AI
# Foundry 통합용 (아래 .NET 빠른 시작에서 사용):
dotnet add package Microsoft.Agents.AI.Foundry
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity
학습 리소스

개요 - 프레임워크의 상위 수준 개요
빠른 시작 - 간단한 에이전트로 시작하기
튜토리얼 - 단계별 튜토리얼
사용자 가이드 - 에이전트와 워크플로 구축을 위한 심층 사용자 가이드
Semantic Kernel에서 마이그레이션 - Semantic Kernel에서 마이그레이션하는 가이드
AutoGen에서 마이그레이션 - AutoGen에서 마이그레이션하는 가이드

빠른 시작
기본 에이전트 - Python
Microsoft Agent Framework에 대한 하이쿠를 작성하는 간단한 Azure Responses 에이전트 만들기

# pip install agent-framework
# Azure CLI로 인증하려면 `az login`을 사용하세요
import os
import asyncio
from agent_framework import Agent
from agent_framework . foundry import FoundryChatClient
from azure . identity import AzureCliCredential

async def main ():
# Microsoft Foundry로 채팅 에이전트 초기화
# 엔드포인트, 배포 이름, api 버전은 환경 변수로 설정하거나
# FoundryChatClient 생성자에 직접 전달할 수 있습니다
agent = Agent (
client = FoundryChatClient (
credential = AzureCliCredential (),
# project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
# model=os.environ["FOUNDRY_MODEL"],
),
name = "HaikuAgent" ,
instructions = "You are an upbeat assistant that writes beautifully." ,
)

print ( await agent . run ( "Write a haiku about Microsoft Agent Framework." ))

if __name__ == "__main__" :
asyncio . run ( main ())
기본 에이전트 - .NET
Microsoft Foundry를 사용하여 Microsoft Agent Framework에 대한 하이쿠를 작성하는 간단한 에이전트 만들기

// 이 샘플은 AIProjectClient.AsAIAgent(...)로 기본 에이전트를 생성하고 실행하는 방법을 보여줍니다.

using Azure . AI . Projects ;
using Azure . Identity ;
using Microsoft . Agents . AI ;

string endpoint = Environment . GetEnvironmentVariable ( "FOUNDRY_PROJECT_ENDPOINT" ) ?? throw new InvalidOperationException ( "FOUNDRY_PROJECT_ENDPOINT is not set." ) ;
string deploymentName = Environment . GetEnvironmentVariable ( "FOUNDRY_MODEL" ) ?? "gpt-5.4-mini" ;

AIAgent agent =
new AIProjectClient ( new Uri ( endpoint ) , new DefaultAzureCredential ( ) )
. AsAIAgent ( model : deploymentName , instructions : "You are an upbeat assistant that writes beautifully." , name : "HaikuAgent" ) ;

// 에이전트를 만들었으면 다른 AIAgent처럼 호출할 수 있습니다.
Console . WriteLine ( await agent . RunAsync ( "Write a haiku about Microsoft Agent Framework." ) ) ;
코딩 에이전트를 위한 에이전트 스킬
Python Agent Framework 빌더 스킬을 설치하여 호환되는 코딩 에이전트에 에이전트, 하네스, 워크플로, 평가, 통합, 호스팅을 선택하고 구축하기 위한 최신 가이드를 제공하세요:

gh skill install microsoft/agent-framework agent-framework-builder-python@main
태그가 지정된 Agent Framework 릴리스에 스킬이 포함될 때까지 명시적인 @main ref가 필요합니다.

크로스 에이전트 스킬 CLI도 지원됩니다:

npx skills add microsoft/agent-framework --skill agent-framework-builder-python
자세한 내용은 소비자 스킬 카탈로그를 참조하세요.

추가 예제 및 샘플
Python

시작하기 : hello-world에서 워크플로까지의 점진적 튜토리얼
에이전트 개념 : 주제별 심층 샘플 (도구, 미들웨어, 공급자 등)
워크플로 : 워크플로 생성 및 에이전트와의 통합
호스팅 : A2A, 자체 호스팅 프로토콜 헬퍼, Foundry 호스팅 에이전트. Durable Task 및 Azure Functions 샘플은 Durable Agent Framework 확장에 있습니다.
엔드 투 엔드 : 전체 애플리케이션, 평가, 데모

.NET

시작하기 : hello agent에서 워크플로까지의 점진적 튜토리얼
에이전트 개념 : 기본 에이전트 생성 및 도구 사용
에이전트 공급자 : 다양한 에이전트 공급자를 보여주는 샘플
워크플로 : 고급 멀티 에이전트 패턴 및 워크플로 오케스트레이션
호스팅 : A2A 및 Foundry 호스팅 에이전트. Durable 에이전트 및 워크플로 샘플은 Durable Agent Framework 확장에 있습니다.
엔드 투 엔드 : 전체 애플리케이션 및 데모

커뮤니티 및 피드백

버그를 발견하셨나요? GitHub 이슈를 등록하여 개선에 도움을 주세요.
MAF가 마음에 드시나요? 를 눌러 지지를 표시하고 다른 사람들이 프로젝트를 발견하도록 도와주세요.
질문이 있으신가요? Discord에 참여하거나 주간 오피스 아워를 방문하세요.

문제 해결
인증

문제
원인
해결 방법

Azure 자격 증명 사용 시 인증 오류
Azure CLI에 로그인하지 않음
앱을 시작하기 전에 az login 실행

API 키 오류
잘못되었거나 누락된 API 키
키를 확인하고 올바른 리소스/공급자에 대한 키인지 확인

팁: DefaultAzureCredential은 개발에 편리하지만 프로덕션에서는 특정 자격 증명(예: ManagedIdentityCredential)을 사용하여 지연 문제, 의도하지 않은 자격 증명 탐색, 폴백 메커니즘으로 인한 잠재적 보안 위험을 피하는 것을 고려하세요.

환경 변수
각 샘플에 특정한 환경 변수 구성은 샘플 디렉터리의 README를 참조하세요 ( Python 샘플 | .NET 샘플 ).

기여자 리소스

기여 가이드
AI 지원 기여 정책
행동 강령
Python 개발 가이드
설계 문서
아키텍처 결정 기록

중요 사항
중요

Microsoft Agent Framework를 사용하여 타사 서버, 에이전트, 코드 또는 비 Azure Direct 모델("타사 시스템")과 함께 작동하는 애플리케이션을 구축하는 경우 이는 귀하의 책임 하에 이루어집니다. 타사 시스템은 Microsoft 제품 약관에 따른 비 Microsoft 제품이며 자체 타사 라이선스 약관의 적용을 받습니다. 모든 사용 및 관련 비용은 귀하의 책임입니다.

타사 시스템과 공유되고 타사 시스템으로부터 수신되는 모든 데이터를 검토하고, 데이터 처리, 공유, 보존 및 위치에 관한 타사 관행을 인지할 것을 권장합니다. 귀하의 데이터가 조직의 Azure 규정 준수 및 지리적 경계 외부로 흐를지 여부와 관련 영향, 그리고 적절한 권한, 경계, 승인이 프로비저닝되었는지 여부를 관리하는 것은 귀하의 책임입니다.

Microsoft Agent Framework를 사용하여 구축한 애플리케이션을 귀하의 특정 사용 사례 맥락에서 신중하게 검토하고 테스트하며, 모든 적절한 결정과 사용자 정의를 내리는 것은 귀하의 책임입니다. 여기에는 자체 책임 있는 AI 완화 조치(예: 메타프롬프트, 콘텐츠 필터 또는 기타 안전 시스템)를 구현하고 애플리케이션이 적절한 품질, 신뢰성, 보안, 신뢰성 표준을 충족하도록 보장하는 것이 포함됩니다. 참조: 투명성 FAQ