지정한 개념 **‘에이전트 상태 관리’**에 대한 위키 노트를 성공적으로 작성하여 llm-wiki/wiki/에이전트 상태 관리.md 파일에 반영했습니다.
[생성된 위키 노트 내용]
---
type: concept
status: draft
core: false
tags:
- llm
- agent
- state-management
aliases:
- Agent State
- 에이전트 상태
sources:
- 'raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md'
created: 2026-08-27
updated: 2026-08-27
---
# 에이전트 상태 관리
## 한 줄 정의
에이전트 상태 관리는 [[AI 에이전트 제어 루프|AI 에이전트]]가 의사결정을 내릴 때 인지할 수 있는 온메모리 단기 정보([[컨텍스트 윈도우]])와 외부 영속 저장소(파일, 데이터베이스, [[지속성 장기 메모리|장기 메모리]]) 간의 정보 유입·유출 및 격리 체계를 설계하고 다루는 핵심 기법입니다.
## 핵심 요지
- **두 가지 상태의 층위**: 에이전트 엔지니어링에서 상태(State)는 크게 '워크플로의 진행 단계(추적 정보)'와 '현재 시점에 에이전트가 인지하고 있는 정보(컨텍스트 상태)'로 구분됩니다.
- **컨텍스트 윈도우=시야 한계**: 컨텍스트 윈도우 내부로 유입되지 않은 외부 정보(디스크 파일, DB 레코드, 외부 API, Git 이력 등)는 에이전트 관점에서 존재하지 않는 것과 같습니다.
- **매체별 저장소 선택**:
- **파일 시스템**: 개발자 워크플로의 기본 저장 매체로, 사람이 읽기 쉽고 Git 이력 추적 및 [[Git Worktree 기반 작업 영역 격리|Git diff]] 대조가 용이합니다.
- **장기 메모리**: 세션을 넘어 보존되어야 하지만 Git 커밋 이력까지 필요 없는 사용자 선호도나 프로젝트 기본 지침 저장에 적합합니다.
- **데이터베이스**: 엄격한 구조화 스키마, 복수의 유저/에이전트 동시 접근, 동시성 제어가 요구될 때 활용됩니다.
- **격리 및 동시성 방어**: 다중 에이전트 환경에서 동시 파일 수정 시 [[Race Condition|레이스 컨디션(Race Condition)]]으로 데이터 오염이 발생하므로 [[Git Worktree 기반 작업 영역 격리|Git worktrees]]나 샌드박스 기반 작업 공간 격리가 필수적입니다.
- **[[서브에이전트 패턴|서브에이전트]]를 활용한 컨텍스트 정제**: 서브에이전트는 완전히 깨끗한 새 컨텍스트 윈도우에서 시작하여 노이즈를 차단하고 높은 신호 대 잡음비(Signal-to-Noise Ratio)를 유지합니다.
## 상세
### 1. 컨텍스트 윈도우(In-Context State) 대 외부 저장소(External State)
에이전트의 단기 작업 기억(working memory) 역할을 하는 [[컨텍스트 윈도우]]에는 최신 사용자 메시지, 시스템 프롬프트, 이전 도구 호출 이력 및 실행 결과가 실시간으로 쌓입니다. 그러나 토큰 제한(Token limit)과 정보 누적으로 인한 [[컨텍스트 부패|컨텍스트 부패(Context Rot)]] 및 [[LLM 아키텍처 Lost in the Middle 현상|Lost in the Middle]] 현상이 발생할 수 있습니다.
반면 컨텍스트 윈도우 바깥에 존재하는 데이터는 명시적으로 가져오기(Retrieval/Read) 전까지 에이전트의 사고 과정에 포함되지 않습니다 (raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md). 따라서 훌륭한 에이전트 설계는 **"어떤 정보는 시야(컨텍스트) 바깥에 남겨두고, 어떤 정보만 적시에 시야 안으로 집어넣을 것인가"**를 결정하는 정보 제어 설계입니다.
### 2. 저장 매체별 적재 전략
1. **파일 기반 관리 (File-based)**: `.md` 파일이나 `.json` 파일은 개발자 친화적이며 버전 관리가 쉽습니다. 에이전트의 현재 작업 계획이나 아키텍처 의사결정 기록(ADR)을 파일로 명시하면 세션 간 공유가 용이합니다.
2. **지속성 장기 메모리 (Persistent Memory)**: `MEMORY.md` 또는 임베딩 기반 벡터 DB를 활용하여 세션이 종료된 후에도 유지되어야 하는 사용자 스타일, 도구 실행 룰을 관리합니다.
3. **데이터베이스 (RDBMS / NoSQL)**: 복수의 작업 주체(인간 또는 agent)가 동시에 상태를 업데이트하고 관계형 쿼리나 트랜잭션 제어가 필요한 경우 선택합니다.
### 3. 다중 에이전트 동시성 및 작업 공간 격리
여러 에이전트가 동일한 소스 파일이나 공유 자원에 동시 쓰기를 시도하면 덮어쓰기 버그나 충돌이 일어납니다.
이를 해결하기 위해 [[Git Worktree 기반 작업 영역 격리|Git worktrees]]를 통해 각 에이전트에게 물리적으로 독립된 소스 코드 작업 사본을 제공하고, 작업을 마친 후 병합(Merge) 절차를 거치는 아키텍처를 도입합니다.
또한 상위 부모 에이전트가 [[서브에이전트 패턴|서브에이전트]]를 호출할 때는 부모의 비대한 과거 대화 로그를 통째로 넘기지 않고, 소작업 처리에 필요한 최소한의 요약 팩트만 전달해야 합니다. 과도한 컨텍스트 전달은 업무 분할이 제대로 이루어지지 않았다는 경고 시그널입니다 (raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md).
## 예시
### Python 기반 에이전트 상태 구조체 및 격리 처리 시나리오
아래 코드는 에이전트의 온메모리 컨텍스트 상태와 디스크 기반 파일 상태, 그리고 [[서브에이전트 패턴|서브에이전트]]로 상태를 전달할 때의 정보 정제 과정을 보여주는 구현 예시입니다.
```python
import os
import json
from dataclasses import dataclass, field
from typing import List, Dict, Any
@dataclass
class AgentInContextState:
"""컨텍스트 윈도우 내부 활성 상태 (Short-term Working Memory)"""
system_instruction: str
active_tools: List[str]
chat_history: List[Dict[str, str]] = field(default_factory=list)
def add_observation(self, tool_name: str, result: str):
self.chat_history.append({"role": "tool", "name": tool_name, "content": result})
class ExternalFileManager:
"""컨텍스트 바깥 영속 파일 상태 관리 (External State)"""
def __init__(self, workspace_path: str):
self.workspace_path = workspace_path
def save_agent_memory(self, filename: str, content: str):
path = os.path.join(self.workspace_path, filename)
with open(path, "w", encoding="utf-8") as f:
f.write(content)
def load_relevant_fact(self, filename: str) -> str:
path = os.path.join(self.workspace_path, filename)
if os.path.exists(path):
with open(path, "r", encoding="utf-8") as f:
return f.read()
return ""
# 시나리오: 부모 에이전트가 서브에이전트에 정제된 상태만 위임
def delegate_to_subagent(parent_state: AgentInContextState, subagent_task: str) -> str:
# 비대한 chat_history를 모두 넘기지 않고 필요한 핵심 지침만 전달하여 서브에이전트 컨텍스트 최소화
subagent_in_context_state = AgentInContextState(
system_instruction=f"당신은 보안 검토 전문 서브에이전트입니다. 목표: {subagent_task}",
active_tools=["read_file", "grep_search"]
)
# 서브에이전트는 깨끗한 Fresh Context에서 작업 수행
print(f"[Subagent Launched] Instructions length: {len(subagent_in_context_state.system_instruction)}")
return "보안 취약점 0건 검출 (최종 결과만 반환)"대표 모델 및 도구 활용 현황
- Claude Code: 로컬 디렉토리의
CLAUDE.md및MEMORY.md를 통해 세션 간 지속 상태를 파일로 관리하며,Git worktrees를 병용하여 다중 병렬 서브에이전트 작업 간의 상호 간섭을 차단합니다 (raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md). - LangGraph: 상태 그래프(State Graph) 객체를 정의하여 개별 노드(Node) 간 주고받는 상태 딕셔너리의 스키마를 엄격히 지정함으로써 순환 루프에서의 상태 유실을 방지합니다.
충돌
- 단일 비대 컨텍스트 vs 모듈형 최소 컨텍스트: 일부 초거대 컨텍스트 윈도우 지원 모델(예: Gemini 1.5 Pro의 200만 토큰)이 등장함에 따라 “모든 사내 문서와 전체 Git 로그를 컨텍스트에 쏟아 넣는 것이 상태 관리를 단순화한다”는 주장이 제기되기도 합니다. 그러나 실제 실험과 아키텍처 실무에서는 컨텍스트가 부풀어 오를수록 파라미터 주의력(Attention)이 분산되어 중요한 규칙을 놓치는 컨텍스트 부패와 정보 탐색 정밀도 저하가 밝혀짐에 따라, 외부 저장소와 연동한 모듈형 최소 컨텍스트 제어가 더 우수한 실무 표준으로 인정받고 있습니다 (raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md).