홈/Part 1: 기초/대화 루프 (Conversation Loop)
🧬
Part 1중급⏱ 약 45분 · 4개 섹션

대화 루프 (Conversation Loop)

에이전트의 심장

대화 루프 (Conversation Loop) 대표 이미지
✦이 챕터에서 배울 것
  • ▸QueryEngine은 1,295줄로 에이전트의 핵심 루프를 구현
  • ▸QueryEngineConfig 타입이 에이전트가 알아야 할 모든 것을 정의
  • ▸도구 실행은 검증 → 권한 → 실행 → 결과 처리의 파이프라인
1QueryEngine 아키텍처2메시지 흐름3도구 실행 사이클4상태 관리 3계층
전체 아키텍처에서 현재 위치
⚙️코어 엔진
→
🔧도구 시스템
→
🛡️보안
→
🧠컨텍스트
→
🤝멀티 에이전트
→
🌐생태계
→
⚡인프라
1

QueryEngine 아키텍처

대화 루프의 핵심 엔진 구조를 분석합니다

QueryEngineConfig메시지 정규화턴 관리에러 복구|QueryEngine.ts

QueryEngine은 Claude Code의 심장입니다. 1,295줄의 이 클래스는 사용자 입력부터 최종 응답까지의 전체 사이클을 관리합니다.

src/QueryEngine.ts — 에이전트 설정
1// src/QueryEngine.ts — QueryEngineConfig
2export type QueryEngineConfig = {
3  cwd: string
4  tools: Tools                      // 사용 가능한 도구💡
5  commands: Command[]               // 슬래시 커맨드
6  mcpClients: MCPServerConnection[] // MCP 서버
7  agents: AgentDefinition[]         // 에이전트 정의
8  canUseTool: CanUseToolFn          // 권한 확인 함수💡
9  getAppState: () => AppState       // 상태 읽기
10  setAppState: (f) => void          // 상태 수정
11  readFileCache: FileStateCache     // 파일 캐시
12  maxTurns?: number                 // 최대 턴 수💡
13  maxBudgetUsd?: number             // 최대 예산 (USD)💡
14  customSystemPrompt?: string       // 커스텀 프롬프트
15}
💡 의존성 주입
QueryEngineConfig는 의존성 주입(DI)의 교과서적 구현입니다. 에이전트가 필요한 모든 것이 생성 시점에 주입되며, 런타임에 전역 상태에 의존하지 않습니다.
2

메시지 흐름

사용자 입력 → 시스템 프롬프트 → API → 응답 → 도구 호출의 전체 흐름

메시지 정규화시스템 프롬프트 조립API 호출응답 파싱|query.tscontext.tsservices/api/client.ts

사용자 입력이 최종 응답이 되기까지의 메시지 흐름을 추적합니다.

🔄

대화 루프 시뮬레이터

▶ 실행 버튼을 누르거나 단계를 클릭하세요

3

도구 실행 사이클

도구가 호출되고 결과가 반환되는 전체 과정

도구 선택입력 검증실행결과 직렬화|tools.tsTool.ts

모델이 도구 호출을 결정하면, 4단계 파이프라인이 시작됩니다: 입력 검증 → 추가 검증 → 권한 확인 → 실행.

도구 실행 4단계
1// 도구 실행 파이프라인
2// 1. Zod 스키마 검증
3const result = tool.inputSchema.safeParse(rawInput)
4// 2. 도구별 비즈니스 검증
5const validation = await tool.validateInput(result.data, ctx)
6// 3. 4단계 권한 확인
7const permission = await tool.checkPermissions(result.data, ctx)
8if (permission.behavior === 'deny') return { error: 'denied' }
9if (permission.behavior === 'ask') await promptUser(tool, input)
10// 4. 실행 + 진행률 콜백
11const output = await tool.call(input, ctx, canUseTool, msg, onProgress)
⚠️ fail-closed
isConcurrencySafe()의 기본값이 false — 새 도구는 명시적 선언 없이 병렬 실행 불가.
4

상태 관리 3계층

Bootstrap State, AppState, Local State의 역할과 관계

불변 상태반응형 스토어로컬 격리useSyncExternalStore|bootstrap/state.tsstate/AppStateStore.ts

3계층 상태 모델: Bootstrap State (전역 불변), AppState (React 반응형), Local Task State (클로저/AsyncLocalStorage).

3계층 상태 모델
1// 1계층: Bootstrap State — 전역 불변 싱글턴
2// getSessionId(), getTotalCost() 등 불변 접근자
3// 2계층: AppState — useSyncExternalStore 패턴
4// getAppState() / setAppState(f => newState)
5// 3계층: Local Task State — AsyncLocalStorage 격리
6// 각 태스크/에이전트별 독립 상태
◈

상태 관리 3계층 구조

클릭하여 탐색

💡 비유로 이해하기

각 행을 클릭하여 대응 관계를 확인하세요

🌍회사 조직
🤖상태 관리 3계층
?

이해도 확인 퀴즈

에이전트의 대화 루프에서 maxTurns와 maxBudgetUsd가 존재하는 이유는?

✅ 학습 체크리스트

이해한 항목을 체크하고 학습 진도를 확인하세요

0/5 완료0%

📋 Chapter 2 요약: 대화 루프

이 챕터에서 배운 핵심 개념을 정리합니다

1
QueryEngine
1,295줄의 핵심 엔진. 대화 루프의 전체 사이클을 관리합니다.
2
의존성 주입
QueryEngineConfig로 모든 의존성(도구, 권한, 상태)을 주입합니다.
3
4단계 도구 실행
Zod 검증 → 비즈니스 검증 → 권한 확인 → 실행의 파이프라인.
4
3계층 상태
Bootstrap(전역 불변), AppState(반응형), Local(태스크별 격리).
5
안전 제약
maxTurns와 maxBudgetUsd로 무한 루프와 비용 폭주를 방지합니다.

다음 챕터 미리보기: 다음 챕터에서는 에이전트의 행동을 결정하는 '시스템 프롬프트 아키텍처'를 분석합니다.