코드 오케스트레이션에서 선언적 워크플로우로
마이크로소프트가 2026년 7월 23일 Agent Framework의 선언적 워크플로우(Declarative Workflows)를 1.0으로 발표했습니다. 파이썬 패키지 agent-framework-declarative가 1.0.0에 도달했고 .NET 쪽도 이미 안정 버전으로 합류했습니다. 지금까지 코드 안에서 배선하던 멀티에이전트 오케스트레이션을, 이제는 조율·상태 변화·분기·사람 개입 시점을 YAML로 선언하면 프레임워크가 실행 가능한 워크플로우 그래프로 변환합니다.
선언적 워크플로우의 핵심은 '어떻게 구현할지'가 아니라 '무엇을 할지'를 기술한다는 점입니다. 승인 단계를 추가하거나 핸드오프 조건을 바꾸는 작업이 코드 수정 대신 YAML diff가 되면서, 제품 담당자나 아키텍트도 프레임워크 코드를 읽지 않고 오케스트레이션 동작을 검토할 수 있게 됐습니다.
액션 종류가 곧 오케스트레이션 문법입니다
선언적 워크플로우는 변수 관리(SetVariable, AppendValue, ResetVariable), 제어 흐름(ConditionGroup, Foreach, If/Then/Else, EndWorkflow), 에이전트·도구 호출(함수 도구·MCP·HTTP), 사람 개입(승인 대기 후 재개), 체크포인트·재개, 대화 제어(SendActivity)까지 폭넓은 액션 종류를 지원합니다.
동시에 YAML로 전부를 밀어붙이지는 않습니다. 선언적 정의는 표준 Workflow 인스턴스로 로드되므로 필요한 구간만 저수준 API로 조합할 수 있습니다. 설정으로 조율을 기술하고 코드는 필요한 지점에만 남긴다는 방향은 특정 벤더에 종속되지 않는 운영 원칙입니다.
구축 로드맵과 함정: 선언적 워크플로우 전환 체크리스트
전환 전에 목표 지표부터 숫자로 고정해야 합니다. YAML diff 리뷰 리드타임 4시간 이내, 배포 전 회귀 시나리오 재생 20건 통과율 100%, 조건 분기 커버리지 90% 이상, 사람 승인 대기 SLA 15분(초과 시 자동 에스컬레이션)을 출발 기준으로 삼을 만합니다.
실패 패턴은 네 가지로 좁혀집니다. 첫째, Foreach 종료 조건이 논리적으로 참이 될 수 없어 무한 순회가 발생하는 경우입니다. YAML 문법 검사는 통과하지만 의미상 루프가 닫히지 않습니다.
둘째, 체크포인트 스키마가 바뀐 뒤 옛 체크포인트로 재개를 시도해 변수 상태가 어긋나는 경우입니다. 셋째, 승인자가 응답하지 않아도 타임아웃이 없어 워크플로우가 무기한 대기하는 경우입니다.
넷째, MCP·HTTP 도구 호출이 실패했을 때 이를 잡아내는 분기가 없어 전체 실행이 그대로 죽는 경우입니다. 복구는 반복 액션에 최대 횟수·타임아웃을 명시하고, 체크포인트에 버전 필드를 넣어 스키마 불일치 시 재개를 거부·재시작하고, 승인 대기는 타임아웃 시 기본 경로로 안전 축약하거나 자동 에스컬레이션하며, 도구 호출은 지수 백오프 재시도 후 실패하면 예외 브랜치로 라우팅하는 식으로 액션 종류별로 걸어야 합니다.
배포 전에는 워크플로우 버전을 선택해 플레이그라운드에서 대화를 재생하며 기대 응답과 실제 응답을 대조하는 절차를 표준화합니다. 로그에는 단계 ID, 액션 종류, 변수 스냅샷, 체크포인트 버전, 승인자, 소요 시간을 필수 필드로 남기고, 개인정보가 섞일 수 있는 변수 스냅샷 필드는 저장 전에 마스킹합니다.
매주 실패 로그를 액션 종류별로 집계해 어떤 유형(분기·도구호출·승인대기)에서 실패가 몰리는지 확인하고, YAML 변경 이력은 애플리케이션 코드 변경 이력과 분리해 관리해야 오케스트레이션 문제와 로직 버그를 구분해 추적할 수 있습니다.
바로 쓰는 체크리스트
멀티에이전트 오케스트레이션이 YAML로 내려오면 리뷰 주체와 복구 설계도 함께 바뀝니다. diff 리드타임 4시간, 시나리오 재생 통과율 100%, 분기 커버리지 90%, 승인 SLA 15분을 출발 기준으로 잡고, 반복·체크포인트·승인·도구호출 네 지점에 타임아웃과 백오프를 선언한 뒤 액션 종류별 실패 로그로 매주 어디가 무너지는지 추적하면, 프레임워크가 바뀌어도 같은 운영 기준을 재사용할 수 있습니다.