🤗 07. HF Agents Course 본편 5 - 계획·메모리·관찰가능성으로 에이전트 운영하기

이번 편에서는 **“한 번 답하는 에이전트”**가 아니라, 재시도·기록·검증이 가능한 운영형 에이전트로 확장하는 최소 패턴을 다룹니다.

flowchart TD
    A[사용자 목표 입력] --> B[Plan 생성]
    B --> C[Tool 실행]
    C --> D[중간 결과/로그 저장]
    D --> E{성공 기준 충족?}
    E -- 예 --> F[최종 응답 + 근거]
    E -- 아니오 --> G[수정된 Plan으로 재시도]
    G --> C

왜 중요한가 (실무 포인트)

• 초반 PoC는 잘 되는데 운영에서 깨지는 이유는 대부분 로그 부재, 성공 기준 불명확, 상태 미보존입니다.
• smolagents에서도 Plan/Memory/Trace를 명시적으로 남기면 장애 분석 속도가 크게 올라갑니다.

실습: 운영형 mini runner 만들기

1) 도구 설치

• Python 3.10+
• 가상환경 생성:

python -m venv .venv
source .venv/bin/activate
pip install -U smolagents duckduckgo-search

2) 입력 파일 준비

task_input.txt

2026년 AI 에이전트 운영 체크리스트 핵심 5가지를 조사해서, 근거 URL과 함께 요약해줘.

3) 실행 코드 작성

ops_agent.py

from pathlib import Path
from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel
 
MODEL_ID = "Qwen/Qwen2.5-Coder-32B-Instruct"
 
model = InferenceClientModel(model_id=MODEL_ID)
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
    max_steps=6,
)
 
user_goal = Path("task_input.txt").read_text(encoding="utf-8").strip()
 
system_like_instruction = """
반드시 다음 형식으로 작업:
1) PLAN: 3단계 이하 계획
2) EXECUTION: 실제 검색/추론
3) EVIDENCE: URL 최소 3개
4) FINAL: 한국어 불릿 5개
""".strip()
 
prompt = f"{system_like_instruction}\n\n사용자 목표: {user_goal}"
result = agent.run(prompt)
 
Path("run_result.md").write_text(str(result), encoding="utf-8")
print("DONE: run_result.md 생성")

4) 실행 명령

python ops_agent.py

5) 성공 판정

아래를 모두 만족하면 성공:

• run_result.md 파일 생성
• PLAN/EXECUTION/EVIDENCE/FINAL 4개 섹션 확인
• EVIDENCE에 URL 3개 이상
• FINAL에 불릿 5개

초보자를 위한 해설

• max_steps=6은 무한 루프 방지 안전장치입니다.
• “형식 강제 프롬프트”를 넣어야 결과물 품질이 흔들리지 않습니다.
• 결과를 파일로 남겨야 다음 자동화(스케줄러, 알림, 검수)에 연결됩니다.

운영 체크리스트

• 실패 시 재시도 정책(예: 1회 자동 재시도)
• 근거 링크 누락 시 실패 처리
• 실행 시간/토큰 비용 로깅
• 출력 스키마(JSON/Markdown) 고정

다음 편 예고

본편 6에서는 에이전트 출력 검증기(guardrail) + 배치 실행으로 확장합니다.

---

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성한 뒤, 사람이 구조·정확성·재현 절차를 검토/보정했습니다.