UI에서 워커(Worker)까지 액션 엔벨로프(Action Envelope)를 통한 에이전틱 AI (Agentic AI) 구축하기
요약
에이전틱 AI 구축 시 UI, API, 워커 간의 신뢰할 수 있는 계약을 형성하기 위한 '액션 엔벨로프(Action Envelope)' 설계 방식을 제안합니다. 상태 변경 대신 새로운 액션을 추가하는 불변성 원칙과 계층 간 데이터 무결성 유지의 중요성을 강조합니다.
핵심 포인트
- 액션 엔벨로프를 통한 UI-API-워커 간 명시적 계약 수립
- 데이터 무결성을 위해 기존 행을 수정하지 않고 새로운 액션 삽입
- 계획 버전(planVersion)과 해시 검증을 통한 실행 안정성 확보
- 중복 전달 및 실패 시나리오에 대한 테스트 설계 필요성
에이전트 기능은 단 한 번의 모델 호출로 이루어지지 않습니다. 그것은 UI, API, 권한 부여 (authorization), 스토리지 (storage), 워커 실행 (worker execution), 그리고 인간의 검토 (human review)를 가로지르는 하나의 계약 (contract)입니다.
저는 그 계약을 명시적으로 만들 것입니다:
type ActionEnvelope = {
taskId: string;
planVersion: number;
...
브라우저는 특정 planVersion을 승인합니다. API는 해당 승인을 저장합니다. 워커는 계획이 변경되었거나, 액션이 이미 실행되었거나, 인자 (arguments)의 해시 (hash)가 검토자가 본 것과 다를 경우 엔벨로프 (envelope)를 거부합니다.
수정 (correction)은 실패한 액션과 그 증거를 참조하는 새로운 액션입니다. 기존 행 (row)을 조용히 변경 (mutate)해서는 안 됩니다:
(task_id, plan_version, action_id, replaces_action_id, status)
values ($1, $2, $3, $4, 'pending');
연결 부위 (seams)를 테스트하세요:
| 시나리오 (Scenario) | 예상 결과 (Expected result) |
|---|---|
| 중복된 워커 전달 (duplicate worker delivery) | 동일한 액션 결과 (same action result) |
| ... |
OpenAI Agents SDK run lifecycle는 도구 호출 (tool calls) 및 핸드오프 (handoffs)를 포함하는 루프를 문서화합니다. 어떤 SDK를 사용하든, 애플리케이션은 여전히 내구성이 있는 계층 간 계약 (cross-layer contract)을 소유합니다.
이 수직적 슬라이스 (vertical slice)는 현재 무료로 시작 가능한 브라우저 플랫폼 (browser platform)을 포함하여 MonkeyCode를 위한 적절한 일회성 작업입니다. 위의 스키마 (schema)는 독립적인 예시이며, MonkeyCode의 내부 구조에 대한 주장이 아닙니다. 나중에 저장소 (repository)를 내보내어 동일한 수락 테스트 (acceptance tests)를 다른 곳에서도 실행할 수 있도록 하세요.
저는 MonkeyCode 사용자이며, 해당 프로젝트와 관련이 없습니다. 이 계정은 이 배치의 나머지 계정들과 동일한 운영자에 의해 관리됩니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기