실습 노트
Microsoft Agent Framework에서 에이전트와 워크플로를 나누는 방법: 체크포인트·승인 기준
Microsoft Agent Framework 공식 문서와 Python 1.17.0 릴리스를 바탕으로 에이전트와 고정 워크플로를 나누고, 사람 승인·체크포인트·관측성을 설계하는 기준을 정리합니다.
여러 단계의 문서·코드 업무에 AI를 연결하려는 팀이라면 모델 이름보다 먼저 실행 순서와 사람의 승인 지점을 정해야 합니다. Microsoft Agent Framework는 에이전트와 고정된 워크플로를 Python·.NET 코드 안에서 구성하고, 체크포인트와 관측성을 함께 검토할 수 있는 오픈소스 프레임워크입니다. 이 글은 어떤 단계를 에이전트에 맡기고 어떤 단계는 함수나 사람의 확인으로 남길지 판단하는 데 초점을 둡니다.
에이전트와 워크플로는 언제 나누나요?
Microsoft Learn은 에이전트를 개방형 대화와 자율적인 도구 선택에 맞는 구성으로 설명합니다. 반면 워크플로는 여러 함수나 에이전트가 정해진 실행 경로로 협력해야 할 때 적합합니다.
이 기준은 제품 이름보다 업무의 불확실성을 봅니다. 자료에서 핵심 내용을 찾는 일은 에이전트가 맡을 수 있습니다. 원문 대조, 숫자 계산, 권한 확인처럼 규칙을 코드로 적을 수 있는 일은 일반 함수가 더 분명할 수 있습니다. Microsoft Learn도 함수로 처리할 수 있는 일이라면 AI 에이전트보다 함수를 사용하라고 안내합니다.
예를 들어 회의 자료를 보고 보고서를 만드는 흐름을 다음처럼 나눌 수 있습니다.
자료 입력 → 초안 작성 → 원문·수치 대조 → 사람 승인 → 외부 전달
이 흐름에서 프레임워크가 맡는 일과 조직이 정해야 하는 일은 다릅니다.
| 단계 | 프레임워크로 구성할 수 있는 부분 | 조직이 정할 부분 |
|---|---|---|
| 자료 입력 | 에이전트 세션과 도구 연결 | 입력 가능한 자료와 계정 권한 |
| 초안 작성 | 모델 호출과 에이전트 지시 | 초안의 형식과 누락 허용 범위 |
| 원문·수치 대조 | 함수·워크플로 단계와 결과 전달 | 대조할 원본과 실패 판정 |
| 사람 승인 | 중단·재개와 승인 이벤트 | 승인자와 승인 뒤 외부 효과 |
| 외부 전달 | 승인된 단계의 도구 호출 | 발송·공유 권한과 되돌리기 절차 |
앞의 두 번째 열은 Microsoft가 README와 Learn에서 설명하는 기능 범위입니다. 세 번째 열은 그 기능을 실제 업무에 적용할 때 필요한 운영 판단입니다.
초안 작성은 에이전트의 판단이 필요한 단계입니다. 원문·수치 대조와 외부 전달은 각각 확인 규칙과 권한 경계를 둔 별도 단계가 됩니다. 이렇게 나누면 모델이 만든 초안과 실제로 외부 시스템에 쓰인 결과를 같은 것으로 취급하지 않게 됩니다.
사람 승인은 어디에 둘까요?
사람 승인은 모든 단계에 붙이는 버튼이 아닙니다. 외부 상태를 바꾸거나 되돌리기 어려운 단계에 둬야 합니다. 메일 발송, 결재 등록, 공개 게시, 파일 삭제, 비용 발생처럼 결과가 조직 밖으로 나가는 작업이 대표적입니다.
승인 단계에는 최소한 세 가지 정보가 보여야 합니다.
- AI가 만들거나 선택한 결과물
- 결과를 만든 입력 자료와 도구 호출
- 승인 뒤 발생할 외부 변경과 되돌리는 방법
승인자가 원문과 결과를 비교할 수 없다면 버튼만 추가해도 판단 품질이 올라가지 않습니다. 승인 전에는 외부 쓰기 권한을 주지 않고, 승인 뒤 실행된 요청과 응답을 기록하는 방식이 경계를 더 분명하게 만듭니다.
중단된 작업은 어디서 재개하나요?
공식 README는 워크플로 기능으로 체크포인트, 스트리밍, 사람 개입과 재실행을 안내합니다. 체크포인트는 작업의 특정 시점과 상태를 저장해 중단 뒤 이어 갈 기준을 만드는 구조입니다.
도입할 때는 “재개된다”는 문장만 확인하지 말고 단계별 입력·출력과 외부 효과를 표로 적어야 합니다. 초안 생성은 다시 실행해도 되지만, 결재 등록이나 메일 발송은 같은 작업이 두 번 실행되면 곤란합니다. 외부 효과가 있는 단계에는 요청 ID나 중복 실행 방지 규칙을 두고, 재개 시 이미 처리된 결과를 판별할 수 있어야 합니다.
체크포인트를 보존하는 위치와 접근자도 정해야 합니다. 업무 문서와 도구 결과가 상태에 포함된다면 저장 기간, 백업 범위와 삭제 요청 처리까지 코드 밖의 운영 규칙에 들어갑니다.
실행 과정을 어떻게 관찰하나요?
Microsoft Agent Framework 공식 README는 OpenTelemetry 연동을 기능 범위로 제시합니다. 관측성은 성공한 최종 답변을 보는 기능만을 뜻하지 않습니다. 어느 단계에서 어떤 도구가 호출됐고, 어떤 결과가 다음 단계로 전달됐으며, 어디서 사람이 승인하거나 중단했는지를 확인하는 데 필요합니다.
작은 실험에서도 다음 기록을 남기면 비교가 쉬워집니다.
- 작업 ID와 실행한 워크플로 버전
- 사용한 모델과 도구 이름
- 각 단계의 시작·종료 시각과 성공·실패 상태
- 승인자, 승인 시각과 외부 변경의 식별자
프롬프트 전체나 민감한 도구 결과를 무조건 로그에 넣을 필요는 없습니다. 대신 나중에 실패 원인을 재현할 수 있는 최소 입력과 결과 요약을 정하고, 개인정보·자격 증명·내부 문서가 로그로 복제되지 않는지 확인해야 합니다.
공급자가 달라도 실행 책임은 어디에 남나요?
도구 호출 기능은 여러 공급자에 있지만, 모델이 도구를 골랐다는 사실과 애플리케이션이 실제 함수를 실행했다는 사실은 구분해야 합니다. Google Gemini API 문서는 모델이 함수 호출과 인자를 반환하고 함수 코드는 애플리케이션이 실행한다고 설명합니다. xAI 문서도 사용자 정의 도구는 애플리케이션으로 돌아와 처리하며, 서버에서 실행되는 기본 도구와 구분한다고 안내합니다.
이 차이를 업무 흐름에 옮기면 모델의 선택 → 인자 검증 → 함수 실행 → 결과 기록 → 다음 단계가 됩니다. 메일 발송이나 데이터 변경을 함수 안에 넣었다면, 함수 실행 직전에 승인 상태와 권한을 다시 확인해야 합니다. 모델 응답을 그대로 실행 함수의 입력으로 쓰지 않는 이유입니다.
공급자 안전 문서의 표현도 같은 방향을 가리킵니다. OpenAI는 에이전트가 구매·메일 발송 같은 결과를 만들기 전에 확인할 때 실제 행동과 공유 정보를 검토하라고 설명합니다. Anthropic은 모델·실행 환경·외부 콘텐츠를 함께 방어해야 하며 단일 방어선이 보장을 제공하지 않는다고 설명합니다. GitHub Copilot의 콘텐츠 제외는 관리자 정책으로 제외 파일이 에이전트 컨텍스트에 들어가지 않게 하는 범위를 제공하지만, 터미널·외부 도구·승인 절차까지 대신 설계하지는 않습니다.
따라서 Microsoft Agent Framework를 선택하더라도 비교의 끝은 SDK 기능표가 아닙니다. 조직이 허용하는 입력, 실행 가능한 도구, 사람 승인, 기록과 복구를 한 흐름으로 시험할 수 있는지가 먼저입니다.
Python 1.17.0 릴리스에서 무엇을 확인했나요?
공식 릴리스 기록에 따르면 Python 1.17.0은 2026년 9월 3일 공개됐습니다. 이 릴리스에는 Foundry 호스팅 Telegram 에이전트 예제와 에이전트가 소유한 모델 기록을 선택하는 동작이 포함됐습니다. 후자는 대화 기록을 중복으로 재생하는 문제를 피하기 위한 방향을 보여줍니다.
같은 릴리스에는 승인 호출, 재개 상관관계, 병렬 결과, 제공자 거부 응답과 MCP 취소 오류를 다루는 수정 사항도 기록되어 있습니다. 이 내용은 프로젝트가 어떤 실행 경계를 계속 다듬는지 보여주는 공급자 릴리스 기록입니다. 특정 조직의 안정성이나 보안이 보장됐다는 독립 평가로 해석하면 안 됩니다.
어떤 한계를 먼저 확인해야 하나요?
Microsoft의 공식 README는 이 프로젝트를 production-grade 방향의 프레임워크로 소개합니다. 이 표현은 공급자가 제시한 프로젝트 방향입니다. 인증, 특정 규정 준수, 장애율이나 비용을 독립적으로 보증하는 표현은 아닙니다.
공식 빠른 시작은 Azure 자격 증명과 Foundry 클라이언트를 사용하는 예제를 포함합니다. Azure를 쓰지 않는 팀은 사용할 모델 공급자, 인증 방식, 데이터가 이동하는 서비스와 비용을 따로 확인해야 합니다. Microsoft Learn은 Go SDK를 공개 프리뷰로 설명하며, Go에서 선언형 에이전트·RAG·CodeAct·함수형 워크플로가 제공되지 않는다고 안내합니다.
프레임워크는 테스트와 권한 설계를 대신하지 않습니다. 조직의 실제 문서로 시작하기 전에 비식별 자료와 읽기 전용 계정으로 실패·재시작·승인 거부·중복 실행을 각각 확인해야 합니다.
작은 업무로 어떻게 시작할까요?
처음부터 여러 에이전트가 협력하는 긴 흐름을 만들기보다 결과와 외부 효과가 분명한 한 가지 업무를 고르는 편이 좋습니다. 다음 순서로 범위를 줄일 수 있습니다.
- 입력 자료와 최종 결과를 한 문장으로 정합니다.
- 모델 판단, 일반 함수, 사람 승인으로 단계를 나눕니다.
- 외부 쓰기 직전에 실행을 멈추고 승인 결과를 저장합니다.
- 체크포인트에서 재개했을 때 같은 외부 요청이 반복되지 않는지 시험합니다.
이 과정을 통과한 뒤에야 모델 교체, 병렬화와 멀티에이전트 구성을 비교하는 것이 의미가 있습니다. 공공기관 문서나 기업 반복 업무에 적용할 대상, 실습 범위와 산출물을 함께 검토하려면 생성형 AI 실무교육 과정을 확인할 수 있습니다.