VPS에서 Claude AI 에이전트 구축하는 방법

Claude를 활용한 에이전트 구축의 의미

Claude를 활용한 에이전트 구축이란 Claude를 추론의 핵심 엔진으로 사용하고, 루프(loop), 도구(tools), 데이터는 사용자의 서버에서 직접 운영하는 것을 의미합니다. Claude가 수행할 작업을 결정하면 사용자의 VPS가 이를 실행합니다. 사용자가 Claude에게 작업과 현재 상태를 전달하면, Claude는 답변을 내놓거나 도구 사용을 요청합니다. 그러면 사용자의 코드가 해당 도구를 실행하고 결과를 다시 Claude에게 전송하며, 작업이 완료될 때까지 이 루프가 반복됩니다. 지능은 인터넷을 통해 호출하는 서비스이며, 그 외 모든 구성 요소는 사용자의 소유입니다.

이러한 역할 분담이 바로 이 방식의 핵심 장점입니다. 모델을 직접 운영하지 않고도 최첨단 수준의 추론 능력을 활용할 수 있으며, 도구가 사용자의 하드웨어에서 실행되므로 에이전트가 접근할 수 있는 범위를 완전히 통제할 수 있습니다. 이미 첫 번째 Claude 프로그램을 구축해 보셨다면, VPS에서 첫 Claude 앱 실행하기 가이드를 통해 이 가이드의 기반이 되는 기초 지식을 확인하실 수 있습니다.

Claude의 핵심: Messages API

Claude를 호출하는 모든 요청은 단일 엔드포인트인 Messages API를 통합니다. 현재까지의 대화 내용과 에이전트가 사용할 수 있는 도구 목록을 전송하면, Claude가 다음 메시지를 반환합니다. 이 메시지는 최종 답변이거나 도구 호출 요청 중 하나입니다. 직접 구현하는 방식에서 별도의 "에이전트 API"는 존재하지 않습니다. 도구 사용은 이 단일 엔드포인트의 기능이며, 이를 둘러싼 루프는 직접 구현해야 합니다.

Claude는 호출 간에 상태를 유지하지 않으므로 스스로는 아무것도 기억하지 못합니다. 각 요청마다 전체 대화 내용을 포함해야 합니다. 코드가 대화 기록을 보관하고 매 턴마다 전송해야 하므로 긴 세션에서 턴이 진행될수록 더 많은 토큰 비용이 발생합니다. 이는 제약이라기보다 설계상의 선택입니다. 상태가 서버에 존재하므로 Claude가 무엇을 볼지 정확히 결정할 수 있으며, 작업과 관련된 정보는 통제할 수 없는 곳에 저장되지 않습니다. 다만 프롬프트가 계속 커진다는 의미이기도 합니다. Claude의 컨텍스트 윈도우는 이를 충분히 수용하지만, 동일한 루프 내의 로컬 모델은 그렇지 못합니다. 이것이 바로 Ollama에서 긴 프롬프트가 잘리지 않도록 num_ctx를 높여야 하는 이유입니다.

도구 사용과 에이전트 루프

Claude를 활용한 에이전트 루프의 구조는 간단합니다. 먼저 도구 정의를 포함한 요청을 보냅니다. Claude는 작업을 읽고, 실행이 필요하다고 판단하면 도구 이름과 입력값이 포함된 도구 사용 요청을 반환합니다. 사용자의 코드는 해당 도구를 실행한 뒤, 그 결과를 다음 요청에 담아 다시 Claude에게 보냅니다. Claude는 결과를 확인하고 다른 도구를 호출하거나 최종 답변을 작성합니다. 도구 호출을 멈추면 작업이 완료된 것입니다.

이 루프는 구조가 명확하고 제어가 쉬워 직접 몇 줄의 코드로 작성하는 경우가 많습니다. 공식 SDK는 루프를 대신 실행해 주는 도구 러너(tool runner)를 제공합니다. 도구 함수를 제공하면 SDK가 Claude 호출, 도구 실행, 결과 전달 과정을 반복하며 Claude가 작업을 마칠 때까지 자동으로 처리합니다. 방식은 다르지만 본질적인 형태는 동일합니다. 러너는 루프를 직접 작성하는 번거로움을 덜어줄 뿐입니다. 루프의 개념이 여전히 추상적으로 느껴진다면, 러너를 사용하기 전에 최소한의 루프를 직접 작성해 보는 것이 좋습니다. 이는 AI 에이전트를 처음부터 학습하기 위한 단계별 경로에서 모든 과정의 기초가 되는 단계입니다.

빌드하는 세 가지 방법과 VPS에 적합한 방식

Claude 에이전트를 빌드하는 방법은 세 가지가 있으며, 각 방식은 시스템의 어느 부분을 직접 운영하느냐에 따라 차이가 있습니다.

첫 번째는 직접 작성한 코드로 Claude API를 호출하고 자체 도구를 사용하는 방식입니다. 루프를 직접 구현하거나 SDK의 도구 실행기(tool runner)를 사용하며, 전체 시스템을 VPS에서 호스팅합니다. 이 방식은 도구, 데이터, 보안에 대한 완전한 통제권을 가질 수 있고 서버에서 일반적인 프로그램으로 실행되므로 가장 흔히 선택됩니다. 이 가이드의 대부분은 이 경로를 가정합니다.

