SDK 없이 Ollama와 LMStudio를 지원하는 Python 에이전트 하네스 개발

실용적 조언

외부 SDK 대신 urllib.request를 사용하여 의존성 충돌 없는 가벼운 LLM 연동 환경을 구축할 수 있다.
Claude Code의 구조를 참고하여 로컬 모델에서도 작동하는 도구 사용(Tool Use) 루프를 구현할 수 있다.

섹션별 상세

외부 SDK 의존성 없이 표준 라이브러리만으로 다중 LLM 연동을 구현했다. urllib.request를 사용하여 Ollama와 LMStudio의 API를 직접 호출함으로써 설치 용량을 줄이고 환경 호환성을 높였다. 이는 복잡한 라이브러리 업데이트로 인한 의존성 충돌 문제를 방지하는 실무적 이점을 제공한다. 가벼운 배포가 필요한 엣지 컴퓨팅 환경에서 유용하게 활용될 수 있다.

에이전트의 핵심 기능을 포함하는 통합 하네스 구조를 설계했다. 턴 루프(Turn Loop) 관리와 함께 파일 편집, Bash 실행, 서브 에이전트 생성 등 7가지 필수 도구를 내장하여 즉시 실행 가능한 환경을 구축했다. 사용자는 간단한 명령어로 로컬 환경에서 자율적인 코딩 에이전트 워크플로를 재현할 수 있다. 훅 시스템과 스킬 주입 기능을 통해 에이전트의 기능을 동적으로 확장하는 것도 가능하다.

bash

cb chat --provider ollama --model llama3.1

Ollama와 Llama 3.1 모델을 사용하여 로컬 코딩 에이전트를 실행하는 명령어

Claude Code의 아키텍처를 역공학한 claw-code 프로젝트를 기반으로 실질적인 실행 환경을 완성했다. 기존 프로젝트가 구조 분석에 집중했다면, 이번 구현체는 이를 바탕으로 실제 작동하는 인터페이스와 실행 로직을 추가했다. 상용 에이전트의 설계 철학을 오픈소스 로컬 모델에 이식하여 고성능 에이전트의 작동 원리를 로컬에서 실험할 수 있는 토대를 마련했다.

용어 해설

에이전트 하네스(Agent Harness): — 에이전트가 도구를 사용하고 루프를 돌며 작업을 수행할 수 있도록 지원하는 실행 환경이다. LLM과 외부 도구 사이의 인터페이스 역할을 하며 실행 흐름을 제어한다.
턴 루프(Turn Loop): — 사용자 입력에 대해 모델이 추론하고 도구를 실행한 뒤 그 결과를 다시 모델에 전달하는 반복적인 사고-행동 순환 구조이다. 에이전트의 자율적 문제 해결 능력을 구현하는 핵심 메커니즘이다.
스킬 주입(Skill Injection): — 에이전트에게 특정 기능이나 지식을 동적으로 부여하는 기법이다. 프롬프트나 코드를 통해 에이전트의 작업 범위를 확장하여 복잡한 요구사항에 대응할 수 있게 한다.
역공학(Reverse Engineering): — 완성된 제품이나 시스템의 구조를 분석하여 그 원리를 파악하는 과정이다. 이 아티클에서는 상용 에이전트인 Claude Code의 작동 방식을 분석하여 오픈소스로 재구현하는 데 활용됐다.

언급된 도구

Ollama추천

로컬 LLM 추론 엔진

LMStudio추천

로컬 LLM 추론 및 API 서버

CoderBhaiya추천

Python 기반 에이전트 프레임워크

언급된 리소스

GitHubCoderBhaiya GitHub Repository

문서Project Writeup on Substack