📝 에이전트 상태 관리

💬

messages[]와 세션

messages[] 구조 · session_id · 인메모리 한계

PART 1 · messages[]와 세션

messages[]와 세션

대화가 모델에 전달되는 실제 구조와 인메모리 한계의 조감

💬

모델은 기억하지 않는다 — 매번 다시 읽는다

매 호출마다 messages[] 전체가 모델에 재전송됩니다 — session_id로 대화를 격리하고 인메모리 한계를 확인합니다.

• messages[] — user · assistant · toolUse · toolResult 누적
• session_id — 사용자×대화 격리, 멀티유저 서빙의 기본
• 인메모리 한계 — 유실 · 토큰 폭발 · 윈도우 초과 · 혼선
• SessionManager — 외부 저장소 영속화로 유실 해결

takeaway

모델에는 기억이 없고 매 호출 messages[] 전체를 다시 읽습니다 — 이 구조가 상태 관리 전체의 출발점입니다.

PART 1 · messages[]와 세션

messages[]의 실체

모델은 "기억"이 아니라 매번 다시 읽는 것 — 다음 호출에 실제로 나가는 페이로드

Converse API 요청 바디 — "messages": [ ... ]

이전 턴 누적분 — 매 호출마다 전부 다시 전송

{ "role": "user", "content": "제주도 여행 계획 세워줘" }사용자 질문

{ "role": "assistant", "content": "2박3일 추천드릴게요..." }모델 응답

{ "role": "assistant", "content": [{ "toolUse": { "name": "get_weather", "input": { "city": "jeju" } } }] }모델의 도구 호출 요청

{ "role": "user", "content": [{ "toolResult": { "content": "맑음, 28도" } }] }프레임워크가 넣은 실행 결과

{ "role": "user", "content": "그럼 우산 챙겨야 해?" }
NEW · 이번 턴

toolUse·toolResult까지 모두 messages[]에 쌓이고 다음 호출에 전부 다시 전송됩니다 — 대화가 길수록 입력 토큰이 커지는 이유입니다.

PART 1 · messages[]와 세션

session_id 설계

대화를 구분하는 키 — 멀티유저 서빙의 기본

사용자당 1개

user_id

• 대화 1개만 유지
• 단순하지만 대화 분리 불가

언제 — 단순 봇 (1사용자 = 1대화)

대화별 분리

user_id-conv_id

• 여러 대화 독립 유지
• ChatGPT 방식 (좌측 대화 목록)

언제 — 멀티 대화 앱 (대부분의 프로덕션)

시간 기반

user_id-2026-07-19

• 날짜별 자동 분리
• 이전 날짜 대화 자동 아카이브

언제 — 일일 보고, 데일리 어시스턴트

takeaway

대부분의 프로덕션은 user_id-conv_id 대화별 분리를 사용합니다 — 키 설계가 대화 격리 수준을 결정합니다.

PART 1 · messages[]와 세션

인메모리 상태의 4가지 문제

상태 관리 없이는 프로덕션 불가

기억 상실

프로세스 종료 시 messages[] 전체 유실 — 서버 재시작, 배포, Lambda 콜드스타트

토큰 폭발

대화가 길어지면 매 호출마다 수만 토큰 전송 — 비용↑ 지연↑

윈도우 초과

컨텍스트 윈도우를 넘으면 API 에러 — 에이전트 멈춤

멀티유저 혼선

session_id 없이 여러 사용자의 messages[]가 섞임

takeaway

네 문제 모두 상태를 프로세스 메모리에만 두어서 생깁니다 — 다음 파트의 상태 관리 구성요소가 각각의 해법입니다.

🧩

상태 관리 구성요소

Session · Conversation · Memory · Context · Snapshots · Interrupts

PART 2 · 상태 관리 구성요소

상태 관리 구성요소

독립적인 6가지 구성요소와 상태를 수명으로 구분하는 관점의 조감

🧩

6가지 구성요소 · 수명 3계층

Session·Conversation·Memory·Context·Snapshots·Interrupts를 필요한 것만 골라 조합하고, 상태를 수명으로 구분합니다.

• 6가지 구성요소 — 각각 독립, 선택 조합
• 수명 3계층 — 턴 · 세션 · 세션 너머
• agent.state — 세션 유지, 도구 간 공유 메모장
• invocation_state — 1턴 유효, 외부 주입 비밀

takeaway

어떤 상태가 얼마나 오래 살아야 하는지가 먼저입니다 — 수명이 저장소와 구성요소 선택을 결정합니다.

PART 2 · 상태 관리 구성요소

상태 관리 6가지 구성요소

각 구성요소는 독립적 — 필요한 것만 선택하여 조합

SessionManager

messages[]를 외부 저장소에 저장/복원 — 프로세스 재시작 후 대화 이어가기

ConversationManager

모델 전달 전 messages[] 축소 — 슬라이딩 윈도우, 요약 압축

MemoryManager

세션 너머 장기 기억 — 사용자 선호, 이전 세션 요약, 패턴 학습

Context Management