두 번째는 Claude Agent SDK를 사용하는 방식입니다. 이는 코딩 에이전트인 Claude Code를 기반으로 빌드할 수 있도록 라이브러리 형태로 패키징한 것입니다. 전체 에이전트 루프와 파일 읽기·쓰기, 셸 명령 실행, 검색을 위한 내장 도구가 포함되어 있어 처음부터 모든 것을 조립할 필요가 없습니다. 이 역시 자체 서버에서 실행되므로, 직접 하네스를 구축하지 않고도 강력한 파일 및 셸 제어 에이전트가 필요한 경우 VPS에 매우 적합합니다. 파일 읽기와 셸 명령 실행이 가능한 에이전트는 무인 상태로 작동하기 전에 격리 조치가 필요하며, 서버에서 Claude Code를 안전하게 실행하는 방법에서 권한 시스템, 샌드박스, 격리 옵션을 다룹니다.

세 번째는 관리형 에이전트(Managed Agents)로, Anthropic이 루프를 실행하고 에이전트의 도구가 실행되는 샌드박스를 호스팅하는 방식입니다. 이는 운영 부담이 거의 없는 방식이지만, 에이전트의 작업 공간이 VPS가 아닌 Anthropic의 인프라에 위치합니다. 운영 업무를 최소화하고 싶고 도구가 자신의 머신에서 직접 실행될 필요가 없을 때 이 방식을 선택하십시오. 나머지 두 방식에서는 서버가 에이전트의 거점이 되며, 이 가이드의 나머지 부분은 이를 중심으로 설명합니다.

MCP를 사용한 도구 연결

어떤 경로를 선택하든 에이전트를 실제 시스템에 연결해야 하며, Model Context Protocol은 이를 수행하는 깔끔한 방법입니다. MCP는 에이전트에 도구와 데이터를 노출하기 위한 개방형 표준입니다. 모든 서비스에 대해 통합 기능을 직접 코딩하는 대신, 해당 기능을 이미 도구로 제공하는 MCP 서버를 Claude에 지정하면 됩니다. 각 MCP 서버는 필요한 권한만 가진 작은 서비스 형태로 동일한 VPS에서 실행할 수 있으며, 이에 관한 내용은 VPS에서 MCP 서버 실행하기에서 다룹니다.

모델 선택하기

Claude는 여러 모델로 제공되며, 모델을 선택할 때는 성능, 속도, 비용 사이의 균형을 고려해야 합니다. 이 글을 작성하는 시점의 주요 선택지는 다음과 같습니다. 복잡한 추론과 긴 에이전트 작업에 적합한 기본 모델인 Claude Opus 4.8 (claude-opus-4-8), 많은 작업에서 Opus에 근접한 성능을 내면서도 더 저렴하고 빠른 균형 잡힌 옵션인 Claude Sonnet 5 (claude-sonnet-5), 그리고 단순하고 대량의 작업 처리에 가장 빠르고 저렴한 Claude Haiku 4.5 (claude-haiku-4-5)가 있습니다. 이들보다 상위에는 가장 까다로운 작업에 최적화된 최고 성능의 모델인 Claude Fable 5 (claude-fable-5)가 있습니다. 코드에는 날짜를 제외한 정확한 모델 식별자를 사용하십시오.

모델을 혼합하여 사용하는 것이 실용적인 패턴입니다. 일상적인 도구 호출은 저렴한 모델이 처리하게 하고, 어려운 결정은 더 강력한 모델이 처리하게 하십시오. 모델은 요청 내에서 단순한 문자열로 지정되므로, 한 줄만 수정하면 모델을 교체할 수 있습니다. 따라서 처음에는 성능이 뛰어난 기본 모델로 시작한 뒤, 품질보다 속도나 비용이 더 중요한 경우 하위 모델로 조정하십시오.

VPS에서 강화된 서비스로 실행하기

에이전트는 계속 실행되어야 유용하며, 격리되어야 안전합니다. VPS 환경에서는 터미널에서 수동으로 실행하는 대신 강화된 시스템 서비스로 에이전트를 구동해야 이 두 가지를 모두 달성할 수 있습니다. 서비스로 등록하면 부팅 시 자동으로 시작되고, 충돌 시 재시작되며, 로그가 journal에 기록됩니다. 강화된 설정은 에이전트를 필요한 권한만 가진 비특권 사용자로 실행하므로, 버그나 잘못된 명령이 발생해도 피해 범위가 제한됩니다. 서비스 유닛은 프로세스가 접근할 수 있는 범위를 제한할 뿐이므로, 나머지 보안은 에이전트 자체의 기능이 담당해야 합니다. 이는 설치할 가치가 있는 DeepSeek Harness 플러그인이 다른 스택에서 수행하는 역할인 비용 제한, 도구별 권한 규칙, 프롬프트 인젝션 스캔 등이 담당합니다.

