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

Claude를 사용하여 에이전트를 구축한다는 의미

Claude를 사용하여 에이전트를 구축한다는 것은 Claude를 추론 코어로 사용하고, 루프, 도구 및 데이터는 사용자 자신의 서버에서 실행하는 것을 의미합니다. Claude는 수행할 작업을 결정하며, VPS는 이를 실행합니다. 사용자가 Claude에 작업과 현재 상태를 보내면, Claude는 답변을 하거나 도구 사용 요청을 보냅니다. 사용자의 코드가 해당 도구를 실행하고 결과를 다시 보내면, 작업이 완료될 때까지 루프가 계속됩니다. 지능은 인터넷을 통해 호출하는 서비스이며, 그 외의 모든 요소는 사용자의 소유입니다.

이러한 분리 구조가 핵심입니다. 모델을 직접 운영하지 않고도 최첨단 추론 능력을 얻을 수 있으며, 도구가 사용자의 하드웨어에서 실행되므로 에이전트가 접근할 수 있는 범위에 대해 완전한 제어권을 유지할 수 있습니다. 이미 첫 번째 Claude 프로그램을 구축했다면, VPS에서 첫 Claude 앱을 구축하는 가이드에서 이 가이드의 기반이 되는 기초 내용을 다룹니다.

Claude는 두뇌입니다: Messages API

Claude에 대한 모든 호출은 하나의 엔드포인트인 Messages API를 통해 이루어집니다. 사용자가 지금까지의 대화 내용과 에이전트가 사용할 수 있는 도구 목록을 보내면, Claude는 다음 메시지를 응답합니다. 이 메시지는 최종 답변이거나 도구 호출 요청입니다. 직접 구축하는 방식에는 별도의 "agent API"가 없습니다. 도구 사용은 이 단일 엔드포인트의 기능이며, 이를 둘러싼 루프는 사용자가 직접 실행해야 합니다.

Claude는 호출 간에 상태를 유지하지 않으므로, 자체적으로는 아무것도 기억하지 않습니다. 각 요청에는 전체 대화 내용이 포함되어야 합니다. 사용자의 코드가 히스토리를 보유하고 매 턴마다 이를 전송해야 하므로, 긴 세션의 각 턴에서 이전보다 더 많은 토큰이 소모되는 이유가 발생합니다. 이는 제한이라기보다 설계 방식의 선택입니다. 상태가 사용자의 서버에 저장되므로, Claude가 무엇을 볼지 정확히 결정할 수 있으며, 작업에 관한 어떠한 정보도 사용자가 제어하지 못하는 곳에 저장되지 않습니다.

도구 사용은 에이전트 루프입니다

Claude를 이용한 에이전트 루프는 설명하기 간단합니다. 도구가 포함된 요청을 보냅니다. Claude는 작업을 읽고, 실행이 필요하면 도구 이름과 입력값을 채운 도구 사용 요청을 보냅니다. 사용자의 코드가 해당 도구를 실행한 다음, 다음 요청에서 결과를 Claude에 다시 보냅니다. Claude는 결과를 읽고 다른 도구를 요청하거나 최종 답변을 작성합니다. 도구 요청이 중단되면 작업이 완료된 것입니다.

이 루프는 몇 줄의 코드로 직접 작성할 수 있으며, 구조가 명확하고 제어가 쉬워 많은 사람들이 이 방식을 사용합니다. 공식 SDK는 루프를 대신 실행해 주는 도구 러너(tool runner)도 제공합니다. 사용자가 도구 함수를 제공하면, SDK가 Claude 호출, 도구 실행, 결과 피드백 과정을 자동으로 처리합니다. 어떤 방식을 선택하든 구조는 동일합니다. 러너는 루프를 직접 작성해야 하는 수고를 덜어줄 뿐입니다.

세 가지 구축 방식과 VPS 적합성

Claude 에이전트를 구축하는 방법에는 세 가지가 있으며, 실행해야 하는 구성 요소의 양에 따라 차이가 있습니다.