큰 도구 결과 자동 오프로드 — 미리보기만 컨텍스트에 유지

Snapshots

특정 시점 상태 캡처 + 롤백 — 잘못된 경로에서 되돌리기

Interrupts

위험 작업 전 멈춤 + 사용자 승인 후 재개

PART 2 · 상태 관리 구성요소

상태 수명 3계층

턴 · 세션 · 세션 너머 — 각 상태의 유효 범위

범위	유지되는 상태	저장소	예시
1턴	invocation_state	메모리 (매 호출 재주입)	user_id, api_key, request_id
세션	messages[] + agent.state	SessionManager (File/S3)	대화 히스토리, 인증 토큰
세션 너머	MemoryManager	AgentCore Memory / Knowledge Base	사용자 선호, 이전 세션 요약

takeaway

턴이 끝나면 invocation_state가, 세션이 끝나면 messages[]가 사라집니다 — 세션 너머까지 남길 것만 MemoryManager로 올립니다.

PART 2 · 상태 관리 구성요소

agent.state vs invocation_state

둘 다 모델에는 안 보이는 존재 — 수명과 주입 방향의 차이

agent.state

세션 전체 유지

• 도구/훅이 .set() / .get()
• 세션 동안 여러 턴에 걸쳐 유지
• SessionManager가 함께 영속화
• 용도: 인증 토큰, 호출 카운터, 도구 간 공유 데이터

도구가 중간 결과를 저장하고, 다른 턴의 다른 도구가 읽어 쓰는 "에이전트 내부 메모장"입니다.

invocation_state

1턴만 유효

• 호출자(caller)가 외부에서 주입
• agent(prompt, invocation_state={...})
• 저장 안 됨 — 매 호출마다 재주입
• 용도: API 키, user_id, 역할(role), 세션 비밀

호출할 때마다 외부에서 넣어주는 "파라미터 봉투". 도구가 tool_context.invocation_state로 꺼냅니다.

PART 2 · 상태 관리 구성요소

모델이 보는 것 vs 못 보는 것

LLM에 노출되면 안 되는 민감 정보는 invocation_state로

상태	LLM이 봄?	도구/훅 접근?	용도
messages[]	✓ 매번 전체 전송	✓	대화 맥락 유지
agent.state	✗	✓ .get()/.set()	도구 간 내부 데이터
invocation_state	✗	✓ tool_context	외부 주입 비밀/설정

API 키, 토큰 등 민감 정보를 messages[]에 넣으면 모델에 노출됩니다. 반드시 invocation_state를 사용하세요.

🔗

멀티에이전트 상태 공유

Agents-as-Tools · Swarm · Graph · invocation_state 전파

PART 3 · 멀티에이전트 상태 공유

멀티에이전트 상태 공유

에이전트 사이에서 결과가 흐르는 통로와 흐르지 않는 것의 조감

🔗

패턴마다 공유 통로가 다르다

Agents-as-Tools·Swarm·Graph는 결과가 흐르는 방향과 방식이 각각 다르고, agent.state는 어디서도 직접 공유되지 않습니다.

• Agents-as-Tools — toolResult로 부모←자식 단방향
• Swarm — Shared Context가 핸드오프마다 누적
• Graph — Output Propagation, DAG 방향 전파
• 공유 불가 — agent.state · messages[] 직접 접근 없음

takeaway

messages[]와 agent.state는 어떤 패턴에서도 복사되지 않습니다 — 패턴이 제공하는 통로로만 결과가 흐릅니다.

PART 3 · 멀티에이전트 상태 공유

패턴별 상태 공유

에이전트 A의 결과를 에이전트 B가 알아야 할 때

Agents-as-Tools

• 자식 에이전트 결과가 부모의 toolResult로 삽입
• 단방향 — 부모만 자식 결과를 봄
• 가장 단순한 패턴

Swarm

• 핸드오프 시 이전 에이전트의 작업 맥락이 자동 누적
• Shared Context — 핸드오프될 때마다 쌓임
• messages[]는 복사 안 됨 — Context만 전달

Graph

• 이전 노드 출력이 엣지를 따라 연결 노드의 입력으로 전파
• Output Propagation — DAG 의존성 방향으로만 흐름
• 병렬 노드 간에는 공유 안 됨

PART 3 · 멀티에이전트 상태 공유

공유 안 되는 것

에이전트 간 직접 접근이 불가능한 상태

agent.state는 인스턴스 귀속

agent.state는 해당 에이전트에만 접근 가능합니다. 다른 에이전트가 직접 읽을 수 없습니다. 공유하려면 도구 반환값으로 꺼내거나, 외부 저장소(AgentCore Memory, DynamoDB)를 경유해야 합니다.

상태	인스턴스 간 공유	공유 방법
agent.state	✗ 직접 접근 불가	도구 반환값 / 외부 저장소
messages[]	✗ 복사 안 됨	Shared Context(Swarm) / Output(Graph)
invocation_state	△ 전파 가능	오케스트레이터가 자식 호출 시 동일 dict 전달