가장 중요한 규칙은 Claude API 키를 서버 측에만 보관하는 것입니다. 이 키는 모든 호출에 대한 비용을 지불하고 권한을 부여하므로, 에이전트 사용자만 읽을 수 있는 파일에 저장하고 환경 변수로 서비스에 로드해야 합니다. 코드나 저장소, 또는 브라우저가 접근할 수 있는 곳에는 절대 두지 마십시오. 에이전트를 위한 완전하고 강화된 서비스 유닛을 여기서 생성하십시오:

그런 다음 서버 설정을 마무리하십시오. SSH는 키 기반 인증만 허용하고, 관리 계정은 VPS의 SSH 강화 가이드에 따라 잠그십시오. 에이전트를 구축하는 동안 대화형 세션에서 직접 제어하고 싶다면 tmux를 사용하여 VPS에서 Claude Code 실행하기가 좋은 대안입니다. 같은 서버에 두 번째 세션을 열면 사용자가 일일이 명령을 전달할 필요 없이 두 세션 간에 작업을 주고받을 수 있습니다. 특정 모델에 국한되지 않고 이 모든 개념의 기반을 이해하고 싶다면, VPS에서 나만의 AI 에이전트 구축하기 가이드가 기초를 설명합니다.

터미널 기반의 코딩 보조 도구를 원하신다면 VPS에서 코딩 AI 에이전트 실행하기에서 Aider와 Goose에 대해 다룹니다.

FAQ

에이전트를 구축할 때 어떤 Claude 모델을 사용해야 합니까?

기본적으로 성능이 우수한 Claude Opus 4.8(claude-opus-4-8)로 시작하여 필요에 따라 조정하십시오. 대부분의 작업에는 더 저렴하고 빠른 Claude Sonnet 5(claude-sonnet-5)가 적합하며, 단순하고 반복적인 대량 작업에는 Claude Haiku 4.5(claude-haiku-4-5)가 가장 좋습니다. 가장 어려운 작업에는 Claude Fable 5(claude-fable-5)가 가장 뛰어난 성능을 발휘합니다. 일반적인 패턴은 일상적인 단계에는 저렴한 모델을 사용하고, 중요한 결정이 필요한 단계에는 강력한 모델을 사용하는 것입니다. 모델 전환은 코드 한 줄만 수정하면 되기 때문입니다.

에이전트 전체를 VPS에서 실행해야 합니까, 아니면 Anthropic에서 실행합니까?

접근 방식에 따라 다릅니다. Claude API를 사용하여 직접 루프를 작성하거나 Claude Agent SDK를 사용하면 에이전트는 전적으로 VPS에서 실행되며 Anthropic에는 모델 호출만 전송됩니다. Managed Agents를 사용하면 Anthropic이 루프를 실행하고 도구가 실행되는 샌드박스를 호스팅하므로 서버에서 실행되는 비중이 줄어듭니다. 자신의 머신에서 실행되는 에이전트를 원한다면 앞의 두 가지 방법 중 하나를 선택하십시오.

Claude API와 Claude Agent SDK의 차이점은 무엇입니까?

Claude API는 원시 Messages 엔드포인트입니다. 대화 내용과 도구를 전송하고 그 주변에 에이전트 루프를 직접 작성하거나 SDK의 도구 실행기(tool runner)를 사용하여 구동합니다. Claude Agent SDK는 더 높은 수준의 라이브러리이자 개발을 위해 패키징된 Claude Code로, 완전한 루프와 내장된 파일, 셸, 검색 도구를 제공합니다. 모든 것을 직접 정의하고 싶을 때는 API를 사용하고, 별도의 환경 구축 없이 바로 사용할 수 있는 강력한 에이전트가 필요할 때는 Agent SDK를 사용하십시오.

서버에서 Claude API 키를 안전하게 유지하려면 어떻게 해야 합니까?

키를 코드에 포함하지 말고 서버 측에 보관하십시오. 에이전트를 실행하는 계정만 읽을 수 있는 파일에 저장하고, 서비스 환경 변수로 로드하십시오. 리포지토리에 커밋하거나 브라우저에 노출해서는 안 됩니다. Claude로 향하는 모든 요청은 서버에서 발생하므로 키가 사용자의 기기로 전달될 필요가 없습니다. 이것이 클라이언트 앱에 내장된 에이전트보다 서버에서 실행되는 에이전트를 보호하기가 더 쉬운 이유입니다.

Claude로 에이전트를 구축하려면 모델을 직접 호스팅해야 합니까?

아닙니다. Claude는 API를 통해 호출하는 호스팅 서비스이므로 GPU에서 실행할 것이 없습니다. VPS는 에이전트 루프, 도구, 데이터를 실행하고 추론은 Anthropic 측에서 수행합니다. 이것이 사양이 낮은 서버에서도 강력한 에이전트를 실행할 수 있는 이유입니다. 만약 완전히 로컬 모델을 원한다면, 직접 AI 에이전트를 구축하는 방법에 관한 별도의 가이드에서 다루는 자체 호스팅 경로를 확인하십시오.