에이전트 루프

개요

에이전트 루프는 사용자 메시지가 들어오고 응답이 생성되기까지의 전체 실행 경로를 정의한다. 각 단계가 순차적으로 실행되며, 도구 호출이 필요하면 루프가 반복된다.

실행 경로

intake → context assembly → model inference → tool execution → streaming replies → persistence

상세 흐름

┌─────────────┐
│   Intake    │  메시지 수신 및 검증
└──────┬──────┘
       │
┌──────▼──────┐
│  Context    │  컨텍스트 조립 (부트스트랩 + 히스토리 + 토큰 예산)
│  Assembly   │
└──────┬──────┘
       │
┌──────▼──────┐
│   Model     │  AI 모델 추론 요청
│  Inference  │
└──────┬──────┘
       │
┌──────▼──────┐
│    Tool     │  도구 호출 필요 시 실행
│  Execution  │  (없으면 건너뜀)
└──────┬──────┘
       │
┌──────▼──────┐
│  Streaming  │  응답을 실시간 스트리밍
│   Replies   │
└──────┬──────┘
       │
┌──────▼──────┐
│ Persistence │  세션에 결과 저장
└─────────────┘

진입점 (Entry Points)

에이전트 루프를 시작하는 두 가지 방법이 있다.

1. Gateway RPC

게이트웨이 WebSocket API를 통한 호출:

• agent: 비동기 에이전트 실행 (스트리밍 응답)
• agent.wait: 동기 에이전트 실행 (완료까지 대기)

2. CLI agent 명령어

openclaw agent --message "작업을 수행해주세요"

실행 단계 상세

1. Validation (검증)

• 메시지 형식 검증
• 세션 존재 여부 확인
• 권한 확인

2. Resolve Model/Skills (모델 및 스킬 해석)

• 에이전트 설정에서 사용할 모델 결정
• 스킬 로딩 우선순위에 따라 사용 가능한 스킬 해석
• 도구 목록 구성

3. Run Runtime (런타임 실행)

• 컨텍스트 엔진으로 메시지 세트 구성
• 토큰 예산 내에서 히스토리 포함
• AI 모델에 추론 요청

4. Stream Events (이벤트 스트리밍)

루프 실행 중 다음 유형의 이벤트가 스트리밍된다:

5. Completion (완료)

• 모든 도구 호출이 완료되고 최종 응답이 생성되면 루프 종료
• 세션 JSONL 파일에 결과 저장

세션 직렬화

동일 세션 키에 대한 실행은 **직렬화(serialize)**된다. 즉, 같은 세션에서 여러 메시지가 동시에 들어와도 순서대로 하나씩 처리된다.

세션 A: 메시지1 → [처리 중] → 메시지2 → [대기] → [처리 중] → ...
세션 B: 메시지1 → [처리 중] → ...  (A와 독립적으로 병렬 실행)

이는 컨텍스트 일관성을 보장하기 위함이다.

훅 시스템

에이전트 루프의 특정 시점에 커스텀 로직을 삽입할 수 있다.

Internal Gateway Hooks (내부 게이트웨이 훅)

게이트웨이 레벨에서 동작하는 내장 훅이다. 메시지 전처리, 후처리, 라우팅 결정 등에 사용된다.

Plugin Hooks (플러그인 훅)

외부 플러그인이 등록하는 훅이다. 에이전트 루프의 각 단계에 개입하여 동작을 확장할 수 있다.

훅을 사용하면 다음과 같은 작업이 가능하다:

• 메시지 수신 시 전처리 (필터링, 변환)
• 도구 호출 전후 로깅
• 응답 후처리 (포맷 변환, 알림)
• 에러 발생 시 커스텀 처리