첫 번째는 사용자 자신의 코드로 도구와 함께 Claude API를 호출하는 방식입니다. 루프를 직접 작성하거나 SDK의 도구 러너를 사용하며, 전체 시스템을 VPS에 호스팅합니다. 이는 도구, 데이터 및 보안에 대해 완전한 제어권을 제공하고 서버에서 일반 프로그램처럼 실행되므로 가장 일반적인 선택입니다. 이 가이드의 대부분은 이 방식을 전제로 합니다.

두 번째는 Claude Agent SDK를 사용하는 방식입니다. 이는 코딩 에이전트인 Claude Code를 라이브러리 형태로 패키징한 것입니다. 파일 읽기/쓰기, 쉘 명령 실행, 검색을 위한 전체 에이전트 루프와 내장 도구를 제공하므로, 이러한 기능을 처음부터 직접 조립할 필요가 없습니다. 이 방식 역시 사용자 자신의 서버에서 실행되므로, 직접 프레임워크를 구축하지 않고도 강력한 파일 및 쉘 에이전트를 원하는 경우 VPS에 매우 적합합니다. 파일을 읽고 쉘 명령을 실행하는 에이전트는 자동 실행을 위해 격리 환경이 필요하며, 서버에서 Claude Code를 안전하게 실행하는 방법에서 권한 시스템, 샌드박스 및 격리 옵션을 다룹니다.

세 번째는 Managed Agents입니다. Anthropic이 루프를 실행하고 에이전트의 도구가 실행될 샌드박스를 호스팅합니다. 이는 관리가 필요 없는 옵션입니다. 사용자가 운영해야 할 요소는 훨씬 적지만, 에이전트의 작업 공간은 사용자의 VPS가 아닌 Anthropic의 인프라에서 실행됩니다. 운영 부담을 최소화하고 싶고 도구가 사용자 기기에서 실행될 필요가 없는 경우 이 방식을 선택하십시오. 나머지 두 방식은 사용자의 서버가 에이전트의 거점이 되며, 이 가이드는 그 내용을 다룹니다.

MCP를 통한 도구 연결

어떤 방식을 선택하든 에이전트를 실제 시스템에 연결해야 하며, Model Context Protocol(MCP)은 이를 수행하는 깔끔한 방법입니다. 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에서는 터미널에서 수동으로 시작한 프로그램이 아니라, 강화된 시스템 서비스(system service)로 에이전트를 실행함으로써 이 두 가지를 모두 충족할 수 있습니다. 서비스로 실행하면 부팅 시 시작되고, 충돌 시 재시작되며, journal에 로그를 남깁니다. 보안이 강화된 서비스는 필요한 권한만 가진 비특권 사용자(unprivileged user)로 실행되므로, 버그나 잘못된 명령의 영향 범위를 제한할 수 있습니다.

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

그 다음 서버 자체를 마무리하십시오. VPS SSH 강화하기와 같이 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의 도구 러너를 사용하여 실행합니다. Claude Agent SDK는 상위 수준의 라이브러리로, 구축을 위해 패키징된 Claude Code입니다. 이는 전체 루프와 파일, 쉘, 검색을 위한 내장 도구를 제공합니다. 모든 것을 직접 정의하려면 API를 사용하고, 프레임워크를 직접 조립하지 않고 유능한 에이전트를 원하면 Agent SDK를 사용하십시오.

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

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

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

아니요. Claude의 경우 모델은 API를 통해 호출하는 호스팅 서비스이므로 GPU에서 실행할 것이 없습니다. 사용자의 VPS는 에이전트 루프, 도구 및 데이터를 실행하며, 추론은 Anthropic 측에서 수행됩니다. 이 덕분에 사양이 낮은 서버에서도 유능한 에이전트를 실행할 수 있습니다. 대신 완전히 로컬 모델을 사용하고 싶다면, 자신만의 AI 에이전트 구축에 관한 가이드에서 다루는 셀프 호스팅 방식을 사용하십시오.