Microsoft Agent Framework
Microsoft Agent Framework for Go에 오신 것을 환영합니다!
Microsoft Foundry Discord
MS Learn Documentation
Go Reference
GitHub stars
Microsoft Agent Framework (MAF)는 프로덕션급 AI 에이전트 및 다중 에이전트 워크플로우를 구축하기 위한 오픈 소스, 다국어 프레임워크입니다. 이 저장소에는 Microsoft Agent Framework의 Go 구현과 시작하는 데 도움이 되는 Go 샘플 및 문서가 포함되어 있습니다.
Microsoft Agent Framework는 에이전트를 프로토타입 단계에서 프로덕션 단계로 가져가는 팀을 위해 구축되었습니다. 이 프레임워크는 요구 사항이 진화함에 따라 아키텍처 선택을 열어두면서 에이전트 시스템 구축, 오케스트레이션(orchestrating), 운영을 위한 일관된 기반을 제공하며, Microsoft Foundry, Azure OpenAI, OpenAI, Model Context Protocol (MCP), Agent2Agent (A2A), AG-UI, GitHub Copilot SDK를 포함하는 광범위한 생태계를 지원합니다.
.NET 및 Python 구현체는 상위(upstream) Microsoft Agent Framework 저장소에서 사용할 수 있습니다.
참고: Microsoft Agent Framework for Go는 Public Preview 상태이며 현재 핵심 상위 코드베이스 외부에서 발전하고 있습니다. 채택 및 피드백이 증가함에 따라 더 광범위한 MAF 생태계와 더욱 긴밀하게 통합될 것으로 예상합니다.
<p align="center">
<a href="https://www.youtube.com/watch?v=AAgdMhftj8w" title="Watch the full Agent Framework introduction (30 min)">
<img src="https://img.youtube.com/vi/AAgdMhftj8w/hqdefault.jpg"
alt="Watch the full Agent Framework introduction (30 min)" width="480">
</a>
</p>
<p align="center">
<a href="https://www.youtube.com/watch?v=AAgdMhftj8w">
전체 Agent Framework 소개 시청하기 (30분)
</a>
</p>
이 프레임워크가 적합한가요?
MAF는 다음 조건에 해당한다면 강력하게 추천됩니다:
- 프로덕션 환경에서 실행되기를 기대하는 에이전트와 워크플로우를 구축하고 있거나,
- 단일 프롬프트나 상태 비저장(stateless) 채팅 루프 이상의 오케스트레이션(orchestration)이 필요하거나,
- 순차적(sequential), 동시적(concurrent), 그룹 협업, 사용자 지정 워크플로우 라우팅과 같은 그래프 기반 패턴을 원하거나,
- 체크포인팅(checkpointing), 재시작 가능성(restartability), 관측 가능성(observability), 거버넌스(governance), 또는 인간 개입형 제어(human-in-the-loop)에 신경 써야 하거나,
- 아키텍처가 대규모 재작성 없이 진화할 수 있도록 제공업체 유연성이 필요합니다.
주요 기능 (Key Features)
공식 블로그에서 새로운 MAF 기능과 실제 구현 패턴을 살펴보세요.
상세한 .NET 대 Go 기능 비교는 .NET 및 Go SDK 기능 비교를 참조하십시오. 간단히 말해, Go SDK는 핵심 에이전트, 도구(tools), 미들웨어, 워크플로우, 관측 가능성 및 상호 운용성 통합을 다루며, 반면 .NET은 현재 더 광범위한 제품 통합과 아직 Go에 구현되지 않은 여러 기능을 가지고 있습니다.
-
Go 지원 (Go Support): Go에서 에이전트와 워크플로우를 구축하기 위한 Go 패키지, 예제 및 API.
-
다중 에이전트 제공업체 지원 (Multiple Agent Provider Support): 다양한 LLM 및 에이전트 제공업체를 지원하며, 지속적으로 더 많은 제공업체가 추가되고 있습니다.
-
미들웨어 (Middleware): 요청/응답 처리, 로깅, OpenTelemetry, 컨텍스트 제공업체(context providers), 도구 승인 및 자동 도구 호출을 위한 유연한 미들웨어.
-
오케스트레이션 패턴 및 워크플로우 (Orchestration Patterns & Workflows): 순차적, 동시적, 그룹 협업, 조건부 라우팅(conditional routing), 서브워크플로우(subworkflows), 체크포인팅, 스트리밍, 인간 개입형(human-in-the-loop), 시간 여행 패턴을 지원하는 그래프 기반 워크플로우로 멀티 에이전트 시스템을 구축할 수 있습니다. 핸드오프 오케스트레이션은 아직 Go SDK에 구현되지 않았습니다.
-
[워크플로우 예시 (Workflow examples)]](./examples/03-workflows/) | [워크플로우 패키지 (Workflow package)]](./workflow/)
-
Microsoft Foundry Agents: 프로젝트 기반의 Foundry 에이전트를 구축하고, 기존 서버 측 Foundry 에이전트를 호출하며, Foundry 클라이언트 헤더를 전달하고, 서비스된 모델 메타데이터를 캡처하며, Foundry 메모리를 사용합니다. Foundry 호스팅 배포는 Go SDK에 아직 구현되지 않았습니다.
- [Foundry 예시 (Foundry examples)]](./examples/02-agents/providers/foundry/) | [Foundry 제공자 (Foundry provider)]
./provider/foundryprovider/
-
관측 가능성 (Observability): 분산 추적(distributed tracing), 모니터링 및 디버깅을 위한 OpenTelemetry 통합.
-
선언적 에이전트 (Declarative Agents): Go SDK에 아직 구현되지 않았습니다.
-
에이전트 스킬 (Agent Skills): 파일, 인라인 정의 및 스크립트를 사용하여 에이전트가 발견하고 사용할 수 있는 도메인별 지식 기반을 구축합니다.
- [스킬 예시 (Skills examples)]](./examples/02-agents/skills/) | [스킬 패키지 (Skills package)]
./agent/skills/
-
텍스트 검색 (Text Search) (RAG): 에이전트 실행 전 또는 온디맨드(on-demand) 검색 도구를 통해 외부 지식을 자동으로 검색하고 인용하며, 선택적으로 세션 기반의 최근 메시지 메모리를 지원합니다.
- [텍스트 검색 패키지 (Text search package)]
./agent/textsearch/ | [RAG 예시 (RAG examples)] ./examples/02-agents/rag/
-
채팅 기록 메모리 (Chat History Memory): 대화를 벡터 스토어(vector store)에 저장하고, 범위가 지정된 메모리를 자동으로 또는 온디맨드 도구를 통해 검색합니다.
- [메모리 패키지 (Memory package)]
./agent/memory/ | [메모리 예시 (Memory examples)] ./examples/02-agents/memory/
-
영구 채팅 기록 (Persistent Chat History): 세션 기반 라우팅(session-backed routing), 구성 가능한 보존 기간(configurable retention), 기록 개수 및 삭제 기능을 갖춘 Cosmos DB에 범위가 지정된 대화를 저장합니다.
-
임베딩 (Embeddings): 제공자 독립적인 배치 생성(Provider-independent batch generation), 숫자 및 이진 벡터(numeric and binary vectors), 요청 옵션, 사용 메타데이터, 그리고 단일 입력/벡터/배치 쌍 도우미 기능을 제공하며, OpenAI/Foundry 어댑터와 선택적 OpenTelemetry 계측 기능이 포함됩니다.
-
임베딩 패키지 | OpenAI 임베딩 생성기 | Foundry 임베딩 생성기
-
벡터 데이터 (Vector Data): 타입별 및 동적 컬렉션을 가진 벡터 저장소, CRUD 헬퍼, 그리고 휴대 가능한 필터가 적용된 벡터/하이브리드 검색 옵션을 제공합니다. Azure AI Search와 정확한 벡터 검색, 배치 임베딩 생성, JSON 스냅샷을 갖춘 인메모리 커넥터를 포함합니다.
-
AF Labs: Go SDK에서는 아직 구현되지 않았습니다.
-
DevUI: Go SDK에서는 아직 구현되지 않았습니다.
목차 (Table of Contents)
시작하기 (Getting Started)
설치 (Installation)
Go
go get github.com/microsoft/agent-framework-go
학습 자료 (Learning Resources)
- 개요 - 프레임워크의 높은 수준 개요
- 빠른 시작 - 간단한 에이전트로 시작하기
- 튜토리얼 - 단계별 튜토리얼
- 사용자 가이드 - 에이전트 및 워크플로우 구축을 위한 심층 사용자 가이드
빠른 시작
기본 에이전트 - Go
Microsoft Foundry에서 Microsoft Agent Framework에 대한 하이쿠(haiku)를 작성하는 간단한 에이전트를 만드세요.
package main
import (
...
더 많은 예제 및 샘플
Go
- 시작하기: 헬로 월드부터 워크플로우까지의 점진적 튜토리얼
- 에이전트 개념: 도구(tools), 미들웨어(middleware), 프로바이더(providers), 관찰 가능성(observability), A2A, AG-UI, MCP 및 스킬을 포함한 주제별 심층 샘플
- 파일 메모리: 개별 사용자 간 대화 전반에 걸쳐 메모리를 유지합니다.
az login으로 인증한 후, 리포지토리 루트에서 FOUNDRY_PROJECT_ENDPOINT와 FOUNDRY_MODEL을 설정하고 go run ./examples/02-agents/agents/step24_filememory를 실행합니다. 파일은 실행 간에 agent-memory/users/UID1에 남아 있습니다.
- 에이전트 하네스: 일반 프로바이더 생성자를 사용하여 사전 구성된 메모리, 스킬, Todo, 모드(modes), 승인(approvals), 히스토리 및 추적 기능을 위해
harness.AgentConfig를 사용합니다. Foundry 예제가 포함되어 있습니다.
- 워크플로우: 다중 에이전트 패턴, 라우팅(routing), 체크포인팅(checkpointing), 관찰 가능성(observability) 및 워크플로우 오케스트레이션
- 엔드투엔드: 전체 애플리케이션 및 데모
- 기능 비교: .NET 및 Go SDK 기능 동등성 참고 사항
커뮤니티 및 피드백
- 버그를 발견했나요? 개선에 도움을 주려면 GitHub 이슈를 제출해 주세요.
- MAF for Go를 사용하고 계신가요? GitHub stars를 통해 지지를 보여주고 다른 사람들이 프로젝트를 발견하도록 도와주세요.
- 질문이 있나요? 저희 Discord에 참여해 주세요.
문제 해결 (Troubleshooting)
인증 (Authentication)
| 문제 | 원인 | 해결 방법 |
|---|
| Azure 자격 증명 사용 시 인증 오류 발생 | Azure CLI 또는 다른 구성된 자격 증명 소스에 로그인하지 않음 | 앱을 시작하기 전에 az login을 실행하거나, 앱이 사용하는 특정 자격 증명을 구성하세요. |
팁: DefaultAzureCredential은 개발 단계에서 편리하지만, 프로덕션 환경에서는 지연 시간 문제, 의도치 않은 자격 증명 탐색(credential probing), 그리고 폴백 메커니즘으로 인한 잠재적 보안 위험을 피하기 위해 관리형 ID(managed identity)와 같은 특정 자격 증명을 사용하는 것을 고려하세요.
환경 변수 (Environment Variables)
각 샘플에 특화된 환경 변수 구성을 위해서는 examples 아래의 샘플 디렉터리 내 README 또는 소스를 참조하세요.
기여자 리소스 (Contributor Resources)
중요 참고 사항 (Important Notes)
