Microsoft Agent Framework 가이드: HITL 요청과 checkpoint 재개

InYourLeague 리서치 · 2026-08-30

Answer in brief

Microsoft Agent Framework는 형식이 지정된 요청·응답 메커니즘을 통해 외부 입력을 기다린 뒤 실행을 계속하는 사람 참여형 상호 작용을 지원합니다. 여러 run 호출 사이의 상태 보존은 공식 Python 예시에서만 확인되며, 제공된 근거에는 영속 체크포인트 직렬화, 프로세스 간 복원 또는 .NET과 Go에 공통으로 적용되는 후속 실행 재개 보장이 없습니다.

Key facts at a glance

Failure modes and verification

FAQ

Microsoft Agent Framework 워크플로가 사람의 입력을 기다리는 조건은 무엇인가요?

문서화된 요청 메커니즘으로 보낸 요청에 아직 응답이 없으면 워크플로가 기다립니다. .NET과 Go는 RequestPort를 사용하고, Python은 ctx.request_info()를 사용합니다. 자세한 내용은 사람 참여형 워크플로 공식 문서에 있습니다.

외부 응답은 어떻게 올바른 실행기에 전달되나요?

프레임워크가 응답을 원래 요청과 연결해 해당 실행기로 자동 전달합니다. Python은 request_id를 노출하며, 공식 .NET 예시는 RequestInfoEvent에 포함된 요청 객체로 응답을 생성합니다.

Python의 보류 요청을 후속 run 호출에서 처리할 수 있나요?

네. 공식 Python 예시는 여러 run 호출 사이에 상태가 보존된다고 명시하고, 보류 중인 request_id에 대응하는 응답을 후속 호출에 전달하는 흐름을 보여 줍니다. 이 설명은 사람 참여형 워크플로 공식 문서의 Python 예시에 한정됩니다.

프로세스를 재시작한 뒤 영속 체크포인트에서 복원할 수 있나요?

제공된 근거만으로는 확인할 수 없습니다. 두 자료는 체크포인트 직렬화, 영속 저장소, 불러오기 API 또는 프로세스 간 복구를 설명하지 않습니다. Python의 여러 실행 호출 사이 상태 보존을 영속 체크포인트 복원으로 표현해서는 안 됩니다.

공식 예시에서는 에이전트를 어떻게 오케스트레이션하나요?

Agents in Workflows 가이드는 WorkflowBuilder와 직접 연결선을 사용해 전문 에이전트를 순차적으로 연결합니다. 문서의 .NET 예시에서는 메시지를 받은 뒤 TurnToken이 처리를 시작하게 합니다.

.NET 에이전트의 응답 갱신은 어떻게 스트리밍되나요?

공식 .NET 에이전트 예시는 StreamingRun을 사용하며, AgentResponseUpdateEvent로 점진적인 응답을 제공합니다. 다만 제공된 근거는 이 이벤트와 사람 참여형 요청 이벤트가 하나의 스트림에 함께 나타난다고 입증하지 않습니다.

Microsoft Agent Framework가 공개한 선택 가능한 모델 ID는 무엇인가요?

제공된 두 공식 자료는 제품 수준에서 선택할 수 있는 고정 모델 ID를 제시하지 않습니다. 에이전트 예시는 Azure Foundry 환경에 구성된 모델 또는 배포 값을 사용합니다.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-30

Extended guide

직접 답변

Microsoft의 사람 참여형 워크플로 공식 문서에 따르면 실행기(executor)는 사람이나 외부 시스템에 요청을 보내고, 응답을 받을 때까지 기다린 다음 처리를 계속할 수 있습니다. .NET과 Go에서는 RequestPort가 요청 형식과 응답 형식을 지정하는 통신 경계입니다. Python에서는 실행기가 ctx.request_info()를 호출하고, @response_handler로 등록한 메서드가 반환된 응답을 처리합니다.

이 메커니즘은 사람의 승인, 추가 정보 수집 또는 다른 비동기 작업에 사용할 수 있습니다. 공식 자료에서 확인되는 기본 동작은 요청을 내보내고, 외부 응답을 기다리고, 연결된 응답을 원래 실행기로 전달한 뒤 처리를 계속하는 것입니다. 영속 체크포인트를 이용한 장애 복구는 별도의 문제이며, 제공된 근거만으로는 지원 여부를 확정할 수 없습니다.

문서화된 요청·응답 계약

사람의 승인 처리 절차

