🚀 기술 브리핑: 이 튜토리얼은 Gate of AI의 에이전트 워크플로우(Agentic Workflows) 심층 분석 시리즈 중 일부입니다. 전체 기술 분석, 인터랙티브 코드 샌드박스 및 네이티브 아랍어 번역은 원문 기사 바로가기에서 확인하세요.
튜토리얼 · 아키텍처 가이드
인간 승인과 함께 LlamaIndex 워크플로우 설계하기
이 가이드는 LlamaIndex 문서 워크플로우에서 상태(state), 승인(approval), 복구(recovery)에 대해 추론하는 방법을 설명합니다. 이는 워크플로우의 진행 중 실행(in-process execution)과 영속적인 애플리케이션 기록(durable application records)을 구분하고, 제공된 지속성 평가에서 중요한 한계점을 강조합니다. 테스트 환경에서 LlamaIndex 직렬화된 Context가 새로운 프로세스에서 재개되지 않았습니다. 이 결과는 모든 LlamaIndex 배포에 대한 보편적 진술이 아니라, 테스트된 구성에 대한 발견 사항으로 간주해야 합니다.
이 가이드에서 다루는 내용
LlamaIndex는 종종 검색 증강 생성(retrieval-augmented generation)과 연관되지만, 검증된 컨텍스트는 더 광범위한 방향을 설명합니다: 에이전트 문서 워크플로우(Agent Document Workflows), 또는 ADW. 보고된 설명에 따르면, 워크플로우는 문서를 더 큰 비즈니스 프로세스의 일부로 처리하고, 단계 전반에 걸쳐 상태를 유지하며, 비즈니스 규칙을 적용하고, 구성 요소를 조정하며, 문서 내용에 기반하여 작업을 수행할 수 있습니다. 계약 검토가 한 예입니다: 프로세스는 정보를 추출하고, 이를 규제 요구 사항과 비교하며, 잠재적 위험을 식별하고, 권장 사항을 준비할 수 있습니다.
이 가이드는 이러한 종류의 다단계 작업에서 파생되는 아키텍처 질문에 초점을 맞춥니다. 프로세스가 상태를 유지한다는 것은 무엇을 의미할까요? 애플리케이션은 워크플로우 런타임과 독립적으로 어떤 정보를 보관해야 할까요? 인간이 중요한 결과를 검토하거나 승인해야 하는 곳은 어디일까요? 그리고 서비스 재시작 후 프로세스가 복구될 수 있다고 주장하기 위해 필요한 증거는 무엇일까요?
이는 실행 가능한 LlamaIndex 또는 SQLite 구현을 제공하지 않습니다. 제공된 검증된 소스는 이를 구축하는 데 필요한 정확한 API, 의존성 버전 또는 코드를 확립하지 못했습니다. 검증되지 않은 코드를 테스트된 튜토리얼로 제시하는 것은 지원에 대한 잘못된 인상을 줄 것입니다. 대신, 아래 단계들은 사용 중인 특정 버전에 대한 문서를 기반으로 워크플로우를 구현할 때 적용할 수 있는 실용적인 설계 및 검증 방법을 제공합니다.
1단계: 작업을 문서 중심의 프로세스로 모델링하기
모델 호출부터 시작하지 말고, 비즈니스 작업부터 시작하십시오. 처리되는 문서 또는 사례, 추출되어야 하는 정보, 참조해야 하는 자료, 허용되는 결정 사항, 그리고 검토자나 다운스트림 시스템이 필요로 하는 결과물을 작성합니다. 계약서 검토 시나리오의 경우, 프로세스는 관련 조항을 추출하고, 이를 적용 가능한 요구사항과 비교하며, 잠재적 우려 사항을 식별하고, 분석가를 위한 권장안을 준비하는 것을 포함할 수 있습니다.
이러한 틀 잡기는 검증된 컨텍스트 내의 ADW 설명을 반영합니다. 문서는 단순히 모델에 제공되는 프롬프트가 아닙니다. 이는 컨텍스트와 결정이 단계 전반에 걸쳐 진화하는 더 광범위한 프로세스의 일부입니다. 워크플로우는 어떤 자료가 검토되었는지, 어떤 규칙이 적용되었는지, 그리고 다음으로 어떤 결과가 검토되어야 하는지를 보존해야 할 필요가 있을 수 있습니다. 하지만 소스가 특정 구성 레이아웃, API 계약 또는 저장 메커니즘을 확립한다고 가정해서는 안 됩니다. 그러한 세부 사항은 선택하는 구현의 문서를 통해 확인되어야 합니다.
프로세스를 명명된 단계로 분리합니다. 유용한 개념적 개요는 정보 수집(intake), 추출(extraction), 참고 자료 검토(reference review), 의사 결정 준비(decision preparation), 인간 검토(human review), 그리고 완료(completion)입니다. 각 단계는 명시적인 입력과 예상 결과를 가져야 합니다. 예를 들어, “참고 자료 검토”는 참조된 참고 자료와 그것이 답변하려는 질문을 식별해야 합니다. “의사 결정 준비”는 모델이 생성한 진술을 승인된 조치로 암묵적으로 처리하기보다는, 검토 가능한 권장 사항을 만들어야 합니다.
마지막으로, 정보가 누락되거나 모호할 때 무슨 일이 발생하는지 정의합니다. 워크플로우는 빠진 계약 조건을 지어내거나 불확실성을 긍정적인 발견으로 취급하는 대신, 명확화나 검토를 위해 중단될 수 있어야 합니다. 이것은 애플리케이션의 설계 요구 사항이며, 특정 LlamaIndex 워크플로우가 이를 자동으로 강제한다는 주장은 아닙니다.
단계 2: 워크플로우 컨텍스트와 영구 비즈니스 기록 분리하기
지속성(persistence)을 설명할 때는 정확한 언어를 사용해야 합니다. 워크플로우는 실행되는 동안 단계 간에 컨텍스트를 전달할 수 있습니다. 애플리케이션은 케이스 기록, 문서 식별자, 검토 상태, 승인 결정 또는 최종 권장 사항을 별도로 저장할 수 있습니다. 이들은 서로 다른 것입니다. 비즈니스 기록을 저장하는 것이, 중단된 워크플로우가 멈춘 정확한 단계에서 복원될 수 있음을 스스로 증명하지는 않습니다.
이 구분이 중요한 이유는 “재개 가능한(resumable) 워크플로우”라는 제목이 여러 가지 다른 보장을 의미할 수 있기 때문입니다. 이는 사용자가 케이스를 다시 열고 마지막으로 저장된 결과를 검사할 수 있다는 것을 의미할 수도 있습니다. 애플리케이션이 시작부터 미완성 작업을 재실행할 수 있음을 의미할 수도 있습니다. 또는 런타임(runtime)이 특정 단계에서 계속하는 데 필요한 상태를 포함하여, 진행 중인 전체 실행을 복원할 수 있음을 의미할 수도 있습니다. 이러한 보장들은 서로 교환 가능하지 않습니다. 시스템이 실제로 어떤 것을 지원하는지 명시하십시오.
제공된 영속성(persistence) 연구는 여러 에이전트 프레임워크와 그들의 영속성 메커니즘을 비교합니다. 요약에 따르면 LlamaIndex는 평가에서 직렬화된 Context를 사용했으며, 이 테스트된 구성으로는 새로운 프로세스에서 재개되지 않았습니다. 이는 모든 LlamaIndex 워크플로우가 복구할 수 없다고 주장하는 근거가 아니라, 필요한 정확한 복구 동작을 테스트해야 할 이유일 뿐입니다. 마찬가지로, 애플리케이션 데이터를 SQLite에 저장한다고 해서 런타임 복구가 자동으로 가능함을 의미하는 증거도 아닙니다.
애플리케이션 레벨의 기록을 설계할 때는 사람이 이해하고 검토해야 하는 것이 무엇인지 고려해야 합니다: 케이스 식별자(case identifier), 현재 비즈니스 상태, 관련 입력 또는 이에 대한 안전한 참조, 현재 결과, 그리고 결정 이력입니다. 저장소 설계를 선택하기 전에는 반드시 환경의 운영 및 보안 요구 사항을 확인해야 합니다. 제공된 자료들은 SQLite 스키마, 트랜잭션 전략, 또는 적절한 데이터 보존 정책을 명시하지 않으므로, 이러한 선택들은 독립적으로 설계하고 테스트해야 합니다.
3단계: 승인을 비즈니스 결정으로 만들기
인간의 승인은 모호한 최종 체크박스로 추가되는 것이 아니라, 정의된 결정에 연결될 때 가장 유용합니다. 어떤 결과가 검토를 필요로 하는지, 누가 검토할 권한이 있는지, 검토자가 어떤 정보를 보는지, 그리고 승인 전에 시스템이 무엇을 할 수 있도록 허용되어야 하는지를 파악해야 합니다. 예를 들어, 계약 추천은 최종 법적 결정으로 취급되기보다는 분석가를 위한 제안으로 제시될 수 있습니다.
추천과 권한 부여(authorization)의 구분을 인터페이스와 저장된 비즈니스 기록에서 명확히 유지해야 합니다. 모델은 요약을 준비하거나 잠재적인 문제를 식별할 수 있지만, 지정된 검토자가 조직의 프로세스에 따라 승인 결정을 내립니다. 조직의 개인 정보 보호 및 보존 요구 사항을 준수하여 나중에 결정을 설명할 수 있을 만큼 충분한 정보를 기록해야 합니다. 이는 애플리케이션 설계 권장사항이며, 검증된 내장 LlamaIndex 승인 기능은 아닙니다.
검토 단계를 구현하기 전에 가능한 결과를 정의해야 합니다. 검토자는 제안된 다음 단계를 승인하거나, 거부하거나, 추가 정보를 요청할 수 있습니다. 각 결과가 프로세스의 나머지 부분에 모호하지 않도록 만드세요. 단순히 권장 사항이 생성되거나 승인되었다는 이유만으로 외부 작업이 발생했음을 암시하는 언어는 피해야 합니다. 다운스트림(downstream) 작업이 제품의 일부라면, 그것이 어떻게 승인되고, 실행되며, 보고되는지 별도로 검증해야 합니다.
승인 정책은 조직이 설명할 수 있는 비즈니스 규칙을 기반으로 해야 합니다. 검증된 ADW 리포트는 더 광범위한 문서 프로세스의 일부로 비즈니스 규칙을 적용하는 것을 구체적으로 언급합니다. 하지만 정책 엔진을 제공하거나 특정 승인 임계값을 규정하지는 않습니다. 따라서, 임의의 예시 규칙을 보편적인 지침으로 제시하기보다는 관련 도메인 소유자들과 함께 임계값과 검토자의 책임을 정의해야 합니다.
4단계: 복구(recovery)를 정직하게 설계하고 테스트하기
서비스를 재개 가능하다고 설명하기 전에, 복구 사양을 작성해야 합니다. 프로세스 종료 시 어떤 정보가 살아남는지, 어떤 작업이 계속될 수 있는지, 어떤 작업이 반복되어야 하는지, 그리고 서비스가 부분적인 결과와 완료된 결과를 혼동하는 것을 어떻게 방지하는지 명시하세요. 그런 다음 관련 지점에서 서비스를 중단하고 새로운 프로세스로 다시 시작하여 이러한 주장을 테스트해야 합니다.
최소한 세 가지 복구 결과를 구별해야 합니다. 첫째, 애플리케이션이 마지막으로 저장된 비즈니스 상태를 표시할 수 있어야 합니다. 둘째, 더 이른 안전 경계(safe boundary)부터 처리를 다시 시작할 수 있어야 합니다. 셋째, 워크플로우 런타임의 진행 중인 상태(in-progress state)를 복원하고 중단된 단계부터 계속할 수 있어야 합니다. 시스템은 다른 결과를 제공하지 않으면서 하나의 결과만 제공할 수도 있습니다. 테스트한 결과를 문서화하고, 모든 경우에 '체크포인트(checkpoint)'라는 단어를 동의어로 사용해서는 안 됩니다.
어떤 결과도 저장되기 전, 중간 결과가 기록된 후, 그리고 검토자가 결정을 내린 후에 중단되는 경우를 포함해야 합니다. 재시작 시 미완성 작업을 자동으로 완료로 표시하거나, 검토 결정을 폐기하거나, 명시적인 정책 없이 중요한 작업을 반복하지 않는지 확인하십시오. 정확한 테스트 하네스(test harness)와 영속성 API(persistence API)는 LlamaIndex 버전과 애플리케이션 아키텍처에 따라 달라지므로, 제공된 자료에는 구체적으로 명시되어 있지 않습니다.
영속성 평가는 유용한 배경 지식이지만, 자체적인 검증을 대체할 수는 없습니다. 이 요약은 여러 프레임워크를 가로지르는 연구를 설명하며 테스트된 LlamaIndex 구성에 대한 특정 신선한 프로세스 결과를 제공합니다. 귀하의 시스템은 다른 설계를 사용할 수 있지만, 재현 가능한 테스트를 통해 그 동작을 입증하고 해당 증거의 경계를 설명할 수 있어야 합니다.
5단계: 문서 처리를 책임 있는 단계들의 순서로 다루기
검증된 컨텍스트에서의 ADW 예시는 문서를 더 광범위한 비즈니스 프로세스의 일부로 설명합니다. 계약 검토의 예시에서, 프로세스는 문서에서 정보를 추출하고, 규제 요구사항과 교차 참조하며, 위험을 식별하고, 권장 사항을 준비할 수 있습니다. 이는 단계를 설계하는 데 유용한 모델이지만, 특정 워크플로우가 정확한 법적 또는 규제 판단을 내릴 것이라는 보장은 아닙니다.
각 단계에 대해 어떤 정보를 받는지, 그리고 무엇을 생성할 것으로 예상되는지 명시하십시오. 주장은 제공된 문서와 참조 자료에 근거해야 합니다. 출력이 권장 사항이라면, 그렇게 표시하십시오. 필요한 소스를 참고하지 않았다면, 프로세스가 포괄적인 비교를 완료했다고 암시해서는 안 됩니다. 검토자는 결론뿐만 아니라 프로세스가 실제로 무엇을 검토했는지도 알아야 합니다.
비즈니스 규칙이 적용되는 곳에서는 프로세스 설계에 이를 명시하고 독립적으로 테스트해야 합니다. 소스는 ADW가 비즈니스 규칙을 적용하고 구성 요소를 조정할 수 있다고 설명하지만, 구체적인 규칙을 열거하거나 특정 강제 메커니즘을 확립하지는 않습니다. 모델이 생성한 답변 자체가 규칙 검사라고 추론해서는 안 됩니다. 규칙을 정의하고, 애플리케이션이 이를 어떻게 검증하는지 결정하며, 그 결과를 인간 검토자에게 의미 있는 방식으로 기록해야 합니다.
첫 구현은 범위를 좁게 유지하세요. 문서 유형 하나와 명확하게 정의된 검토 결과(review outcome) 하나를 선택합니다. 워크플로우가 후속 단계에서 필요한 컨텍스트를 보존할 수 있고, 검토자가 결과를 이해할 수 있는지 확인하는 것이 중요합니다. 동작 방식과 복구 경계(recovery boundary)가 명확해진 후에만 더 많은 문서 유형이나 결정으로 확장하세요.
6단계: 신뢰성이 있다고 설명하기 전에 시스템 평가 수행
평가는 생성된 콘텐츠와 그 주변의 라이프사이클 모두를 다루어야 합니다. 콘텐츠에 대해서는 대표적인 예시들을 모아서 자격을 갖춘 검토자들이 추출된 정보와 권장 사항이 의도된 작업에 유용한지 평가하도록 해야 합니다. 라이프사이클 동작 방식에 대해서는 애플리케이션이 불완전한 작업을 정확하게 표현하고, 검토 결정을 의도한 대로 보존하며, 중단 후에도 예측 가능하게 작동하는지 테스트해야 합니다.