✨ 지금 바로 Quick Star CLI를 사용해 보세요! 우아한 명령줄 인터페이스 (Command-line interface), 실시간 스트리밍 응답 (Real-time streaming responses), 그리고 강력한 코드 생성 (Code generation) 능력을 갖춘 지능형 AI 에이전트입니다.

🎯 스네이크 게임을 플레이해 보세요! 이 완전한 기능의 게임은 Quick Star CLI와의 자연어 대화만으로 완전히 제작되었으며, 다음을 보여줍니다:

• 🧠 지능형 코드 생성 (Intelligent Code Generation) - 간단한 설명만으로 완전한 게임 로직 구현
• 🔧 실시간 디버깅 (Real-time Debugging) - 즉각적인 코드 반복 및 개선
• 📁 스마트 파일 관리 (Smart File Management) - 복잡한 프로젝트 구조 처리
• 🎨 대화형 애플리케이션 (Interactive Applications) - 매력적인 사용자 경험 생성

놀라운 것을 만들 준비가 되셨나요? 아래의 설치 가이드를 따라 Quick Star CLI와 함께 창작을 시작해 보세요!

이 프로젝트는 기본적인 도구 호출 (Tool calling)부터 히스토리 제어 (History control) 기능이 있는 고급 스트리밍 에이전트 (Streaming agents)에 이르기까지, AI 에이전트의 점진적인 발전을 보여줍니다. 각 장은 이전 장을 바탕으로 구축되어, 점진적인 개선과 새로운 기능들을 보여줍니다.

├── .env # 환경 설정 (모든 장에서 공유됨)
├── .env.example # 환경 템플릿
├── requirements.txt # Python 의존성
...

네이티브 함수 호출 (Native Function Call): 타입 안정성 (Type safety)을 갖춘 표준 OpenAI JSON Schema 인터페이스
XML 도구 호출 (XML Tool Call): 모든 텍스트 모델과 호환되는 범용 XML 형식

• 두 방식의 비교 및 사용 사례
• 도구 호출 (Tool calling) 패턴 이해를 위한 기초

ReAct 패턴 (ReAct pattern): 지능형 에이전트를 위한 Think-Act-Observe 사이클
재귀적 대화 처리 (Recursive conversation handling): 지속적인 AI 상호작용을 위한 처리
사용자 승인 시스템 (User approval system): 안전 제어 기능을 갖춘 위험한 작업용
싱글톤 대화 관리자 (Singleton conversation manager): 일관된 상태 관리를 위한 관리자

• 에러 핸들링 (Error handling)을 포함한 완전한 도구 실행 프레임워크

문자 단위 스트리밍 (Character-by-character streaming): 즉각적인 AI 응답 가시성 확보
스트리밍 도구 호출 (Streaming tool calls): 도구 실행과 원활하게 작동하는 스트리밍
설정 외부화 (Configuration externalization): .env 파일 관리를 통한 설정 분리

• 표준 모드로 자동 폴백 (Auto-fallback)되는 우아한 성능 저하 (Graceful degradation)
• 전체 응답을 기다릴 필요 없는 개선된 사용자 경험

지능형 멀티 세션 및 싱글 세션 전략을 통한 자동 히스토리 압축 (Auto history compression)
컨텍스트 사용률 표시를 포함한 실시간 토큰 모니터링 (Real-time token monitoring)
모델별 가격 책정 및 세션 요약을 포함한 종합적인 비용 추적 (Comprehensive cost tracking)
시스템 메시지 및 최근 컨텍스트를 위한 보존 보장 (Preservation guarantees)
장기 대화를 위한 성능 최적화 (Performance optimization)

TOP/BOTTOM 메시지 크로핑 (Cropping) 전략을 통한 정밀한 컨텍스트 제어 (Precision context control)
수동 대화 관리를 위한 스마트 컨텍스트 크로퍼 (Smart Context Cropper) 도구
최신 사용자 메시지 및 시스템 프롬프트를 보호하는 안전 보장 (Safety guarantees)
컨텍스트 연속성 유지를 위한 크로핑된 콘텐츠에 대한 요약 지원 (Summary support)
기존 자동 압축 및 비용 추적 시스템과의 통합 (Integration)

자동화된 작업 정리 및 진행 상황 추적을 위한 TodoWrite 도구
복잡한 요청을 구조화된 목록으로 변환하는 지능형 워크플로 분해 (Intelligent workflow breakdown)
pending/in_progress/completed 라이프사이클을 포함한 실시간 상태 관리 (Real-time state management)
조기 작업 완료를 방지하는 품질 보증 게이트 (Quality assurance gates)
단순 실행 대비 할 일 목록(Todo list)이 가치를 더하는 시점을 결정하는 컨텍스트 인식 (Context awareness)

복잡한 작업을 전문화된 하위 에이전트 (Sub-agents)에게 위임하기 위한 Task Tool
격리된 대화 컨텍스트 및 라이프사이클 관리를 지원하는 SubagentManager
하위 에이전트가 전체 도구 액세스 권한을 가지고 독립적으로 실행되는 자율 실행 (Autonomous execution)
적절한 동시성 (Concurrency) 지원을 위해 모든 도구를 변환하는 비동기 도구 시스템 (Async tool system)
복잡한 워크플로를 관리 가능한 단위로 분해하는 작업 위임 흐름 (Task delegation flow)
동시 실행 및 리소스 격리를 통한 전문화의 이점 (Specialization benefits)

