AI 에이전트 로컬 실행, 5분 시작 가이드 — 초보가 막히는 건 도구 호출

AI 에이전트를 로컬에서 돌린다는 건 도구를 든 LLM이 '결정→도구 실행→관찰'을 목표까지 반복하는 루프를 내 컴퓨터에서 클라우드·API 키 없이 돌리는 것이다. 5분이면 시작하고, 초보가 100% 막히는 단 하나는 '모델의 도구 호출(tool calling) 능력'이다 — 아무 로컬 모델이나 쓰면 에이전트가 도구를 안 부르고 말만 하거나, 없는 도구를 지어낸다. 그래서 모델 선택이 곧 성패다. 도구 호출에 강한 Qwen3 8B(또는 4B)를 고르면, 같은 5분이 '되는 데모'와 '겉도는 데모'로 갈린다.

쉽게 말하면: 에이전트는 리모컨을 든 조수다. 똑똑한 두뇌(LLM)만으론 부족하고, '버튼을 정확히 누르는 손'(도구 호출)이 있어야 일을 끝낸다. 손이 어설픈 모델은 아무리 말을 잘해도 일을 못 한다.

로컬 에이전트는 무엇이고 왜 로컬인가?#

==에이전트 = LLM + 도구 + 루프다. 모델이 어떤 도구를 어떤 인자로 부를지 정하면, 내 코드가 실행하고 결과를 다시 모델에 돌려준다 — 이 결정→실행→관찰을 목표까지 반복한다. 로컬로 돌리는 이유는 명확하다: 데이터가 내 컴퓨터를 안 떠나고, 토큰당 비용이 0이며, 오프라인으로 돈다. 표준 길은 Ollama다 — 모델을 OpenAI 호환 /v1 엔드포인트로 띄워주므로, 대부분의 에이전트 프레임워크가 베이스 URL만 바꿔== 로컬 모델에 붙는다. 최소 사양은 약 16GB RAM이면 시작된다.

초보가 가장 많이 막히는 한 가지는?#

모델이 도구 호출을 제대로 못 하는 것이다. 모든 로컬 모델이 tool calling을 지원하진 않고, 작은 모델(7~14B)은 멀티턴·병렬·중첩 호출에서 신뢰도가 뚝 떨어진다(BFCL 함수호출 벤치의 공통 결론). 그래서 도구 튜닝된 모델(Qwen3, Llama 3.x, Mistral Small)을 골라야 한다. 둘째 함정은 작은 모델은 더 또렷한 지시가 필요하다는 것 — 클라우드 모델엔 생략해도 되는 단계를 명시하고, 온도(temperature)는 0.1처럼 낮게 둬 도구 인자가 흔들리지 않게 한다. 정직한 한계도 알자: 로컬 7~70B는 복잡한 다단계 추론에서 프런티어 클라우드 모델을 못 따라간다.

어떤 모델·프레임워크로 시작하나?#

모델은 Qwen3, 프레임워크는 목적에 따라다. 모델은 ollama pull qwen3:8b(아주 약하면 4b), 다운로드는 7B급이 약 4.7GB라 대부분 PC에서 돈다. 프레임워크는 둘 중 하나: smolagents는 코드-퍼스트로 모델이 파이썬을 써 실행하는 최소 루프라 배우기 좋고(Ollama엔 LiteLLM로 붙는다), Pydantic AI는 입력·도구·출력을 타입으로 못박아 검증·신뢰성이 강하다(단 아직 1.0 전이라 API 변동 주의). 권장 순서는 raw 파이썬 ~60줄로 루프를 먼저 이해한 뒤 프레임워크를 얹는 것이다.

직접 5분 안에, 안전하게 해보려면?#

핵심은 에이전트는 '말'이 아니라 '실행'이라 안전장치를 1일차에 같이 켜는 것이다.

• 시작: Ollama로 qwen3:8b를 받고, smolagents로 도구 1~2개(검색·파일읽기)부터 붙인다.
• 안전: 에이전트는 명령을 실제로 돌리니 허용목록·인자 검증(JSON 스키마)·타임아웃·단계 상한·전 호출 로깅을 처음부터 건다.
• 검증: 작은 목표(폴더 문서를 읽어 할 일을 JSON으로 추출)로 내 환경에서 직접 재고, 부족하면 모델·온도·지시를 하나씩 바꾼다.

참고: 모델·용량·사양 수치는 2026년 공개 가이드·모델카드 기준이며 양자화·하드웨어·버전에 따라 달라진다. tool calling 지원과 프레임워크 API는 빠르게 바뀌니(특히 Pydantic AI는 1.0 전) 도구 버전을 먼저 확인하라. 에이전트 품질은 내 작업·도구로 직접 측정하라(리더보드는 출발점). 에이전트 생태계는 빠르게 바뀌니 분기별로 다시 본다.

참고 링크#

• Ollama(로컬 모델 런타임)
• smolagents(코드-퍼스트 에이전트)
• Pydantic AI(타입 안전 에이전트)
• Qwen3(도구 호출 모델)
• Gorilla/BFCL(함수호출 벤치)