Claude 도구 호출 에이전트: 직접 루프 vs Agent SDK

Claude 도구 호출 사이트 점검 에이전트는 직접 루프와 Agent SDK 중 무엇이 맞을까요? URL·상태 코드 수준이면 직접 루프, 파일·셸·권한이 필요하면 SDK입니다.

조회 30
Claude 도구 호출 에이전트: 직접 루프 vs Agent SDK

핵심 요약

  • URL·상태 코드 점검은 직접 루프, 파일·셸·권한 필요 시 Agent SDK
  • 실패 지점: 도구 오류, 결과 크기, 판단 일관성, 권한 범위
  • 비용은 대화 누적으로 가파르게 증가하니 대화 분리와 캐싱을 검토

Claude 도구 호출로 사이트 점검 에이전트를 만들 때 직접 루프를 짤지 Agent SDK를 쓸지는 이렇게 정하면 됩니다. 점검 대상이 URL 몇 개와 상태 코드 정도라면 직접 루프가 가볍고 비용을 예측하기 쉽습니다. 파일 읽기, 셸 실행, 권한 관리까지 필요하면 Agent SDK가 낫습니다. 아래는 두 방식의 구조와 예상되는 실패 지점, 비용 관리 방법입니다. 실측 결과가 아니라 공식 문서를 바탕으로 한 설계 정리입니다.

도구 호출 루프의 구조

Anthropic 도구 사용 문서에 따르면 도구 호출은 모델이 tool_use 블록을 반환하면 클라이언트가 도구를 실행하고, 그 결과를 tool_result로 돌려주는 루프로 동작합니다. 모델은 도구를 직접 실행하지 않습니다. 무엇을 어떤 인자로 호출할지 요청할 뿐이고, 실행은 우리 코드가 합니다. 이 점이 안전장치와 비용 통제를 설계하는 출발점입니다.

사이트 점검 에이전트라면 도구는 fetch_url(상태 코드, 응답 시간, 헤더), check_tls(인증서 만료일), find_broken_links 정도면 시작할 수 있습니다. 루프는 아래처럼 단순합니다.

messages = [{"role": "user", "content": "example.com 점검해줘"}]
for step in range(MAX_STEPS):          # 상한은 필수
    resp = client.messages.create(
        model=MODEL, max_tokens=1024,
        tools=TOOLS, messages=messages)
    messages.append({"role": "assistant", "content": resp.content})
    if resp.stop_reason != "tool_use":
        break
    results = []
    for block in resp.content:
        if block.type == "tool_use":
            out = run_tool(block.name, block.input)  # 예외는 문자열로 변환
            results.append({"type": "tool_result",
                            "tool_use_id": block.id,
                            "content": out[:4000]})  # 길이 제한
    messages.append({"role": "user", "content": results})

MAX_STEPS와 결과 길이 제한(out[:4000])이 이 코드에서 가장 중요한 두 줄입니다. 이유는 아래 실패 지점과 비용 항목에서 다룹니다.

Agent SDK를 쓰면 달라지는 것

Claude Code SDK 문서에 따르면 Agent SDK는 Claude Code와 같은 에이전트 루프를 코드에서 쓸 수 있게 해 줍니다. 루프, 컨텍스트 관리, 내장 도구를 직접 구현하지 않아도 된다는 뜻입니다. 공식 퀵스타트에 안내된 패키지는 TypeScript가 @anthropic-ai/claude-agent-sdk, Python이 claude-agent-sdk입니다. 같은 문서에 따르면 두 SDK 모두 네이티브 Claude Code 바이너리를 번들하므로 대부분 별도 설치가 필요 없습니다.

선택 기준은 다음과 같습니다.

기준 직접 루프 Agent SDK
구현량 루프·도구 실행 직접 작성 루프와 내장 도구 제공
제어 단계마다 개입 가능 SDK 설정(권한 등)에 의존
적합한 점검 HTTP/TLS 같은 좁은 도구 로그·설정 파일까지 읽는 점검
배포 의존성 적음 번들 바이너리 포함

최신 버전 번호는 이 글에 적지 않았습니다. 설치 전에 위 문서에서 직접 확인하세요.

예상되는 실패 지점

첫째는 도구 오류의 처리 방식입니다. 타임아웃이나 DNS 실패로 예외가 나면 루프 전체가 죽기 쉽습니다. 예외를 문자열로 바꿔 tool_result로 돌려주면 모델이 재시도할지, 장애로 보고할지 스스로 판단합니다. 다만 같은 실패 호출을 반복하는 경우가 생길 수 있으니 동일 인자의 반복 호출은 코드에서 끊는 편이 안전합니다.