1. 먼저 승인 계약을 정의합니다. 공식 Go 예시는 요청 형식이 string이고 응답 형식이 bool인 RequestPort를 사용합니다. 요청에는 검토할 내용을 담고, Boolean 응답에는 승인 또는 거절 결정을 담을 수 있습니다.
2. 승인 결과를 소비할 실행기에 포트를 연결합니다. 해당 예시의 FinalizeExecutor는 Boolean 값을 받아 사람이 승인했다는 결과 또는 거절했다는 결과를 생성합니다.
3. 실행을 시작하고 이벤트를 관찰합니다. .NET 예시에서는 InProcessExecution.RunStreamingAsync(...)가 StreamingRun을 반환하며, 실행 호스트는 WatchStreamAsync()로 이벤트를 읽습니다.
4. RequestInfoEvent가 도착하면 외부에서 답을 수집하고 검증합니다. 사용자 화면, 승인 서비스 또는 다른 연동 시스템은 워크플로 밖에서 요청을 확인하고 필요한 값을 준비할 수 있습니다.
5. .NET에서는 handle.SendResponseAsync(requestInputEvt.Request.CreateResponse(value))로 응답합니다. 이 방식은 이벤트에 포함된 요청 객체가 나타내는 연결 관계를 유지합니다. 제공된 근거는 .NET 호스트가 별도의 요청 식별자를 추출해 저장해야 한다고 설명하지 않습니다.
6. 응답을 보낸 뒤에도 스트림을 계속 읽습니다. 최종 출력이 생성될 수도 있고, 워크플로가 또 다른 외부 요청을 내보낼 수도 있으므로 첫 번째 응답 직후 이벤트 소비를 끝내면 안 됩니다.

Python은 목적은 비슷하지만 언어별 API가 다른 방식을 사용합니다. 실행 호스트는 request_info 이벤트에서 request_id와 요청 데이터를 수집하고, 각 식별자에 대응하는 응답을 구성합니다. 실행기의 @response_handler는 원래 요청과 응답 매개변수에 표시된 형식 주석을 기준으로 선택됩니다. 따라서 Python 구현에서는 나중에 응답해야 하는 보류 요청의 request_id를 보관하는 것이 문서화된 흐름과 맞습니다.

보류 요청, 체크포인트, 복원의 범위

공식 Python 예시는 여러 run 호출이 서로 격리되지 않으며 호출 사이에 워크플로 상태가 보존된다고 명시합니다. 따라서 같은 Python 워크플로 인스턴스에서 보류 요청 식별자를 수집하고, 후속 run 호출로 응답을 전달해 처리를 계속하는 방식은 근거가 있는 설명입니다.

하지만 이 동작을 모든 언어의 SDK에 공통인 복원 기능으로 확대해서는 안 됩니다. 제공된 .NET 예시는 하나의 StreamingRun 안에서 요청 이벤트를 받고 곧바로 응답합니다. Go 발췌문은 외부 응답을 기다렸다가 재개하는 동작을 보여 주지만, 실행을 종료한 뒤 다른 실행에서 복원하는 절차는 보여 주지 않습니다.

또한 두 자료에는 영속 체크포인트 객체, 저장소 제공자, 직렬화 형식, 체크포인트 불러오기 API, 프로세스 재시작 절차 또는 프로세스 간 복구 보장이 제시되어 있지 않습니다. 그러므로 Python의 여러 run 호출 사이에서 이루어지는 상태 보존을 디스크 기반 체크포인트 복원과 같은 기능으로 설명하면 근거 범위를 넘습니다. 서비스 재시작이나 장애 이후의 복구가 필수라면, 실제로 사용하는 언어와 SDK 버전에 대한 별도의 공식 계약이 필요합니다.

에이전트 오케스트레이션과 스트리밍

별도의 Agents in Workflows 가이드는 전문 에이전트를 WorkflowBuilder와 직접 연결선으로 순차 연결하는 방식을 보여 줍니다. 문서의 .NET 예시에서 에이전트는 전달받은 메시지를 임시로 보관하고, TurnToken을 받은 뒤 처리를 시작합니다. 스트리밍 실행 중에는 AgentResponseUpdateEvent를 통해 각 실행기의 점진적인 에이전트 응답을 관찰할 수 있습니다.

다만 제공된 자료는 사람 참여형 요청 이벤트와 에이전트 응답 갱신 이벤트를 서로 다른 예시에서 설명합니다. 두 종류의 이벤트가 하나의 실행 스트림에 함께 나타난다는 사실은 입증하지 않습니다. 따라서 두 기능을 조합한 워크플로를 설명하려면 실제 조합 동작을 뒷받침하는 추가 공식 근거가 필요합니다.

구현 점검 목록

• 요청과 응답의 정확한 형식을 선언합니다.
• 외부 값을 워크플로에 반환하기 전에 형식과 허용 범위를 검증합니다.
• Python에서는 후속 응답에 필요한 각 보류 요청의 request_id를 보관합니다.
• .NET에서는 문서에 나온 대로 이벤트의 요청 객체를 이용해 응답을 생성합니다.
• 응답을 보낸 뒤에도 최종 출력이나 다음 요청을 받을 수 있도록 이벤트를 계속 소비합니다.
• Python의 여러 실행 호출 사이 상태 보존과 영속 체크포인트 복원을 명확히 구분합니다.
• 공식 .NET 에이전트 예시를 따를 때는 필요한 TurnToken을 전송합니다.
• 워크플로 출력, 요청 이벤트, 에이전트 응답 갱신을 각각 해당 API의 의미에 맞게 처리합니다.

제공된 두 공식 자료는 Microsoft Agent Framework 제품 수준에서 선택할 수 있는 고정 모델 ID를 제시하지 않습니다. 에이전트 예시는 제품 고유 모델 ID가 아니라 Azure Foundry 환경에 구성된 모델 또는 배포 값을 입력받습니다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.