MCP 프로토콜 지원 (MCP Protocol Support) 외부 Model Context Protocol 서버에 연결하기 위한 지원
동적 도구 로딩 (Dynamic Tool Loading) MCP 도구의 자동 검색 및 통합
멀티 서버 지원 (Multi-Server Support) 여러 MCP 서버에 동시에 연결
통합 도구 인터페이스 (Unified Tool Interface) 외부 MCP 도구와 내장 도구의 원활한 통합
설정 기반 설정 (Configuration-Driven Setup) JSON 설정을 통한 MCP 서버의 간편한 관리
샘플 MCP 서버 (Sample MCP Servers) 일기 예보 및 계산기 구현 포함

• Python 3.8 이상
• Conda (권장) 또는 pip
• OpenAI 호환 API 액세스 (OpenRouter, OpenAI 등)

git clone https://github.com/woodx9/build-your-claude-code-from-scratch.git
cd build-your-claude-code-from-scratch

# 새로운 conda 환경 생성
conda create -n agentLearning python=3.11
# 환경 활성화
...

다음 방법 중 하나를 사용하여 종속성을 설치할 수 있습니다:

# 모든 필수 패키지 설치
pip install -r requirements.txt

# 또는 다른 챕터
cd chapter5_smart_context
pip install -e .

quickstar

❯ quickstar
══════════════════════════════════════════════════
✦ ✦ ✦ ✦ ✦ ✧ ✧ ✧ ✧ ✧
...

예시 환경 파일을 복사합니다:

cp .env.example .env

본인의 API 자격 증명으로 .env 파일을 편집합니다:

OpenAI API 설정

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_MODEL=anthropic/claude-sonnet-4

단위는 k(천)입니다

MODEL_MAX_TOKENS=200
COMPRESS_THRESHOLD=0.8

변수	설명	예시
OPENAI_API_KEY	귀하의 API 키	sk-or-v1-...
OPENAI_BASE_URL	API 엔드포인트 URL	https://openrouter.ai/api/v1
OPENAI_MODEL	사용할 모델	anthropic/claude-sonnet-4
MODEL_MAX_TOKENS	응답을 위한 최대 토큰 수 (천 단위)	200
COMPRESS_THRESHOLD	히스토리 압축 임계값 (0.0-1.0)	0.8

cd chapter1_tool_call_api
# Native Function Call 예제 실행
python native_function_call.py
...

이 프로젝트는 모든 OpenAI 호환 API를 지원합니다. 테스트된 제공업체는 다음과 같습니다:

OpenRouter(권장): 여러 모델에 대한 접근을 제공합니다
OpenAI: 공식 OpenAI API
로컬 LLM 서버 (Local LLM servers): OpenAI API 형식을 구현하는 모든 서버

• openrouter.ai에서 가입하세요

• 대시보드에서 API 키를 받으세요

• https://openrouter.ai/api/v1을 기본 URL (base URL)로 사용하세요

• 다음과 같은 사용 가능한 모델 중에서 선택하세요:
  anthropic/claude-sonnet-4
openai/gpt-4
meta-llama/llama-3.1-70b-instruct

• platform.openai.com에서 API 키를 받으세요

• https://api.openai.com/v1을 기본 URL (base URL)로 사용하세요

• 다음과 같은 모델을 사용하세요:
  gpt-4
gpt-3.5-turbo

chapter_X/
├── src/
│ ├── core/
...

참고 (Note): Chapter 1은 도구 호출 (tool calling) 개념을 보여주는 직접적인 Python 파일들로 구성된 더 단순한 구조를 가지고 있습니다.

APIClient: 환경 변수 설정을 사용하는 싱글톤 패턴 (Singleton pattern) 클라이언트
BaseAgent: ReAct 패턴을 구현하는 핵심 에이전트 로직
ToolManager: 사용 가능한 도구 및 그 실행을 관리
ConversationManager: 대화 기록 및 컨텍스트 (context)를 처리

이 프로젝트에는 포괄적인 에러 처리 (error handling)가 포함되어 있습니다:

• 누락된 환경 변수는 설명이 포함된 에러를 발생시킵니다

• API 실패는 포착되어 보고됩니다

• 도구 실행 에러는 유연하게 처리됩니다

환경 변수를 찾을 수 없음 (Environment variables not found)
ValueError: 环境变量 OPENAI_API_KEY 未设置或为空。请检查 .env 文件中的配置。

해결 방법 (Solution): .env 파일이 존재하고 필요한 모든 변수를 포함하고 있는지 확인하세요

API 연결 실패 (API connection failed)
API请求失败: Connection error

해결 방법 (Solution): 인터넷 연결과 API 엔드포인트 (endpoint) URL을 확인하세요

유효하지 않은 API 키 (Invalid API key)
API请求失败: Unauthorized

해결 방법 (Solution): API 키가 정확하고 충분한 크레딧 (credits)이 있는지 확인하세요

# 환경 변수가 올바르게 로드되었는지 테스트
python -c "
import sys
...

• 저장소 (repository)를 포크 (Fork) 하세요
• 기능 브랜치 (feature branch)를 생성하세요
• 변경 사항을 적용하세요
• 철저하게 테스트하세요
• 풀 리퀘스트 (pull request)를 제출하세요

MIT 라이선스

이슈 및 질문 사항:

• 문제 해결 (troubleshooting) 섹션을 확인하세요
• 챕터별 README 파일을 검토하세요
• 저장소에 이슈 (issue)를 생성하세요

참고: 이 프로젝트는 점진적인 AI 에이전트 (AI agent) 개발 과정을 보여줍니다. 기본적인 도구 호출 (tool calling) 개념을 이해하려면 챕터 1부터 시작하세요. 그 다음 ReAct 패턴을 위해 챕터 2로, 스트리밍 (streaming) 기능을 위해 챕터 3으로, 마지막으로 고급 이력 관리 (history management)를 위해 챕터 4로 넘어가시기 바랍니다.