클로드 에이전트 SDK 한도 — 같은 0인데 무제한과 시작 거부

에이전트를 직접 만들어 돌릴 때 가장 먼저 걱정되는 게 「어디까지 가다 멈추게 할까」입니다. 무한정 도는 걸 막으려고 상한을 거는데, 막상 걸어 두고 나면 걸린 다음에 무슨 일이 벌어지는지가 더 중요해집니다.

상한은 두 가지고 성질이 제법 다릅니다. 게다가 같은 0을 넣어도 결과가 정반대고, 상한에 닿은 뒤 세션이 살아남는지도 입력 방식에 따라 갈립니다. 새로 정리된 설정 문서를 펴 놓고 걸리기 전과 걸린 뒤를 나눠 보겠습니다.

📌 30초 요약

• 상한은 차례 수와 지출 둘이고 기본은 둘 다 꺼짐입니다.
• 차례에 0은 무제한, 예산에 0은 시작 거부입니다.
• 단발 호출은 예외를 던지고 흐름 입력은 살아남습니다.
• 도중에 설정을 바꾸는 건 흐름 입력에서만 됩니다.

1. 상한 두 가지와 걸렸을 때

걸 수 있는 상한은 차례 수와 지출 금액 둘입니다. 둘 다 따로 지정하지 않으면 꺼진 상태라서, 아무것도 안 걸면 한도 없이 돕니다. 자동화에 올릴 때 이 기본값을 모르고 지나가면 밤새 도는 상황이 생길 수 있으니, 처음 붙일 때 둘 중 하나는 반드시 걸어 두시는 편이 안전합니다.

상한에 닿으면 세션이 그냥 죽는 게 아니라 결과 메시지를 하나 내놓고 끝납니다. 그 메시지에는 어느 상한에 걸렸는지가 하위 종류로 적혀 있어서, 차례를 다 쓴 건지 돈을 다 쓴 건지 코드에서 구분할 수 있습니다. 로그만 보고 「왜 멈췄지」 헤매지 않아도 된다는 뜻이라, 자동화에서는 이 값으로 분기를 나눠 두면 편합니다.

상한	성질
차례 수	흐름 입력에서는 대기 메시지마다 다시 0부터 셈
지출 금액	메시지를 넘어 계속 누적 — 대화를 비워야 초기화
기본값	둘 다 꺼짐 — 안 걸면 제한 없이 돎

참고로 이번에 새로 정리된 이 문서는 옵션 하나하나가 어느 기능에 딸린 것인지 짝지어 주는 지도 역할도 합니다. 권한·도구 허용·시스템 지침·설정 출처·외부 도구 서버·하위 에이전트·훅·스킬·플러그인·구조화된 출력·세션 이어가기와 갈래·외부 저장·되돌릴 수 있는 편집·노력 수준·격리 상자까지 각각 어느 문서를 봐야 하는지 표로 묶여 있습니다. 「무엇을 하고 싶은지는 알겠는데 어느 옵션인지 모르겠다」 할 때 먼저 열어 볼 자리가 생긴 셈입니다.

표의 앞 두 줄이 실무에서 크게 갈리는 지점입니다. 차례 수는 메시지 단위로 초기화되니 열 번을 걸어 뒀다면 메시지마다 열 번씩 쓸 수 있습니다. 반면 지출은 대화 전체에 걸쳐 쌓입니다. 그래서 긴 대화를 돌리다 보면 차례는 여유로운데 예산만 먼저 바닥나는 일이 흔합니다. 요금 상한을 어디에 어떻게 걸어야 하는지는 에이전트 요금 상한의 함정에 따로 정리해 뒀습니다.

2. 0의 의미가 정반대입니다

⚠️ 같은 0인데 하나는 무제한, 하나는 시작 거부입니다

두 상한에 0을 넣으면 결과가 정반대입니다. 차례 수에 0을 주면 제한 없이 돕니다 — 아예 지정하지 않은 것과 같은 상태죠. 반면 예산에 0을 주면 시작할 때 잘못된 금액으로 거부당하고 세션이 아예 실행되지 않습니다. 「0이면 안 쓰겠다는 뜻이겠지」 하고 둘 다 0으로 맞춰 두면, 한쪽은 무한정 돌고 다른 쪽은 시작조차 안 되는 기묘한 조합이 됩니다. 끄고 싶으면 0이 아니라 아예 지정하지 마세요.

