AI 에이전트 서버 배포 — 세션이 스스로 안 끝나고 기억이 샙니다

직접 만든 AI 에이전트를 서버에 올려 서비스로 돌리려 하면, 웹 API 하나 띄우는 것과 전혀 다르다는 걸 금방 알게 됩니다. 공식 문서가 첫 줄부터 "상태 없는 API를 감싸는 것과 다르다"고 못을 박아요. 세션마다 프로세스가 하나씩 뜨고, 세션은 스스로 끝나지 않으며, 한 통에 여러 손님을 받으면 기억이 섞입니다. 올리기 전에 정해야 할 것들만 골라 정리했습니다.

📌 30초 요약

• ★★세션이 스스로 안 끝납니다 — 차례 수 상한을 직접 걸어야 합니다.
• ★한 세션에 프로세스 하나씩 뜹니다 — 메모리가 곧 정원입니다.
• ★기본은 전부 같은 작업 폴더를 물려받습니다.
• ⚠️ 자동 기억은 설정을 비워도 그대로 들어옵니다.
• 토큰 값이 서버 값을 자릿수로 앞섭니다.
• 재시작하면 로컬 상태 세 가지가 다 사라집니다.

상태 없는 서버가 아닙니다

구조부터 보겠습니다. 내 코드가 에이전트를 부르면 별도의 프로그램이 하나 떠서 입출력으로 대화합니다. 그 프로그램이 셸과 작업 폴더와 대화 기록 파일을 직접 쥐고 있어요. 그러니까 한 세션에 프로세스 하나이고, 동시에 열 개를 받으면 프로세스가 열 개 뜹니다.

여기서 첫 함정. 아무 설정도 안 하면 그 프로세스들이 전부 내 프로그램의 작업 폴더를 그대로 물려받습니다. 세션끼리 같은 자리에서 파일을 만들고 지우게 되는 거죠. 세션마다 파일이 갈라져야 한다면 부를 때마다 작업 폴더를 따로 지정해야 합니다. 문서가 여러 에이전트를 한 통에 넣는 구성에서도 같은 주의를 반복해요.

⚠️ 재시작하면 사라지는 것 세 가지

기본값으로 두면 대화 기록, 기억 파일, 작업 폴더에 만든 결과물 — 이 셋이 전부 그 통의 디스크에 있습니다. 그래서 다시 뜨거나, 줄어들거나, 다른 기계로 옮겨가면 전부 없어집니다. 대화 기록은 공용 저장소에 거울을 두는 방법이 따로 있지만, 기억 파일과 작업 폴더 산출물은 거기 안 실립니다 — 볼륨을 붙이거나 따로 동기화해야 해요. 특히 쉴 때 내렸다가 돌아오면 다시 띄우는 방식은 저장소가 선택이 아니라 필수입니다. 없이 내리면 그대로 날아갑니다.

스스로 끝나지 않습니다

알려진 한계 표의 첫 줄이 이겁니다. 세션 전체에 걸리는 시간 제한이 아예 없습니다. 그냥 두면 안 끝나요. 멈추게 하려면 "도구를 몇 번까지 쓰고 그만"이라는 차례 수 상한을 직접 걸어야 합니다. 곁가지 작업도 마찬가지라 각각에 상한을 따로 줘야 하고요.

뒤로 돌려놓은 곁가지에는 "출력이 멎으면 깨우는 감시 장치"를 걸 수 있는데, 문서가 분명히 선을 긋습니다 — 그건 멈춤을 감지하는 것이지 총 실행 시간을 자르는 게 아닙니다. 그리고 세션이 길어질수록 메모리가 자라니 길이를 제한하거나 주기적으로 프로세스를 갈아 끼우라고 권합니다. 한 스크립트로 여러 에이전트를 펼치는 방식이라면 하나 더 — 한 번에 너무 넓게 펼치면 호출 한도에 걸립니다. 작게 나눠 돌리라는 게 문서의 처방이에요.

한 통에 여러 손님을 받으면 샙니다

비용을 아끼려고 한 통에서 여러 사용자의 세션을 돌리는 순간 생기는 문제입니다. 에이전트는 기본적으로 설정과 기억 파일을 파일 시스템에서 읽어들이는데, 공유된 통에서는 한 손님의 맥락이 다른 손님 세션으로 흘러들 수 있습니다.

막을 것	어떻게
설정 파일이 딸려 들어옴	설정 출처를 빈 목록으로 넘겨 아예 안 읽게
자동 기억	위를 비워도 그대로 들어옵니다 — 환경 값으로 따로 꺼야
전역 설정 공유	손님마다 설정 폴더를 따로
파일이 서로 섞임	부를 때마다 작업 폴더를 명시

둘째 줄이 진짜 함정입니다. 설정 출처를 비웠으니 안전하겠지 싶지만, 자동으로 쌓이는 기억은 그와 무관하게 지시문에 실려 들어옵니다. 별도 환경 값으로 꺼야 해요. 그리고 나가는 길도 손님별로 갈라두라고 합니다 — 나가는 주소나 자격, 허용 목록을 손님마다 다르게 해서, 한 손님이 뚫려도 다른 손님의 통로로 자료를 빼내지 못하게 하는 거죠.

