Injecting Initial State into ADK Web UI with ASGI Middleware

Context

Google ADK Web UI로 에이전트를 개발할 때마다 새 세션을 생성할 때마다 상태를 수동으로 설정해야 하는 불편함이 있었다. 기존에는 UI의 3점 메뉴를 통해 값을 입력하거나 before_agent_callback에 첫 실행 체크 로직을 작성해야 했다.

Technical Solution

• preset.yaml 파일에 initial_state를 YAML 형식으로 정의하고, .adk/preset.yaml과 preset.yaml 두 위치를 우선순위로 검색하는 파일 로딩 시스템 구현
• POST /apps/{app_name}/users/{user_id}/sessions 요청을 정규표현식으로 감지하는 PresetMiddleware ASGI 미들웨어 개발
• 요청 본문을 비동기로 읽고 JSON 파싱 후 preset의 initial_state를 기본값으로, 요청의 state를 오버라이딩 값으로 병합하는 상태 머징 로직 구현
• Content-Length 헤더를 새로운 본문 크기로 재계산하고 receive 함수를 래핑하여 미들웨어를 통과시키는 방식으로 투명한 요청 수정 처리
• adk web의 모든 CLI 옵션과 호환되는 --preset/--no-preset 플래그 추가

Key Takeaway

ASGI 미들웨어를 활용하면 에이전트 코드 수정 없이 HTTP 요청 처리 계층에서 상태 초기화를 자동화할 수 있으며, 이는 개발 편의성과 코드 유지보수성을 동시에 향상시키는 설계 패턴이다.