둘째는 결과 크기입니다. HTML 본문을 통째로 돌려주면 컨텍스트가 빠르게 차고 이후 모든 호출의 입력 토큰이 늘어납니다. 상태 코드, 지연 시간, 필요한 헤더만 요약해서 반환하세요. 셋째는 판단의 일관성입니다. "느리다"의 기준을 프롬프트에 임계값(예: 응답 2초 초과)으로 명시하지 않으면 실행마다 보고 내용이 달라질 수 있습니다. 그래서 수치 판정은 도구 코드에서 하고, 모델은 요약과 우선순위 정리만 맡기는 구성이 안정적입니다.

넷째는 권한입니다. Agent SDK에서 셸이나 파일 쓰기 도구를 열어 두면 점검 에이전트가 점검 범위를 넘어 동작할 수 있습니다. 점검용이라면 읽기 전용 도구만 허용하고, 허용 도구 목록을 명시적으로 좁히는 것을 기본으로 삼으세요.

비용이 늘어나는 구조

가격 수치는 이 글에서 인용하지 않았습니다. 최신 모델별 단가는 공식 가격 페이지에서 확인하세요. 대신 구조는 확실히 말할 수 있습니다. 루프는 매 단계마다 대화 전체를 다시 보내므로, 단계가 늘수록 입력 토큰이 누적됩니다. 도구 정의 자체도 입력 토큰에 포함됩니다. 호출 횟수가 N배가 되면 비용은 N배가 아니라 그보다 가파르게 늘 수 있습니다.

점검 대상이 20개 URL이라면 한 대화에서 20번 호출하는 것보다, URL별로 독립된 짧은 대화로 나누는 편이 컨텍스트 누적을 막습니다. 병렬 호출이 가능하면 한 응답에 여러 tool_use 블록이 담길 수 있으니, 이를 한 번에 처리해 왕복 횟수를 줄이세요. 반복되는 시스템 프롬프트와 도구 정의에는 프롬프트 캐싱을 검토할 만합니다. 적용 조건과 할인율은 공식 문서에서 확인해야 합니다.

실천 가이드

시작 순서를 정리하면 이렇습니다.

  • 도구 2~3개로 직접 루프를 먼저 만든다. 구조를 이해하는 데 가장 빠릅니다.
  • MAX_STEPS, 결과 길이 제한, 같은 호출의 반복 차단을 처음부터 넣는다.
  • 수치 판정은 코드가 하고, 모델은 요약과 우선순위만 맡긴다.
  • 매 실행마다 응답의 토큰 사용량을 기록해 점검 1회당 비용을 직접 계산한다.
  • 파일·셸 접근이 필요해지는 시점에 Agent SDK로 옮기고, 허용 도구는 읽기 전용으로 제한한다.

핵심은 모델이 판단하고 코드가 실행과 한계를 책임지는 분업입니다. 이 경계가 분명하면 실패 원인도 비용도 추적하기 쉬워집니다.

자주 묻는 질문

Q. 사이트 점검 에이전트는 직접 루프와 Agent SDK 중 무엇이 좋나요?

점검 대상이 URL 몇 개와 상태 코드 정도라면 직접 루프가 가볍고 비용을 예측하기 쉽습니다. 파일 읽기, 셸 실행, 권한 관리까지 필요해지면 Agent SDK가 낫습니다.

Q. 직접 루프에서 가장 먼저 넣어야 할 안전장치는 무엇인가요?

MAX_STEPS 상한과 도구 결과 길이 제한이 가장 중요합니다. 여기에 예외를 문자열로 변환해 돌려주고, 동일 인자의 반복 호출을 코드에서 끊는 장치를 처음부터 넣는 편이 안전합니다.

Q. 도구 호출 에이전트의 비용은 왜 빠르게 늘어나나요?

루프는 매 단계마다 대화 전체를 다시 보내므로 단계가 늘수록 입력 토큰이 누적되고, 도구 정의도 입력 토큰에 포함됩니다. URL별로 짧은 대화를 나누고 병렬 호출과 프롬프트 캐싱을 검토하면 줄일 수 있습니다.

참고 자료

이 글은 웹 검색으로 확인한 위 출처를 바탕으로 AI(claude-sonnet-5-5)가 작성했습니다. 수치·가격은 출처 원문에서 다시 확인하세요.

#Agent SDK#AI 에이전트#Claude#도구 호출#사이트 점검#토큰 비용#프롬프트 캐싱