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를 라이브러리 형태로 패키징하여 그 위에서 빌드할 수 있게 한 것입니다. 이 SDK는 완전한 에이전트 루프와 파일 읽기/쓰기, 셸 명령 실행, 검색을 위한 내장 도구를 제공하므로 처음부터 모든 것을 조립할 필요가 없습니다. 이 역시 사용자의 서버에서 실행되므로, 직접 하네스를 구축하지 않고도 강력한 파일 및 셸 제어 기능을 갖춘 에이전트가 필요한 VPS 환경에 매우 적합합니다. 파일 읽기와 셸 명령 실행이 가능한 에이전트는 무인 상태로 작동하기 전에 격리 조치가 필요하며, 서버에서 Claude Code를 안전하게 실행하는 방법에서 권한 시스템, 샌드박스, 격리 옵션을 다룹니다.

세 번째는 Managed Agents 방식으로, Anthropic이 에이전트 루프를 직접 운영합니다. 기본적으로 에이전트의 도구는 Anthropic이 호스팅하는 샌드박스에서 실행되므로, 에이전트의 작업 공간은 사용자의 VPS가 아닌 Anthropic의 인프라에 위치합니다. 2026년 10월 11일 기준으로 베타 상태인 자체 호스팅 샌드박스 옵션을 사용하면, 루프는 Anthropic 측에 유지되면서도 사용자의 서버에서 워커 프로세스가 도구 호출을 수행하도록 할 수 있습니다. 운영 부담을 최소화하고 루프 자체를 자신의 머신에서 실행할 필요가 없을 때 Managed Agents를 선택하십시오. 나머지 두 방식은 서버가 에이전트 전체의 거점이 되며, 이 가이드의 나머지 부분은 이를 중심으로 설명합니다.

MCP를 사용한 도구 연결

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

모델 선택하기

Claude는 여러 모델로 제공되며, 모델 선택은 성능, 속도, 비용 사이의 균형을 고려해야 합니다. 2026년 10월 11일 기준으로 현재 라인업은 다음과 같습니다. Anthropic이 대부분의 워크로드와 장기 실행 에이전트 코딩 및 지식 작업의 시작점으로 권장하는 Claude Opus 5.5 (claude-opus-5-5), 더 저렴하고 빠른 균형 잡힌 옵션인 Claude Sonnet 5.5 (claude-sonnet-5-5), 그리고 단순하고 대량의 작업 단계에 적합한 가장 빠르고 저렴한 Claude Haiku 5.5 (claude-haiku-5-5)가 있습니다. 이들 상위에는 까다로운 추론과 장기적인 에이전트 작업을 위해 모든 고객에게 공개된 가장 뛰어난 모델인 Claude Fable 5.1 (claude-fable-5-1)이 있습니다. Claude Opus 4.8 및 Claude Fable 5와 같은 이전 모델도 여전히 사용할 수 있지만, 현재는 레거시로 분류됩니다. 코드에는 날짜를 추가하지 말고 정확한 모델 식별자를 사용하십시오.

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

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

에이전트는 계속 실행되어야 유용하며, 격리되어야 안전합니다. VPS 환경에서 이 두 가지 조건은 에이전트를 터미널에서 직접 실행하는 대신 강화된 시스템 서비스로 등록하여 충족할 수 있습니다. 서비스로 등록하면 부팅 시 자동으로 시작되고, 충돌 시 재시작되며, 로그가 저널에 기록됩니다. 강화된 환경에서는 최소한의 권한만 가진 일반 사용자 계정으로 실행되므로, 버그나 잘못된 명령이 발생해도 피해 범위가 제한됩니다. 서비스 유닛은 프로세스가 접근할 수 있는 범위와 메모리, CPU, 태스크 사용량을 제한할 수 있습니다. 하지만 에이전트가 부여된 권한 내에서 수행하는 작업 자체를 판단할 수는 없으므로, 나머지 보안은 에이전트 하네스(harness)의 몫입니다. 설치할 가치가 있는 DeepSeek 하네스 플러그인은 비용 제한, 도구별 권한 규칙, 프롬프트 인젝션 스캔과 같은 기능을 다른 스택에서 수행합니다.

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

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

터미널 기반의 코딩 어시스턴트를 원하신다면 VPS에서 코딩 AI 에이전트 실행하기에서 Aider와 Goose에 대해 다룹니다.

FAQ

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

대부분의 작업 부하에 Anthropic이 권장하는 Claude Opus 5.5 (claude-opus-5-5)로 시작한 뒤 필요에 따라 조정하십시오. Claude Sonnet 5.5 (claude-sonnet-5-5)는 대부분의 작업에서 더 저렴하고 빠르며, Claude Haiku 5.5 (claude-haiku-5-5)는 단순하고 대량의 단계를 처리하는 데 가장 적합합니다. Claude Fable 5.1 (claude-fable-5-1)은 가장 어려운 작업에 최적화된 모델입니다. 모델 전환은 코드 한 줄 수정으로 가능하므로, 일상적인 단계에는 저렴한 모델을 사용하고 중요한 결정이 필요한 단계에는 강력한 모델을 사용하는 방식이 일반적입니다.

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

접근 방식에 따라 다릅니다. Claude API를 사용하여 직접 루프를 작성하거나 Claude Agent SDK를 사용하면 에이전트는 전적으로 VPS에서 실행되며 Anthropic으로는 모델 호출만 전송됩니다. Managed Agents를 사용하면 Anthropic이 루프를 실행하고 기본적으로 도구가 실행되는 샌드박스를 호스팅하므로 서버에서 차지하는 비중이 줄어듭니다. 2026년 10월 11일 기준으로 베타 버전인 self-hosted sandbox 옵션을 사용하면 루프는 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 에이전트 구축하기 가이드에서 다루는 self-hosted 경로를 확인하십시오.