Unreal Agent로 비동기식의 내구성 있는 AI 에이전트 워크플로 구축

Unreal Agent란?

Unreal Agent는 Unreal Labs에서 제공하는 비동기 우선 에이전트 하네스입니다. 입력 수락, 세션 기록 유지, 모델 컨텍스트 준비, LLM 턴 조정, 도구 호출 변환, 지속 가능한 비동기 작업 디스패치를 위한 조합 가능한 인프라를 제공합니다.

이 프로젝트는 동기식 조정과 비동기식 실행을 분리합니다. 도구 변환기는 모델이 생성한 요청을 검증하고 I/O를 수행하지 않은 채 직렬화 가능한 작업 설명을 생성합니다. 이후 작업 관리자가 조정자의 이벤트 루프 외부에서 커밋된 작업을 실행합니다.

저장소 구조

저장소는 세 가지 주요 영역으로 구성됩니다.

• harness/: 재사용 가능한 에이전트 하네스 라이브러리입니다.
• cmd/: 라이브러리로 빌드되는 실행 파일입니다.
• benchmarks/: 프로젝트 평가를 위한 벤치마크 실행기입니다.

프레임워크를 다른 애플리케이션에 통합할 때는 harness/부터 살펴보세요. 구체적인 실행 파일 진입점은 cmd/에서 확인하고, 런타임 동작을 검사하거나 측정해야 할 때는 benchmarks/를 사용하세요.

핵심 개념

입력과 인박스

입력은 호출자가 제공하는 전역적으로 고유한 식별자를 포함한 이벤트입니다. 이벤트가 다시 전달되더라도 해당 식별자는 변경되지 않아야 합니다.

세션 인박스는 외부 입력, 제어 입력, 크래시 입력을 메모리에서 중복 제거할 때 이러한 식별자를 사용합니다. 이 멱등성은 세션 범위에 한정되고 휘발성이므로 호출자는 여전히 일관되게 안정적인 ID를 제공해야 합니다.

{
  "id": "globally-unique-and-stable-id",
  "type": "external-input",
  "payload": "Example request"
}

이 형태는 문서화된 Unreal Agent API 타입이 아니라 개념적인 예시입니다. 중요한 요구 사항은 안정적이고 전역적으로 고유한 입력 ID입니다.

세션

세션은 추가만 가능한 영속 기록입니다. 세션을 재개하고 분기할 수 있으므로 애플리케이션은 기존 작업을 계속하거나 원래 순서를 수정하지 않고 이전 기록에서 분기할 수 있습니다.

세션 저장소는 정식 기록과 작업 상태를 관리합니다. 또한 도구 호출의 변환 상태와 해당 변환에서 생성된 작업을 원자적으로 기록합니다.

LLM 턴

LLM 턴은 하나의 논리적 모델 요청을 둘러싸는 조정자 관리 시퀀스입니다. 조정자는 승인된 입력을 영속화하고, 턴을 준비하며, 도구 변환기를 확인하고, 결과 작업을 기록하고, 커밋된 작업을 디스패치합니다.

도구, 변환기, 작업

도구는 스키마와 변환기를 결합한 것입니다. 모델이 도구 호출을 생성하면 변환기는 이를 검증하고 하나 이상의 작업으로 변환합니다.

도구 변환기는 조정자의 이벤트 루프에서 동기적으로 실행됩니다. I/O를 수행하거나 루프를 일시 중지해서는 안 됩니다.

변환 결과를 도구 호출 상태라고 합니다. 여기에는 검증 오류 또는 제출된 작업에 대한 참조가 포함됩니다. 이 상태는 해당 작업의 실행 상태와는 별개입니다.

작업은 비동기 작업을 설명하는 직렬화 가능하고 버전이 지정된 설명입니다. 변환기는 작업을 설명하고, 작업 관리자는 이를 실행합니다.

주요 구성 요소

• 세션 인박스: 휘발성 세션 범위 입력 멱등성을 제공합니다.
• 조정자: 승인된 입력을 영속화하고, LLM 턴을 관리하며, 도구 변환기를 확인하고, 커밋된 작업을 디스패치합니다.
• 세션 저장소: 정식 세션 기록과 작업 상태를 영속화하고, 복구와 분기를 지원하며, 도구 호출 상태와 작업을 원자적으로 기록합니다.
• 컨텍스트 빌더: 메모리에서 모델 입력을 구성하고 생략되거나 잘리거나 압축된 콘텐츠를 보고합니다. I/O를 수행하지 않으며 영속성 의존성도 없습니다.
• LLM 어댑터: 준비된 입력을 모델 제공자에게 전송하고 정규화된 완료 응답을 반환합니다. 인증, 취소, 제공자 오류를 담당합니다.
• 도구 레지스트리: Bash, ViewImage, skill-use 도구의 정의와 변환기를 관리하면서 호스트가 선택한 도구 집합을 노출합니다.
• 도구 변환기: 호출을 검증하고, 상태와 작업을 생성하며, 기록된 상태와 준비된 작업 출력을 모델에 맞는 형식으로 변환합니다.
• 작업 관리자: 지속 가능한 작업을 위한 액터 런타임을 제공합니다. 로컬 구현은 교체할 수 있습니다.

