AI 프로그래밍 어시스턴트 구축하기: 의존성 없는 Agent Loop 구현

본문은 오픈소스 프로젝트 CodeLite를 기반으로 하며, 순수 Python(외부 의존성 없음)을 사용하여 완전한 AI 프로그래밍 어시스턴트를 구축하는 방법을 심층 분석합니다. OpenAI Function Calling 규격을 결합하여 Agent의 핵심 원리를 이해할 수 있도록 단계별로 안내합니다.

서론

2024년, AI 프로그래밍 어시스턴트는 개발자들의 새로운 애착 대상이 되었습니다. Cursor, GitHub Copilot, Claude Code…… 이 도구들의 배후에는 하나의 핵심 개념이 있습니다: Agent Loop.

하지만 대부분의 오픈소스 구현체는 LangChain, LlamaIndex와 같은 무거운 프레임워크에 의존합니다. 오늘 우리는 조금 다른 일을 해보려 합니다: 순수 Python 표준 라이브러리만을 사용하여, 처음부터 완전한 AI 프로그래밍 어시스턴트를 구현하는 것입니다.

왜일까요? 원리를 이해하는 가장 좋은 방법은 직접 만들어 보는 것이기 때문입니다.

최종 결과물

원리를 설명하기 전에 결과부터 보겠습니다:

You> 현재 디렉토리에 어떤 파일이 있는지 확인해줘
🔧 Calling: list_dir(path=".")
📄 결과: 15개의 파일을 찾았습니다...
...

단순해 보이나요? 그 이면의 이야기는 결코 단순하지 않습니다.

Agent Loop: 핵심 원리

Agent Loop란 무엇인가?

Agent Loop는 AI Agent의 핵심 순환 구조로, LLM이 다음과 같은 작업을 수행할 수 있게 합니다:

1. 사고 (Thinking) — 사용자 요구사항 분석
2. 결정 (Decision) — 적절한 도구 선택
3. 실행 (Execution) — 도구를 호출하여 작업 완료
4. 관찰 (Observation) — 실행 결과 획득
5. 순환 (Looping) — 결과에 따라 작업이 완료될 때까지 계속 행동

의사 코드(Pseudo-code)로 표현하면 다음과 같습니다:

while True:
    response = llm.chat(messages, tools)

...

OpenAI Function Calling 규격

Agent Loop의 도구 호출은 OpenAI의 Function Calling 규격을 기반으로 합니다. 핵심 구조는 다음과 같습니다:

{
    "tools": [
        {
...

LLM이 응답할 때는 tool_calls 필드가 포함됩니다:

{
    "choices": [{
        "message": {
...

코드 구현

1. 도구 등록 시스템 (Tool Registration System)

도구 등록은 Agent의 기초입니다. 우리는 데코레이터 패턴(Decorator Pattern)을 사용하여 도구 정의를 우아하게 만들었습니다:

# tools.py
_registry = {}

...

설계 하이라이트:

• 데코레이터 패턴: @tool 한 줄로 깔끔하게 등록
• 자동 스키마(Schema) 생성: 함수의 시그니처와 타입 어노테이션(Type Annotation)으로부터 자동으로 추론하여 JSON을 직접 작성할 필요가 없음
• 위험 표시: dangerous=True로 위험한 명령을 표시하며, 이는 나중에 보안 계층에서 사용됨

2. Agent Loop 핵심

이것이 전체 시스템의 영혼입니다:

# agent.py
MAX_ITERATIONS = 30  # 무한 루프 방지

...

주요 설계 포인트:

1. 순환 상한선: MAX_ITERATIONS = 30을 설정하여 LLM이 오작동하여 무한 루프에 빠지는 것을 방지
2. 컨텍스트 압축 (Context Compression): 토큰이 가득 차면 이전 대화를 자동으로 요약하여 긴 대화가 끊기지 않도록 보장
3. 보안 차단 (Security Interception): 위험한 명령은 사용자의 확인이 필요함
4. 자동 복구 (Auto-repair): 명령이 실패할 경우 자동으로 오류를 분석하고 수정 제안

3. LLM 클라이언트

OpenAI 호환 API를 지원하여, 하나의 클라이언트로 모든 Provider를 사용할 수 있습니다:

# llm.py
class LLMClient:
    def __init__(self, provider, model, api_key, api_base):
...

호환성: OpenAI 호환 API 형식을 사용하기 때문에 DashScope(통의천문), DeepSeek, MiMo(샤오미), Ollama(로컬 모델) 등을 모두 직접 사용할 수 있습니다.

4. 보안 계층 (Safety Layer)

보안은 Agent 시스템의 생명선입니다:

# safety.py
DANGER_PATTERNS = [
    r"\brm\s+(-[rf]+\s+|.*--recursive)",  # rm -rf
...

3단계 리스크:

• 🟢 안전: 즉시 실행 (ls, cat, git status)
• 🟡 확인 필요: 출력 후 확인 (git push, pip install)
• 🔴 위험: 이중 확인 필요 (rm -rf, sudo)

5. 컨텍스트 관리

긴 대화를 유지하는 비결은 지능적인 압축입니다:

# context.py
class ConversationContext:
    def __init__(self, max_tokens=30000):
...

실제 사용 효과

시나리오 1: 파일 조작

You> 프로젝트 구조 좀 봐줘
🔧 Calling: tree_view(path=".", max_depth=2)
📁 .
...

시나리오 2: 코드 리팩토링 (Code Refactoring)

You> utils.py에 있는 중복 코드를 함수로 추출해줘
🔧 Calling: read_file(path="utils.py")
📄 읽기 완료, 3곳의 중복 코드 발견
...

시나리오 3: 자동 수정

You> 테스트 실행해줘
🔧 Calling: run_command(command="python -m pytest")
❌ FAILED - ModuleNotFoundError: No module named 'requests'
...

LangChain 구현과 비교

특성	순수 Python 구현	LangChain Agent
의존성	외부 의존성 없음	langchain 및 의존성 필요
...

권장 사항:

• 원리 학습 → 직접 구현
• 프로덕션 환경 (Production) → LangChain/LangGraph 사용
• 빠른 프로토타이핑 (Prototype) → 프레임워크 사용
• 심층 커스텀 → 직접 구현

요약

AI 프로그래밍 어시스턴트의 핵심 구성 요소:

1. 도구 등록 시스템 (Tool Registration System) — AI가 무엇을 할 수 있는지 알게 함
2. Agent Loop — AI가 자율적으로 결정하고 실행하게 함
3. LLM 클라이언트 (LLM Client) — 대규모 언어 모델 (LLM)과 연결하는 가교
4. 보안 계층 (Security Layer) — AI의 파괴적인 행동을 방지
5. 컨텍스트 관리 (Context Management) — 긴 대화의 일관성을 유지

이 5가지 구성 요소가 AI Agent의 최소 기능 제품 (MVP) 아키텍처를 구성합니다. 이것들을 이해하면 모든 AI Agent 도구의 밑바닥 원리를 이해한 것입니다.

다음 글 예고

《Agent Loop 심층 탐구: 단일 호출에서 다단계 추론까지》 — 작업 분해, 병렬 실행, 오류 복구 등 Agent가 복잡한 작업을 처리하는 고급 기능에 대해 심도 있게 다룰 예정입니다.

참고 자료

• OpenAI Function Calling 문서
• LangChain Agent 아키텍처
• CodeLite 소스 코드

본문은 오픈소스 프로젝트 CodeLite를 기반으로 작성되었습니다. 코드는 공개되어 있으니 Star와 PR을 환영합니다.

tags: ai-agent, python, llm, agent-loop, developer-tools
series: ai-agent-development