Agent Loop 내부
기준일: 2026-07-26
난이도: 중급
공식 기준: Agent Loop Internals
개요
AIAgent 실행 루프 — API 모드, 툴 호출, 콜백, 예산, fallback, 압축·영속화 — 를 내부 관점에서 설명합니다. 사용자 가이드가 “무엇을 설정하나”라면, 이 문서는 “한 턴이 코드에서 어떻게 흘러가나”입니다.
핵심 개념
| 개념 | 설명 |
|---|---|
| Entry points | 단순 응답 문자열 vs 풀 메시지 dict |
| API modes | chat completions / native 등 |
| Turn lifecycle | user → model → tools → model … |
| Message alternation | role 교대 규칙 |
| Interruptible API | 사용자 중단 가능 호출 |
| Sequential vs concurrent tools | 도구 병렬 실행 정책 |
| Iteration budget | 최대 툴 루프 횟수 |
| Fallback model | 주 모델 실패 시 전환 |
| ContextCompressor | 긴 세션 요약 압축 |
| Session persistence | SQLite 등 세션 저장 |
상세
Core Responsibilities
- 시스템 프롬프트 조립 결과 수신
- 모델 API 호출·스트리밍
- tool call 파싱·실행·결과 재주입
- 예산/중단/fallback
- 세션 메시지 기록
Two Entry Points
# Simple — 최종 응답 문자열
# Full — messages, tool traces, metadata dict
CLI/게이트웨이/API 서버가 필요에 따라 다른 엔트리포인트를 씁니다.
API Modes
Provider·모델에 따라:
- OpenAI-compatible chat completions + tools
- Anthropic/Codex 등 native 모드
- 보조 모델은 별도 client
Turn Lifecycle
- 사용자 메시지 정규화 (
@참조, 미디어 등) - 메시지 히스토리 + 시스템 프롬프트 구성
- 모델 호출 (interruptible)
- tool_calls 있으면 실행 후 assistant/tool 메시지 append
- budget 소진 또는 final answer까지 반복
- 세션 저장·콜백·메모리 후보 검토
Message Format & Alternation
user/assistant/tool(또는 provider 고유 역할)- 연속 동일 role 금지 등 provider별 규칙 준수
- tool 결과는 다음 모델 호출 전 반드시 반영
Tool Execution
| 모드 | 동작 |
|---|---|
| Sequential | 순서 보장, 부작용 도구에 안전 |
| Concurrent | 독립 읽기 도구 병렬화 |
Execution flow: schema validate → handler → JSON/string normalize → message append
Agent-level tools: 루프 자체가 가로채는 도구 (위임, 일부 세션 제어)
Callback Surfaces
- pre/post LLM
- pre/post tool
- session start/end
- 플러그인 훅과 동일 계열 이벤트
로깅, Langfuse, 보안 가이던스 플러그인이 이 지점에 붙습니다.
Budget and Fallback
- Iteration budget: 무한 tool loop 방지
- Fallback model: 429/5xx/타임아웃 시 보조 모델
- credential pool과 함께 쓰면 가용성 향상
Compression and Persistence
압축 트리거: 컨텍스트 사용률 임계 (에이전트 쪽 ~50% 등, 게이트웨이 hygiene과 이중 구조)
압축 시: 오래된 tool 결과 prune → 경계 선정 → 구조화 요약 생성 → 히스토리 치환
세션 영속화: 메시지·타이틀·플랫폼 메타를 스토리지에 기록 (→ Session Storage 문서)
Key Source Files (탐색 가이드)
run_agent.py/ agent 코어- tool registry / toolsets
- prompt builder
- context compressor
- session store
관련 문서
- Prompt Assembly
- Context Compression & Caching
- Session Storage
- Adding Tools
체크리스트
- 이 페이지의 공식 문서를 원문과 대조했다
- 로컬 환경에서 관련 명령/
config.yaml항목을 확인했다 - 보안·allowlist·자격증명 노출 위험을 점검했다
- 다음 단계 문서로 연결 경로를 확인했다
다음 단계
- 관련 공식 문서: Agent Loop Internals
- 상위 허브: Hermes Agent 소개
- 문제 해결: 트러블슈팅
기준일: 2026-07-26 — 공식 문서 동기화 코퍼스