인증 배치도 원칙이 분명합니다. 들어오는 요청의 인증은 앞단 관문에서 끝내고, 에이전트는 이미 확인된 요청만 받으라는 것 — 에이전트가 사용자 표를 검증하는 부품이 되면 안 됩니다. 반대로 도구가 밖으로 나갈 때 쓰는 자격은 에이전트 환경에 두지 말고, 요청이 통을 떠난 뒤 중계에서 끼워 넣으라고 합니다.

한 대에 몇 개나 올릴 수 있나

세션마다 프로세스가 뜨니 정원은 메모리가 정합니다. 계산은 단순해요 — 기계 전체 메모리에서 여유분을 뺀 값을, 세션 하나가 최대로 쓰는 양으로 나누면 그게 정원입니다. 문서가 시작점으로 제시하는 값이 있긴 한데, 그건 바닥이지 천장이 아니라고 분명히 적어요. 실제로 쓸 길이만큼 대표 세션을 한 번 돌려 최고치를 재보라는 게 권고입니다.

✅ 세션을 같은 통에 붙들어 둬야 합니다

통을 여러 대로 늘릴 때 그냥 앞에 분배기만 두면 안 됩니다. 세션 번호를 기준으로 같은 통에 계속 붙여줘야 해요. 그래야 이미 떠 있는 그 프로세스로 다시 닿습니다. 안 그러면 엉뚱한 통으로 가서 이어지지 않는 대화가 됩니다. 미리 프로세스를 데워두는 기능도 있으니, 트래픽이 몰리기 전에 띄워두면 첫 응답이 빨라집니다. 웹 앱을 무료로 올려보던 흐름과 달리, 에이전트는 어느 통에 붙느냐가 결과를 바꿉니다.

비용 감각도 짚고 갑니다. 문서는 토큰 값이 서버 값을 자릿수 단위로 앞선다고 말해요. 최소로 잡은 통 한 대의 시간당 비용은 동전 몇 개 수준인데, 긴 세션 하나가 쓰는 토큰은 그보다 훨씬 큽니다. 그러니 서버를 아끼려다 세션을 길게 끌면 오히려 손해예요. 아낄 곳은 서버가 아니라 대화 길이입니다.

자주 묻는 질문 (FAQ)

Q. 어떤 방식으로 올리는 게 좋나요?

문서가 네 갈래로 정리합니다. 일 하나 하고 통째로 버리는 방식(버그 수정·문서 번역 같은 단발 작업), 계속 띄워두는 방식(메일 정리·챗봇처럼 끊임없이 오는 일), 쉴 땐 내렸다 돌아오면 다시 띄우는 방식, 그리고 여러 에이전트를 한 통에 넣는 방식. 어디에 올릴지는 그다음 문제라고 선을 긋습니다.

Q. 인프라를 직접 굴리기 싫으면요?

문서가 첫머리에 대안을 하나 제시합니다 — 에이전트와 격리 공간을 대신 운영해 주는 서비스를 쓰면 내 쪽엔 굴릴 인프라가 없습니다. 격리 방식을 직접 정하거나 데이터가 내 망 안에 있어야 하는 경우가 아니라면 그쪽을 보라고 권해요.

Q. 내 컴퓨터에선 되는데 서버에선 실행 파일을 못 찾습니다.

가장 흔한 배포 실패입니다. 서비스가 내 터미널과 다른 경로 설정으로 프로그램을 돌려서 안 보이는 경우, 이미지를 만들 때 선택 항목이 빠진 경우, 또는 아키텍처가 안 맞거나 실행 권한이 사라진 경우로 갈립니다. 실행 파일은 패키지 판에 묶여 있어서, 올리려면 패키지를 올려야 합니다.

Q. 안에서 무슨 일이 벌어지는지 보려면?

표준 관측 규격을 환경에서 그대로 물려받습니다. 통이나 관리 도구 단에 값을 걸어두면 모든 호출이 수집기로 나가요. 다만 프롬프트 본문과 도구 입력은 기본적으로 안 실립니다 — 필요하면 따로 켜야 합니다.

✨ 정리하면

에이전트 호스팅의 어려움은 전부 "오래 사는 프로세스가 로컬 상태를 쥐고 있다"는 한 문장에서 나옵니다. 그래서 차례 수 상한을 반드시 걸고, 세션마다 폴더를 갈라주고, 자동 기억은 따로 끄고, 세션은 같은 통에 붙들어 두세요. 그리고 아낄 곳은 서버가 아니라 대화 길이입니다. 비용과 권한 설계는 AI 지출 관리 허브에 단계별로 정리해 두었습니다.

출처: Claude Agent SDK 공식 문서 「에이전트 SDK 호스팅」 (2026-08-31 열람). 권장 자원 값과 일부 동작은 SDK 버전에 따라 다르며, 세부 절차는 변경될 수 있습니다.