왜 이렇게 갈렸을까 짐작해 보면, 차례 수의 0은 「셀 필요 없음」으로 읽히고 금액의 0은 「돈을 한 푼도 안 쓰겠다」로 읽히기 때문인 듯합니다. 후자는 실행 자체가 불가능한 요구라 시작 단계에서 막는 게 맞고요. 다만 설정 파일이나 환경 변수에서 값을 읽어 넘기는 구조라면 빈 값이 0으로 변환되는 사고가 나기 쉬우니, 값을 넘기기 전에 한 번 확인하는 코드를 두시는 게 좋습니다.

지출 상한을 다시 0부터 세고 싶을 때도 방법이 있습니다. 대화를 비우는 명령을 쓰면 예산이 처음부터 다시 시작됩니다. 긴 자동화를 돌리면서 구간마다 예산을 나눠 쓰고 싶다면 이 성질을 이용할 수 있죠. 다만 대화를 비우면 그때까지의 맥락도 함께 사라지니, 예산을 초기화하려고 문맥을 버리는 셈이 된다는 점은 감안하셔야 합니다.

3. 입력 방식이 뒷일을 가릅니다

상한에 걸린 뒤가 더 중요하다고 했는데, 여기서 입력을 어떻게 넣었느냐가 결정적입니다. 한 번에 던지고 결과를 받는 단발 호출이라면 상한 결과를 내준 뒤 예외를 던집니다. 그래서 그 뒤로도 계속 돌리려면 반복문을 예외 처리로 감싸 둬야 합니다. 감싸지 않으면 상한에 닿는 순간 자동화 전체가 멈춰 버리죠.

반면 흐름 입력으로 세션을 열어 뒀다면 이야기가 다릅니다. 상한 결과가 나온 뒤에도 세션이 살아 있습니다. 차례 수는 다음 메시지부터 다시 세니 계속 대화할 수 있고요. 다만 예산은 앞서 봤듯 누적되기 때문에, 한 번 예산 상한에 닿으면 같은 대화의 이후 메시지가 전부 같은 예산 결과로 끝납니다. 세션은 살아 있는데 아무것도 못 하는 상태가 되는 겁니다.

정리하면 단발 호출은 예외 처리가 필수고, 흐름 입력은 예산이 바닥났는지 결과 메시지로 확인하는 절차가 필수입니다. 둘 중 어느 쪽이든 「멈추면 알아서 알려 주겠지」 하고 두면 조용히 헛도는 구간이 생깁니다. 두 방식의 차이 전반은 이 축에서 계속 문제가 되는 지점이라, 에이전트를 새로 붙이신다면 SDK 새 방식 정리도 함께 보시길 권합니다.

4. 세션 중간에 바꾸기

돌아가는 중에 설정을 바꾸고 싶을 때가 있습니다. 앞 차례는 싸게 처리하고 다음 차례만 센 모델로 돌린다든가 하는 식이죠. 이것도 흐름 입력으로 시작한 세션에서만 됩니다. 바꿀 수 있는 건 모델과 권한 모드 두 가지고요. 단발 호출로 열었다면 세션 도중에 손댈 방법이 없으니, 중간 변경이 필요할 것 같으면 처음부터 흐름 입력으로 여셔야 합니다.

바꾸는 것	알아 둘 점
모델	인자 없이 부르면 처음 넘긴 모델이 아니라 기본 모델로
권한 모드	같은 방식으로 도중에 전환 가능
설정 쓰기	허용된 키만 파일에 기록 — 이후 세션에도 남음

표의 첫 줄이 함정입니다. 모델 설정자를 인자 없이 부르면 원래대로 돌아가는 게 아니라, 클로드 코드의 기본 모델로 바뀝니다. 처음에 옵션으로 넘긴 모델로 복귀할 거라 기대하기 쉬운데 그렇지 않다는 뜻이죠. 되돌리려면 원래 모델 이름을 명시해서 다시 불러야 합니다. 부르는 위치도 언어마다 다른데, 한쪽은 질의가 돌려준 객체의 메서드고 다른 쪽은 전용 클라이언트의 메서드입니다.

