고통 (The Pain): 에이전트를 튜닝하느라 오후 내내 시간을 보냈습니다. 그런데 다음 날 아침, 에이전트는 마치 어제 일이 전혀 없었던 것처럼 당신을 멍하니 바라봅니다.
배울 내용: 4단계 진화 과정 (Prompt → Context → Harness → Loop)과 메모리를 유지하는 실행 가능한 50줄의 루프 에이전트 (Loop Agent).

0. 사전 요구 사항 (Prerequisites)

• Python ≥ 3.10
• pip install openai (openai ≥ 1.0.0)
• OpenAI API Key
• OS: macOS / Linux / Windows WSL

목표: 코드를 복사하여 붙여넣고 실행하여, 잊어버리지 않는 루프 에이전트 (Loop Agent)를 확인합니다.

1. 고통: 왜 당신의 에이전트는 하룻밤 사이에 모든 것을 잊어버리는가?

새벽 2시, 당신은 마침내 그 다단계 워크플로우 (multi-step workflow)를 작동시켰습니다. 에이전트는 데이터 가져오기, 정제, 분석, 차트 생성 등 당신이 정성껏 설계한 프롬프트 (prompt)를 따랐습니다. 당신은 만족하며 노트북을 닫습니다.

다음 날 아침, 희망에 찬 마음으로 대화를 다시 열었지만 — 에이전트는 마치 그 모든 일이 전혀 없었던 것처럼 당신을 멍하니 바라봅니다.

로그를 확인합니다. 에러는 없습니다. 예외 (exception)도 없습니다. 에이전트는 모든 것을 다시 생성했습니다. 단지 어제 어디서 멈췄는지를 "잊어버렸을" 뿐입니다.

이것은 농담이 아닙니다. 모든 진지한 에이전트 (Agent) 개발자가 경험하는 악몽입니다. 근본적인 원인은 "모델이 충분히 똑똑하지 않아서"가 아닙니다. 더 근본적인 사실은 다음과 같습니다: 당신의 에이전트는 밤을 지새우도록 설계되지 않았다는 것입니다.

2. 4단계 진화: Prompt → Context → Harness → Loop

이를 이해하기 위해 간단한 진화 프레임워크를 사용해 보겠습니다:

루프 엔지니어링 (Loop Engineering)은 프롬프트 엔지니어링 (Prompt Engineering)을 거부하는 것이 아니라 — 그것을 초월하는 것입니다. 프롬프트는 여전히 중요합니다. 하지만 그것은 엔진일 뿐이며, 당신은 엔진을 자동차처럼 운전할 수는 없습니다.

3. 최소 실행 가능 루프 에이전트 (Loop Agent) (50줄)

여기 바로 복사하여 붙여넣고 실행할 수 있는 완전한 루프 에이전트 (Loop Agent)가 있습니다. 먼저 실행해 본 다음, 한 줄씩 이해해 보세요.

import json, os, time
from pathlib import Path
from datetime import datetime
...

이 코드를 loop_agent.py에 복사하고 실행하세요.

4. 검증 (Verification)

# 1. 설치
pip install openai

...

예상 출력 (Expected output):

OK on attempt 1:
The 3 mainstream Python web frameworks:
1. **Flask**: lightweight micro-framework...
...

이제 지속성 (persistence)을 검증하세요 — 터미널을 닫고, 다시 연 다음, 다시 실행하세요:

# 4. 상태 파일 확인
cat agent_state.json

예상 결과:

{
  "state": "done",
  "step": 1,
...

# 5. 메모리 파일 확인
cat agent_memory.json

예상 결과: facts 딕셔너리에 당신의 작업과 출력 결과가 포함되어 있어야 합니다.

# 6. 다시 실행 — 에이전트가 메모리를 자동으로 로드함
python loop_agent.py

에이전트는 agent_memory.json에서 facts를 읽어와 이를 기인지된 컨텍스트 (known context)로 전달합니다. 이것이 바로 "하룻밤 사이에 기억하는" 메커니즘입니다.

5. 코드에 매핑된 6가지 구성 요소

6. 일반적인 오류 (Common Errors)

오류 1: ModuleNotFoundError: No module named 'openai'

pip install openai

오류 2: openai.AuthenticationError: 401
API 키를 설정하지 않았거나 유효하지 않습니다.

export OPENAI_API_KEY="sk-..."

오류 3: 에이전트 출력에 Flask/Django/FastAPI가 누락됨
이는 정상입니다! LLM (대규모 언어 모델)이 항상 지시사항을 완벽하게 따르는 것은 아닙니다. 바로 그 점이 루프 에이전트 (Loop Agent)의 가치입니다 — 검사기 (Checker)가 누락된 키워드를 감지하고, 출력을 거부하며, 자동으로 재시도합니다. 다음과 같은 메시지를 보게 될 것입니다:

Retry 1 failed: Missing: ['Flask', 'Django', 'FastAPI']
Retry 2 failed: Missing: ['Django']
OK on attempt 3:
...

오류 4: API 타임아웃 또는 속도 제한 (rate limit)
gpt-4o-mini는 매우 저렴합니다 (~$0.00015/call). 속도 제한에 걸린다면 time.sleep(1)을 늘리거나 OpenAI 대시보드를 확인하세요.

7. 50줄 코드 이후의 다음 단계

이제 실행 가능한 완전한 루프 에이전트 (Loop Agent)를 갖게 되었습니다. 이 에이전트는 지속화를 위해 일반 JSON 파일을 사용하며, 이는 당신이 모든 구성 요소를 직접 손으로 만져볼 수 있게 해주는 핵심 요소입니다.

확장해 보세요:

• ChromaDB를 JSON으로 교체 → 벡터 메모리 (vector memory)
• Celery를 연결 → 실제 비동기 작업 큐 (async task queue)
• Feishu/Slack 웹훅 추가 → 완료 알림 (completion notifications)
• 구조화된 로그 + Trace ID 추가 → 관측성 (observability)

루프 엔지니어링 (Loop Engineering)은 설치하는 패키지가 아닙니다. 그것은 아키텍처 사고방식의 전환입니다. 이 50줄의 코드로부터, 당신은 4단계의 문턱에 서 있습니다.

다음 글: 당신의 에이전트에는 얼마나 많은 메모리가 필요한가? — 메모리 저장소 선택 가이드

저자 소개: Wu Ji (无记) — 에이전트 엔지니어링 (Agent engineering), 루프 엔지니어링 (Loop Engineering), 그리고 디지털 전환 (digital transformation)에 집중하는 AI 및 디지털화 실무자. 실용적이고 직접 따라 할 수 있는 튜토리얼 — 따라 하기만 하면 바로 작동합니다.