코딩 에이전트로 작은 로컬 AI 도구 만드는 법

이 시리즈에서 만드는 것

이 시리즈는 내 PC에서 도는 모델을 불러 쓰는 작은 도구를 하나씩 만들어 봅니다. 채팅 화면, 요약 창, 엑셀 함수, CSV 분류기, 문서 질문 도구, 자연어 조회, OCR, 더빙, 개인정보 점검 도구입니다.

코드는 직접 쓰지 않고 Claude Code, Cursor 같은 코딩 에이전트에게 시킵니다. 사람이 할 일은 두 가지입니다. 무엇을 만들지 정확히 설명하는 것, 그리고 결과가 맞는지 확인하는 것입니다. 이 글은 그 두 가지를 다룹니다.

공통 구조: 부품 세 개

만들어 본 도구들은 거의 같은 구조였습니다.

부품	하는 일	예
모델 서버	모델을 메모리에 올리고 요청을 받아 답을 만듭니다	Ollama (http://localhost:11434)
작은 백엔드	파일 읽기, DB 조회, 프롬프트 조립, 모델 호출을 맡습니다	Python 파일 한 개
화면	입력을 받고 결과를 보여 줍니다	HTML 파일 한 개

흐름은 다음과 같습니다.

사용자 → 화면(HTML) → 작은 백엔드(Python) → Ollama(11434) → 모델
                    ←                    ←               ← 답

세 부품이 모두 내 PC 안에 있으므로 입력한 내용이 밖으로 나가지 않습니다.

실제로는 세 가지 형태로 나뉩니다

형태	구성	맞는 경우	시리즈의 예
화면이 직접 호출	HTML이 Ollama를 바로 부르고, Python은 그 HTML을 내 PC 주소로 띄워 주기만 합니다	텍스트만 다루는 도구	CSV 분류기, 문서 질문 도구
백엔드 경유	화면은 백엔드만 부르고, 백엔드가 파일·DB·모델을 다룹니다	파일 변환, DB 조회, 무거운 모델	채팅 웹앱, 자연어 조회, OCR
브라우저 없이	창 프로그램, 엑셀, 명령줄이 화면 역할을 합니다	설치 없이 돌려야 하거나 이미 쓰는 프로그램 안에 넣을 때	요약 창, 엑셀 함수, 더빙

첫 번째 형태에서 주의할 점이 있습니다. HTML 파일을 더블클릭해 열면 브라우저 보안 정책 때문에 Ollama 호출이 막힐 수 있습니다. 그래서 Python 표준 기능으로 간이 서버를 띄워 http://localhost:8080 같은 주소로 엽니다.

Ollama에서 알아야 할 주소 두 개

도구들이 쓰는 주소는 대부분 두 개입니다.

주소	용도
GET /api/tags	받아 둔 모델 목록을 가져옵니다. 화면의 모델 선택 상자를 채우고 서버가 켜져 있는지도 확인합니다
POST /api/generate	프롬프트를 보내 답을 받습니다. stream을 true로 두면 글자가 조금씩 옵니다

터미널에서 먼저 확인해 봅니다. 모델 이름은 예시입니다.

curl http://localhost:11434/api/tags
curl http://localhost:11434/api/generate -d '{"model":"gemma3:4b","prompt":"안녕","stream":false}'

이 두 줄이 답을 주면 도구를 만들 준비가 된 것입니다. Ollama 설치는 Ollama 처음 시작하기를 봅니다. Msty만 쓰고 있다면 Settings > Local AI에서 서비스 주소를 확인합니다.

에이전트에게 설명할 다섯 가지

막연하게 “챗봇 만들어 줘”라고 하면 외부 서비스에 의존하는 큰 프로젝트가 나오기 쉽습니다. 다음 다섯 가지를 적어 줍니다.

1. 입력: 무엇을 넣는가 (붙여넣은 글, CSV 파일, PDF, 질문 한 줄)
2. 출력: 무엇이 나오는가 (화면의 글, 저장되는 파일, 표)
3. 모델 호출: Ollama 주소와 쓰는 API, 스트리밍 여부
4. 제약: 파일 개수, 쓸 수 있는 라이브러리, 외부 주소 호출 금지
5. 실행 방법: 명령 한 줄 또는 더블클릭으로 켜져야 한다는 조건

틀로 쓰면 이렇습니다.

내 PC의 Ollama(http://localhost:11434)를 쓰는 작은 도구를 만들어 줘.
- 입력: (무엇을)
- 출력: (무엇이)
- 모델 호출: /api/tags로 모델 목록을 받아 선택 상자에 넣고, /api/generate로 답을 받는다.
- 제약: 파일은 app.py와 index.html 두 개. 외부 CDN과 외부 API를 쓰지 않는다.
- 실행: python app.py 한 줄로 켜지고 브라우저가 열린다.
Ollama가 꺼져 있거나 모델이 없을 때 화면에 이유를 보여 줘.

작은 모델에 맞춘 프롬프트 요령

만든 도구들의 코드에서 되풀이되는 방식입니다.

• 예시를 붙입니다. 분류 도구는 프롬프트에 예시를 세 개쯤 넣었습니다.
• 고를 목록을 줍니다. “아래 부서 중에서만 고르세요”라고 쓰고, 코드에서 답에 그 낱말이 들어 있는지 다시 확인합니다.
• 출력 형식을 고정합니다. 항목 추출처럼 프로그램이 읽어야 하는 답은 Ollama의 JSON 형식 옵션을 켭니다.
• 온도를 낮춥니다. 문서 작업에서는 temperature를 0.1~0.3으로 두었습니다.
• 출력 길이에 상한을 둡니다. 답이 끝없이 이어지는 것을 막습니다.

결과를 확인하는 방법

에이전트가 “완료했습니다”라고 해도 직접 돌려 봅니다.

확인할 것	방법
켜지는가	설명한 명령 한 줄로 실행해 봅니다
모델 목록이 나오는가	선택 상자에 ollama ls와 같은 이름이 보여야 합니다
Ollama가 꺼졌을 때	Ollama를 끄고 실행해 오류 안내가 나오는지 봅니다
빈 입력	아무것도 넣지 않고 버튼을 눌러 봅니다
긴 입력	몇 쪽짜리 글을 넣어 멈추지 않는지 봅니다
밖으로 나가는 요청	코드에서 http로 시작하는 주소를 찾아 localhost와 127.0.0.1뿐인지 확인합니다. 브라우저 개발자 도구의 네트워크 탭으로도 볼 수 있습니다
다른 PC에서 열리는가	서버 주소가 127.0.0.1인지 확인합니다. 0.0.0.0이면 같은 네트워크의 다른 PC에서도 접속됩니다

시리즈 순서

1. 로컬 채팅 웹앱 만들기
2. 요약 창 프로그램 만들기
3. 엑셀에서 로컬 모델을 함수로 부르기
4. CSV를 한 줄씩 분류하는 도구 만들기
5. 문서 한 개에 질문하는 도구 만들기
6. 자연어로 DB를 조회하는 도구 만들기
7. 로컬 OCR 문서 도구 만들기
8. 영상·음성 더빙 파이프라인 만들기
9. 개인정보 점검 도구 만들기
10. 문서 폴더에 요약과 태그 붙이기

처음이라면 1번과 2번부터 만들어 봅니다. 나머지는 필요한 것만 골라도 됩니다.