설치 및 설정

README에는 패키지 관리자, 언어별 설치 명령 또는 안정적인 공개 API가 명시되어 있지 않습니다. 따라서 설정은 특정 패키지 명령을 가정하기보다 저장소의 로컬 체크아웃과 빌드 메타데이터를 바탕으로 시작해야 합니다.

1. Unreal Agent 저장소를 복제하거나 다운로드합니다.
2. 저장소 루트를 열고 지원되는 도구 체인을 확인하기 위해 빌드 및 의존성 파일을 살펴봅니다.
3. 저장소에 구성된 도구를 사용하여 harness/의 라이브러리를 빌드하거나 설치합니다.
4. 하네스 구성 요소를 조합하는 실행 파일 예시는 cmd/에서 확인합니다.
5. 핵심 프로젝트가 성공적으로 빌드된 후에만 benchmarks/를 사용합니다.

cd <unreal-agent-repository>

# 라이브러리, 실행 파일, 벤치마크 디렉터리를 확인합니다.
ls harness
ls cmd
ls benchmarks

호스트 애플리케이션에는 선택한 제공자에 맞게 구성된 LLM 어댑터도 필요합니다. 인증, 취소 동작, 제공자별 오류 처리는 해당 어댑터에 속합니다.

기본 사용법: 하나의 에이전트 요청 따라가기

README에는 구체적인 생성자나 메서드 이름이 공개되어 있지 않으므로, 사용법을 이해하는 가장 안전한 방법은 문서화된 구성 요소 흐름을 따라가는 것입니다.

1. 세션을 생성하거나 재개합니다. 세션 저장소는 영구 기록과 복구를 지원합니다.
2. 안정적인 ID로 입력을 제출합니다. 동일한 논리적 이벤트를 다시 전달할 때는 같은 ID를 재사용합니다.
3. 세션 인박스를 통해 중복을 제거합니다. 인박스는 구현 동작에 따라 활성 세션 내에서 반복 입력을 거부하거나 무시합니다.
4. 승인된 입력을 영구 저장합니다. 코디네이터는 입력을 정식 추가 전용 세션 기록에 기록합니다.
5. 모델 컨텍스트를 구성합니다. 컨텍스트 빌더는 메모리상의 모델 입력을 구성하고, 생략하거나 잘라 내거나 압축한 콘텐츠를 보고합니다.
6. LLM 턴을 실행합니다. LLM 어댑터는 준비된 입력을 제공자에게 보내고 정규화된 완료 응답을 반환합니다.
7. 도구 호출을 확인합니다. 코디네이터는 레지스트리를 통해 허용된 각 도구를 조회합니다.
8. 동기적으로 변환합니다. 선택된 변환기는 호출을 검증하고 검증 오류 또는 직렬화 가능한 작업을 생성합니다.
9. 원자적으로 커밋합니다. 세션 저장소는 도구 호출 상태와 작업을 함께 기록합니다.
10. 비동기적으로 디스패치합니다. 작업 관리자는 커밋된 작업을 실행하고 변환 상태와 별도로 실행 상태를 추적합니다.
11. 모델용 결과를 형식화합니다. 변환기는 기록된 호출 상태와 준비된 작업 출력을 결합해 모델에 전달할 결과를 생성합니다.

도구 호출 수명 주기 예시

안정적인 ID가 있는 입력
  -> 인박스 중복 제거
  -> 영구 저장된 세션 이벤트
  -> 컨텍스트 구성
  -> 정규화된 LLM 응답
  -> 도구 레지스트리 조회
  -> 동기 검증 및 변환
  -> 상태 및 작업의 원자적 커밋
  -> 비동기 작업 실행
  -> 모델용 결과 형식화

검증에 실패하면 변환기는 작업을 생성하는 대신 검증 오류를 기록합니다. 검증에 성공하면 상태는 제출된 작업을 참조하고, 작업 관리자는 해당 작업이 대기 중인지, 실행 중인지, 완료되었는지 또는 구현에 따라 다른 방식으로 처리되었는지를 독립적으로 추적합니다.

도구 선택

도구 레지스트리는 Bash, ViewImage 및 스킬 사용을 위한 정의와 변환기를 관리합니다. 호스트는 이 도구 중 어떤 것을 노출할지 선택합니다.

특정 배포에 필요한 기능만 노출합니다. README는 권한 부여 또는 샌드박싱 정책을 정의하지 않으므로 이러한 문제는 호스트 환경과 작업 실행 계층에서 처리해야 합니다.

하네스 확장

Unreal Agent의 구성 요소는 조합 가능하도록 설계되었습니다. 인터페이스를 기반으로 하는 구성 요소는 문서화된 책임과 불변 조건을 유지하는 한 다른 구현으로 교체할 수 있습니다.

