🎯 에이전트 상태와 프롬프트

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 전달

에이전트 프롬프트 설계

일반 vs 에이전트 · 시스템 프롬프트 구조 · description · 추론 유도

PART 4 · 에이전트 프롬프트 설계

에이전트 프롬프트 설계

시스템 프롬프트 구조부터 추론 모드 유도까지 — 답변이 아니라 행동을 설계하는 관점

좋은 답변이 아니라 올바른 행동

에이전트 프롬프트는 도구 선택과 실행을 지배합니다 — 4블록 구조와 description 품질, 추론 모드 유도가 행동 품질을 결정합니다.

시스템 프롬프트 4블록 — 역할 · 규칙 · 형식 · 제한
description 품질 — 도구 선택 정확도를 결정
추론 유도 — ReAct vs Plan-and-Execute
개선 루프 — 테스트 → 제약 추가 → 자동 평가

takeaway

잘못된 프롬프트의 대가는 부정확한 텍스트가 아니라 잘못된 도구 호출이라는 부작용입니다.

PART 4 · 에이전트 프롬프트 설계

일반 프롬프트 vs 에이전트 프롬프트

"좋은 답변"이 아니라 "올바른 행동"을 유도

일반 프롬프트 에이전트 프롬프트

목표 좋은 텍스트 생성 올바른 도구 선택 + 실행

실패 모드 부정확한 답변 (텍스트) 잘못된 도구 호출 (부작용)

핵심 요소 지시 / 맥락 / 예시 역할 + 도구 설명 + 행동 규칙

평가 기준 답변 품질 (BLEU, 사람 평가) 도구 선택 정확도 + 작업 완료율

도구 정의와 스키마 작성의 기본은 「AI 에이전트 기초」 모듈의 도구 설계 파트에서 다룹니다. 이 파트는 시스템 프롬프트 구조와 추론 유도 관점에서 심화합니다.

PART 4 · 에이전트 프롬프트 설계

시스템 프롬프트 4블록 구조

에이전트가 올바르게 행동하도록 하는 설계 구조

python

# 시스템 프롬프트 4블록 — 역할·규칙·형식·제한
"""
## ① 역할 (Role)
당신은 AWS 비용 분석 전문가입니다.
도구를 사용하여 정확한 데이터 기반으로 답변합니다.

## ② 행동 규칙 (Rules)
- 비용 데이터 필요 → get_cost_data 먼저 호출
- 추측 금지 — 항상 도구 결과 기반
- 한 번에 도구 3개 이상 연속 호출 금지

## ③ 출력 형식 (Format)
- 금액: USD, 소수점 2자리
- 증감률: 퍼센트
- 요약 먼저, 상세 나중에

## ④ 제한 (Constraints)
- 비용 최적화 "실행"은 금지 (분석과 제안만)
- 다른 계정 접근 금지
"""

역할 — 정체성 + 행동 방침. "도구로 데이터 기반 답변"까지 역할에 포함
행동 규칙 — 도구 사용 순서·추측 금지·호출 횟수 제한. 오동작 시 가장 먼저 손볼 블록
출력 형식 — 단위·자릿수·서술 순서를 고정해 응답 일관성 확보
제한 — 권한의 경계. 못 하게 할 일(실행 금지·계정 접근 금지)을 명시

PART 4 · 에이전트 프롬프트 설계

description이 정확도를 결정

LLM이 도구를 고르는 유일한 근거 — description

한 줄 설명

모호한 서술 — 유사 도구와 혼동

조건·형식·예시를 담은 설명

호출 시점 + 파라미터 형식 + 반환 예시

과도한 설명

핵심 밖의 세부가 노이즈로 작용

takeaway

description은 길이가 아니라 판단 정보의 밀도가 관건입니다 — 호출 시점·입력·출력이 드러나는지를 기준으로 다듬습니다.

PART 4 · 에이전트 프롬프트 설계

좋은 description 공식

"언제" + "뭘 넣고" + "뭘 받나" + "주의사항"

필수 요소

언제: "비용 금액/증감/추이 질문 시 호출"
입력: service — AWS 서비스명 (ec2, s3)
입력: period — 조회 기간 (last-7d)
출력: 일별 비용 데이터 (JSON)
주의: 서비스명 불명확하면 확인 후 호출

나쁜 예

"데이터를 가져옵니다"
"비용 관련 작업"
"query" (파라미터만)

PART 4 · 에이전트 프롬프트 설계

추론 모드 유도

시스템 프롬프트로 에이전트의 사고 방식을 결정

ReAct 유도

기본 — 단계별 적응

"단계별로 답하세요"
"도구를 하나씩 호출하고 결과를 확인"
간단한 질의, 도구 1~2개에 적합
Strands 기본 동작

{'text': '매 스텝 적응이 필요한 대화형 에이전트에 적합합니다. 사용자 의도가 바뀔 수 있을 때.', 'code': 'system_prompt = """\n사용자 질문에 단계별로 답하세요.\n각 단계에서 필요한 도구를 하나씩 호출하고,\n결과를 확인한 뒤 다음 단계를 결정하세요.\n"""', 'codeLang': 'python'}

Plan-and-Execute 유도

복합 작업용

"먼저 계획을 세우세요"
"계획을 보여주고 승인 후 실행"
복합 작업, 도구 3+개 조합에 적합
프롬프트로 유도 (명시적 지시)

{'text': '복잡한 멀티스텝 작업에서 사용자가 계획을 미리 확인하고 싶을 때. HITL과 자연스럽게 결합.', 'code': 'system_prompt = """\n사용자 질문을 받으면:\n1. 필요한 단계를 계획하세요 (도구 호출 순서)\n2. 계획을 사용자에게 보여주세요\n3. 승인 후 순서대로 실행하세요\n"""', 'codeLang': 'python'}

PART 4 · 에이전트 프롬프트 설계

프롬프트 개선 루프

1회성이 아닌 지속적 반복 개선

1
초기 작성
역할 + 규칙 + 형식 + 제한으로 초안 작성
2
테스트
5~10건 실행 → 실패 패턴 수집 (도구 선택 오류, 범위 초과)
3
제약 추가
실패 패턴에 대한 명시적 규칙 추가 → 재테스트
4
자동 평가
strands-agents-evals로 점수 기반 비교 → A/B 테스트

takeaway

실패 패턴을 모아 명시적 규칙으로 되먹이는 반복입니다 — 감이 아니라 strands-agents-evals 점수로 개선을 검증합니다.