Node.js를 활용한 안전한 로컬 AI 코딩 에이전트 구축하기
AI 에이전트는 복잡하게 들릴 수 있지만, 사실 그렇지 않습니다.
에이전트는 단순히 루프, 도구, 그리고 안전 규칙이 연결된 LLM일 뿐입니다.
저는 Node.js와 Ollama를 통한 Mistral을 사용하여 로컬 코딩 에이전트를 구축했습니다. 유료 API 키는 필요하지 않습니다. 모든 것이 사용자의 로컬 환경에서 실행됩니다.
이 에이전트는 JavaScript 프로젝트를 이해하는 데 도움을 줍니다. 다음과 같은 작업을 수행할 수 있습니다: • 프로젝트 파일 목록 나열 • 프로젝트 파일 읽기 • 텍스트 검색 • 코드 설명 • 버그 찾기 • 코드 변경 제안
핵심 원칙은 안전입니다. 에이전트는 파일을 검사할 수는 있지만, 직접 수정할 수는 없습니다. 대신 사용자가 검토할 수 있도록 패치 제안(patch proposal)만 반환합니다. 이를 통해 사람이 과정에 개입(human in the loop)할 수 있도록 합니다.
에이전트 작동 방식: 일반적인 챗봇은 단순한 경로를 따릅니다: 사용자가 질문함 -> 모델이 답변함
에이전트는 루프를 따릅니다: 사용자가 질문함 -> 모델이 도구를 결정함 -> JavaScript가 도구를 실행함 -> 모델이 결과를 확인함 -> 모델이 답변함
이 프로젝트에 사용된 주요 패턴: • 에이전트 루프(Agent loop): 모델이 최종 답변을 제공할 때까지 프로세스가 반복됩니다. • 도구 호출(Tool calling): 모델이 특정 JavaScript 함수를 요청합니다. • 도구 허용 목록(Tool allowlist): 승인된 도구만 실행됩니다. • 시스템 프롬프트(System prompt): 규칙을 통해 모델의 행동 방식을 지정합니다. • JSON 액션 프로토콜(JSON action protocol): 모델이 구조화된 데이터로 응답합니다. • 안전 경계(Safety boundary): 파일 접근은 프로젝트 루트 디렉토리 내로 제한됩니다.
안전이 최우선입니다. 경로 탐색(path traversal)을 방지하기 위해 safeResolve라는 함수를 사용했습니다. 이를 통해 에이전트가 프로젝트 폴더 외부의 파일에 접근할 수 없도록 보장합니다. 또한 모델의 컨텍스트를 보호하기 위해 파일 크기에 제한을 두었습니다.
프로젝트 구조: • src/cli.js: 터미널 엔트리 포인트. • src/agent.js: 핵심 루프 및 도구 디스패치. • src/ollama.js: 로컬 API 클라이언트. • src/tools.js: 안전한 파일 시스템 도구. • test/tools.test.js: 안전성 및 동작 테스트.
이 프로젝트는 Node.js와 Ollama로 실행할 수 있습니다. Mistral을 사용하거나, 더 나은 결과를 위해 Qwen2.5-Coder 또는 DeepSeek-Coder와 같은 코딩 특화 모델을 사용해 보세요.
유용한 도구를 만드세요. 범위를 좁게 유지하세요. 코드가 안전 경계를 강제하도록 만드세요.
출처: https://dev.to/gaurav101/building-a-safe-local-ai-coding-agent-with-nodejs-46ol