도구 변환기 구현

사용자 지정 변환기는 다음 순서를 따라야 합니다.

1. 도구의 스키마에 따라 모델이 생성한 인수를 검증합니다.
2. 요청이 유효하지 않으면 검증 오류를 반환합니다.
3. 유효한 경우 직렬화 가능하고 버전이 지정된 작업 설명을 하나 이상 생성합니다.
4. 제출된 작업을 참조하는 상태를 반환합니다.
5. 기록된 상태와 준비된 작업 출력을 모델에 전달할 결과로 변환하는 형식화 로직을 제공합니다.

변환은 결정적이고 빠르게 유지합니다. 변환기 내부에서 네트워크 요청을 보내거나, 파일에 접근하거나, 하위 프로세스를 기다리거나, 그 밖의 I/O를 수행하지 마십시오.

작업 관리자 교체

로컬 작업 관리자는 교체할 수 있습니다. 문서화된 확장 방식 중 하나는 작업을 직렬화하여 원격 샌드박스 프로세스 내부에서 실행 중인 다른 로컬 작업 관리자에게 보내는 프록시 관리자입니다.

이 설계는 코디네이터와 변환기가 검증 및 영속적인 의도에 집중하도록 하면서 실행은 격리된 환경에서 수행할 수 있게 합니다.

저장소 구현

대체 세션 저장소는 직렬화 가능성, 버전 관리, 복구 동작, 도구 호출 상태와 생성된 작업 간의 원자적 관계를 유지해야 합니다.

이 프로젝트는 세션의 이전 버전과의 호환성을 유지하는 것을 목표로 합니다. 세션 버전이 지원되지 않는 경우 데이터를 잘못 해석한 채 조용히 진행하지 말고 명시적인 오류와 함께 재개에 실패해야 합니다.

고급 팁

• 호출자 경계에서 입력 ID를 생성하세요. 재시도와 재전달 시에도 동일한 식별자가 유지되도록 ID를 원래 이벤트와 함께 저장하세요.
• 인박스 중복 제거와 영속적인 기록을 혼동하지 마세요. 인박스는 휘발성이며 세션 범위에 한정되지만, 세션 저장소는 정식 이벤트를 영속화합니다.
• 변환기는 순수하고 동기적으로 유지하세요. 작업을 직접 수행하지 말고 요청을 작업으로 변환하세요.
• 모든 작업 형식에 버전을 지정하세요. 작업은 이를 생성한 프로세스보다 오래 존재하거나 프로세스 및 샌드박스 경계를 넘을 수 있습니다.
• 원자적 커밋을 보존하세요. 성공한 도구 호출 상태를 작업과 함께 기록하지 않으면 충돌 후 세션이 일관되지 않은 상태로 남을 수 있습니다.
• 변환과 실행을 독립적으로 추적하세요. 유효한 호출이 아직 완료되지 않은 커밋된 작업을 생성할 수 있습니다.
• 컨텍스트 빌더 메타데이터를 사용하세요. 모델 동작을 진단할 수 있도록 무엇이 생략, 잘림 또는 압축되었는지 모니터링하세요.
• 프로바이더 관련 처리를 중앙화하세요. 자격 증명, 취소 및 프로바이더 오류를 LLM 어댑터 내부에서 처리하세요.
• 실험을 위해 세션을 분기하세요. 분기를 사용하면 원본 세션의 추가 전용 기록을 보존하면서 다른 연속 흐름을 탐색할 수 있습니다.
• 격리를 위해 프록시 작업 관리자를 사용하세요. 직렬화된 작업을 원격 샌드박스 내부의 런타임으로 전달하되 동기 변환까지 그곳으로 이동하지 않을 수 있습니다.

중요한 불변 조건

확장 기능은 다음 보장을 유지해야 합니다.

• 세션 저장소 항목은 직렬화 가능한 상태로 유지됩니다.
• 저장 형식은 계속 버전 관리됩니다.
• 지원되지 않는 세션 버전은 명시적인 재개 오류를 발생시킵니다.
• 작업은 직렬화 가능하고 버전이 지정된 상태로 유지됩니다.
• 컨텍스트 구성은 I/O를 수행하지 않으며 영속성 종속성을 허용하지 않습니다.
• 도구 변환은 I/O를 수행하지 않으며 코디네이터의 이벤트 루프를 중단시키지 않습니다.

결론

Unreal Agent는 영속 세션, 중복 제거된 입력, 조정된 LLM 턴, 검증된 도구 호출 및 영속적인 비동기 작업이 필요한 에이전트를 위한 모듈식 기반을 제공합니다. 핵심 설계 원칙은 동기 변환과 비동기 실행을 명확히 분리하는 것입니다. 기존 실행 파일에서 시작하고 문서화된 이벤트 흐름을 따르며, 구성 요소를 교체하거나 확장할 때 직렬화, 버전 관리 및 원자성을 유지하세요.