ADK - Sessions & Memory : State

✅ ADK의 session.state: 세션의 스크래치북 (Scratchpad)

🔹 정의

• session.state는 에이전트가 현재 대화 중 필요로 하는 임시 데이터를 저장하는 key-value 딕셔너리입니다.
• 예: 사용자 선호, 현재 단계, 플래그, 리스트 등

---

🧩 주요 특성

항목                                  설명

구조	문자열 key + 직렬화 가능한 값 (str, int, bool, list 등)
가변성	대화 중 동적으로 변경 가능
영속성	SessionService 구현체에 따라 달라짐
단순함 유지	복잡한 객체는 저장 금지 (식별자만 저장)

 

---

🔠 Key Prefix의 의미와 범위

Prefix범위(Scope)예시특징

없음	현재 세션 내부	current_step	대화 흐름 관리용
user:	특정 사용자 전체 세션	user:language	사용자 프로필, 취향 저장
app:	앱 전체 (모든 사용자 공유)	app:api_endpoint	글로벌 설정, 템플릿 공유
temp:	현재 실행 중만 유효	temp:raw_result	휘발성 데이터, 저장 안 됨

 

☝️ ADK는 하나의 session.state 딕셔너리로 다뤄지지만, prefix를 통해 저장소와 범위를 구분합니다.

---

🔁 상태(State) 업데이트 권장 방식

방식                                                              용도                        설명

✅ output_key 사용	단순 응답 저장	Agent 응답을 자동으로 state에 저장
✅ EventActions.state_delta 사용	여러 key 동시 업데이트	명시적으로 변경 사항 지정 후 append_event
✅ CallbackContext.state, ToolContext.state 사용	콜백/툴 내부	컨텍스트 내에서 안전하게 상태 변경 가능
❌ 직접 수정	X	session.state[...] = ... 방식은 비추천 (저장/감사 불가, race condition 위험)

 

---

🔹 output_key 방식 예시

---

🔹 EventActions.state_delta 방식 예시

---

🔹 Callback 또는 Tool 내부에서 상태 변경

🔐 자동으로 Event로 래핑되며 thread-safe하게 저장됨

---

⚠️ 직접 수정이 위험한 이유

문제점                                            설명

저장 안 됨	append_event() 없이 수정하면 DB 저장되지 않음
이벤트 이력 없음	변경 내용이 이벤트에 남지 않음 (감사 불가)
동시성 문제	다른 쓰레드와 충돌 가능성
시간 추적 불가	last_update_time 갱신 안 됨

 

---

🧠 상태 설계 Best Practices 요약

항목                                                                     권장 방식

최소한의 정보만 저장	필요한 정보만, 중복 피하기
단순 자료형 사용	str, int, bool, list(dict) 등
명확한 키 이름	booking_step, user:name 등
얕은 구조 유지	복잡한 중첩 피하기
표준 흐름 따르기	반드시 append_event()를 통해 저장

 

---

🧾 결론 요약

질문요약

session.state란?	현재 세션에서 필요한 임시 정보를 저장하는 key-value 저장소
언제 사용되나?	사용자 입력 추적, 멀티턴 프로세스 진행, 응답 생성에 참고 등
어떻게 업데이트해야 하나?	output_key, EventActions.state_delta, 혹은 context 객체를 통해
무엇을 피해야 하나?	직접 수정 (session.state["key"] = value)