한 언어에는 두 가지가 더 있습니다. 실행 중에 설정을 적용하는 메서드는 옵션 필드가 아니라 설정 파일 키를 받는다는 점이 특이합니다. 그래서 어떤 키가 세션 도중에 실제로 먹는지는 따로 확인해야 하고요. 다른 하나는 설정을 파일에 써 두는 메서드인데, 허용된 키만 기록되고 다음 요청부터 적용되며 이후 세션에도 남습니다. 한 번 쓰면 계속 따라다니니 신중하게 쓰셔야 합니다.

마지막으로 순서 문제가 하나 있습니다. 문서의 예제는 두 번째 메시지를 설정자가 다 돌 때까지 붙들어 둡니다. 흐름 입력은 메시지를 계속 흘려보내는 구조라, 설정을 바꾸는 사이에 다음 메시지가 먼저 나가 버리면 바뀌기 전 설정으로 처리되기 때문입니다. 중간 변경을 쓰신다면 이 대기 장치를 함께 짜 두세요. 어떤 설정이 어디서 읽히는지는 SDK 설정 불러오기에, 도입 순서는 AI 도입 한 바퀴에서 잡아 보세요.

자주 묻는 질문 (FAQ)

Q. 상한을 끄려면 0을 넣으면 되나요?

둘의 결과가 다릅니다. 차례 수에 0은 제한 없음이라 끄는 것과 같지만, 예산에 0은 시작 거부라 세션이 아예 안 돕니다. 끄고 싶으면 0을 넣지 마시고 아예 지정하지 않는 편이 안전합니다. 설정 파일이나 환경 변수에서 값을 읽어 넘기는 구조라면 빈 값이 0으로 바뀌지 않는지 확인하세요.

Q. 상한에 걸렸는데 자동화가 통째로 멈췄습니다

단발 호출로 돌리셨을 가능성이 큽니다. 이 방식은 상한 결과를 내준 뒤 예외를 던지기 때문에 반복문을 예외 처리로 감싸지 않으면 그 자리에서 멈춥니다. 계속 돌려야 한다면 감싸 두시고, 아예 세션을 살려 두고 싶다면 흐름 입력으로 여세요. 흐름 입력은 상한 뒤에도 세션이 유지됩니다.

Q. 세션은 살아 있는데 답이 안 옵니다

예산 상한에 닿았을 가능성이 큽니다. 지출은 메시지를 넘어 계속 누적되기 때문에, 한 번 바닥나면 같은 대화의 이후 메시지가 전부 같은 결과로 끝납니다. 결과 메시지의 하위 종류를 보면 어느 상한인지 알 수 있고요. 다시 쓰려면 대화를 비우면 예산이 처음부터 시작되지만 그때까지의 맥락도 함께 사라집니다.

Q. 모델을 원래대로 돌리고 싶습니다

설정자를 인자 없이 부르면 처음 넘긴 모델이 아니라 기본 모델로 갑니다. 원래 모델로 되돌리려면 이름을 명시해서 다시 불러야 합니다. 그리고 중간 변경 자체가 흐름 입력에서만 되니, 단발 호출로 열었다면 방법이 없습니다. 바꾼 뒤 다음 메시지가 먼저 나가지 않도록 대기 장치를 두는 것도 잊지 마세요.

정리하면

• 상한은 둘 다 기본 꺼짐입니다.
• 차례의 0은 무제한, 예산의 0은 시작 거부입니다.
• 차례는 메시지마다 초기화, 지출은 누적입니다.
• 단발 호출은 예외 처리가 필수입니다.
• 모델 설정자를 빈손으로 부르면 기본 모델로 갑니다.

※ 공개된 에이전트 설정 문서를 읽고 정리했습니다. 옵션과 메서드 이름은 우리말로 풀어 적었으니 실제 입력값과 언어별 표기는 원문에서 확인하세요.

※ 이 문서는 최근 새로 정리된 것이라 이후 판올림에서 옵션 이름이나 동작이 달라질 수 있습니다. 중간 변경이 가능한 설정 키 목록도 따로 명시돼 있으니, 자동화에 넣기 전에 원문과 대조해 확인하세요.