Claude Agent SDK × Sheets 자동화 설계

Anthropic의 Claude Agent SDK는 AI 에이전트를 구축하기 위한 공식 라이브러리로, Python과 TypeScript 모두에서 제공됩니다. 이 기사에서는 Claude Agent SDK와 Google Sheets API를 결합하여 IT 신청 폼의 선택지를 동적으로 업데이트하는 설계 패턴을 정보시스템(情シス) 담당자의 실무 관점에서 정리합니다.

• Google 폼이나 Sheets의 선택지를 매달 수작업으로 업데이트하고 있어, 체계화를 검토 중인 정보시스템 담당자
• Claude API를 사용한 업무 자동화에 관심은 있지만, 어떤 설계 패턴부터 시작해야 할지 고민 중인 분
• GAS(Google Apps Script) 구현이 복잡해져서 설계를 재검토하고 싶은 분

Claude Agent SDK는 Claude를 핵심으로 하는 AI 에이전트를 구축하기 위한 Anthropic 공식 라이브러리입니다. 도구 호출(Tool Calling), 서브 에이전트(Sub-agent), 세션 관리, MCP(Model Context Protocol) 클라이언트 등 다양한 기능을 표준으로 갖추고 있습니다.

일반적인 Claude API 호출은 프롬프트를 보내고 답변을 받는 일문일답 형태입니다. Claude Agent SDK는 그 한 단계 더 나아가, 에이전트가 "어떤 도구를 어떤 순서로 호출할지"를 상황에 따라 동적으로 판단하며 처리를 진행합니다. 예를 들어 "승인된 소프트웨어 목록을 Sheets에서 읽기 → 폼의 선택지 데이터 업데이트 → 신청 내용을 다른 시트에 쓰기 → 승인자에게 통지하기"라는 일련의 처리를, 여러 도구 정의를 바탕으로 에이전트가 자율적으로 구성합니다.

GAS에서도 유사한 처리를 작성할 수 있지만, 분기나 조건이 늘어날수록 if/else 문이 비대해집니다. Claude Agent SDK에서는 "무엇을 해야 할지"를 에이전트가 판단하기 때문에, 처리 흐름을 전부 다 작성하기보다 도구의 정의에 집중할 수 있는 설계가 됩니다. 정보시스템 담당자가 설계해야 할 것은 "처리 순서"가 아니라 "도구의 책임 범위"라는 점이 발상의 전환 포인트입니다.

라이브러리는 Python과 TypeScript 모두에서 제공되며, Google Cloud Functions나 Cloud Run과의 조합으로 서버리스(Serverless) 실행도 가능합니다. GWS 환경에서 어떤 런타임(Runtime)을 선택할지는 기존 인프라나 사내 멤버의 기술 스택에 맞춰 판단합니다. GAS 생태계에 익숙한 팀이라면 TypeScript/Node.js 기반이 학습 비용을 낮추기 쉬운 경우가 있습니다.

Sheets와의 연계는 트리거(Trigger)·도구(Tool)·출력(Output)의 3계층으로 생각하면 정리하기 쉽습니다.

대표적인 패턴은 2가지가 있습니다.

스케줄 실행: 매일 아침 정해진 시간에 Sheets의 마스터 데이터를 참조하여, 폼의 선택지를 자동 업데이트함 -
요청 기반 실행: 신청 폼 전송을 트리거로 하여, Sheets 쓰기와 승인 통지를 일괄 실행함

스케줄 실행은 Google Cloud Scheduler에서 HTTP 요청으로 에이전트를 기동하는 구성이 다루기 쉽습니다. GAS의 시간 기반 트리거에서 에이전트의 API 엔드포인트를 호출하는 구성으로도 동작하지만, GAS의 실행 타임아웃(최대 6분)에 주의해야 합니다. 처리가 길어질 가능성이 있다면 Cloud Scheduler ＋ Cloud Functions 조합이 더 안전합니다. 요청 기반 실행의 경우, Google 폼 전송 시 실행되는 GAS 스크립트에서 엔드포인트를 호출하는 패턴이 일반적입니다.

어느 패턴이든 에이전트의 기동 로직과 처리 로직은 분리하여 관리합니다. 기동 방식이 바뀌더라도(스케줄 변경이나 다른 트리거로의 전환 등), 도구 정의에는 손을 댈 필요가 없으므로 사후 수정이 용이합니다.

도구는 가능한 한 단일 책임(Single Responsibility)으로 정의하는 것이 원칙입니다. 나중에 기능을 추가하거나 변경했을 때의 영향 범위를 한정할 수 있습니다.

아래는 개념적인 도구 정의 구조 예시입니다. 실제 Sheets API 호출 상세 내용은 공식 레퍼런스를 참조하십시오.

# 도구 정의의 개념 예시 (Python)
# 실제 API 호출 상세는 공식 문서를 참조
def get_approved_software_list() -> list[str]:
...

에이전트는 이러한 도구들을 "지금 무엇이 필요한가"라는 문맥(Context)에 기반하여 자율적으로 호출합니다. "〇〇 소프트웨어 신청이 접수되었습니다"라는 입력을 받은 에이전트가, 먼저 get_approved_software_list로 리스트를 확인하여 신청 내용이 목록에 포함되는지 판단한 후, write_request_log로 기록하고, 마지막으로 notify_approver를 통해 알림을 보내는 과정을 자동으로 구성합니다.

GAS(Google Apps Script)에서는 처리 순서를 모두 코드로 작성해야 했지만, SDK에서는 도구(Tool)의 정의만 갖춰져 있다면 에이전트가 스스로 판단합니다. 도구가 세분화되어 있을수록 에이전트는 상황에 맞는 조합을 선택할 수 있습니다. 반면, 도구가 너무 많아지면 에이전트의 판단 비용이 상승하여(처리 시간 증대 및 API 비용 증가) 디버깅도 어려워집니다. 초기 단계에서는 5~7개 정도의 도구로 시작하여 동작을 확인하며 추가해 나가는 것이 현실적입니다.

도구의 실행 결과로 생성되는 대표적인 출력(Output)은 다음과 같습니다.

• Sheets의 특정 셀 범위 업데이트 (폼의 드롭다운 선택지 마스터로 사용)
• 신청 로그 시트에 추가 (누가, 언제, 무엇을 신청했는지에 대한 기록)
• 다른 도구와 조합한 Slack 또는 Gmail 알림
• 에이전트의 실행 로그 (어떤 도구를, 언제, 어떤 데이터로 실행했는지에 대한 기록)

출력 대상이 Sheets에만 국한되지 않는다는 점이 이 설계의 강점입니다. "Sheets의 데이터를 읽고, Slack에 게시하고, 로그를 Sheets에 쓰는" 복합적인 처리도 도구를 조합하는 것만으로 대응할 수 있습니다.

정보시스템(情シス) 부서가 일상적으로 직면하는 신청 폼 관리에 초점을 맞추어, 3가지 유스케이스(Use Case)를 제시합니다.

IT 자산 신청 폼의 선택지 자동 업데이트

정보시스템 부서가 관리하는 단말 마스터 시트(모델명, 재고 수량, 할당 부서 등을 기록)를 데이터 소스로 사용하여, 신청 폼의 "희망 기종" 드롭다운을 정기적으로 자동 업데이트합니다. 재고가 0이 된 기종은 선택지에서 자동으로 제외되며, 신규 기종을 추가하면 폼에 즉시 반영됩니다. 매달 수동으로 폼을 편집하는 작업이 사라지는 것은 소규모 정보시스템 부서에서 특히 체감하기 쉬운 이점입니다.

운영상의 포인트로서, 마스터 시트에 "공개 대상 플래그" 열을 준비해 두면 편리합니다. 재고가 0이더라도 "곧 입고 예정"으로 선택지에 남겨두고 싶은 경우, 플래그를 에이전트가 읽게 하여 노출 여부를 판단하게 할 수 있습니다. 플래그 값만 변경하면 폼의 표시가 바뀌는 설계로 구성하면 정보시스템 부서의 조작 비용이 낮아집니다.

소프트웨어 조달 신청

"승인된 소프트웨어 목록"을 관리하는 Sheets를 읽어 신청 폼의 선택지를 동적으로 생성합니다. 신청이 제출되면 신청자 정보, 신청일, 승인 상황을 "신청 로그" 시트에 자동으로 기록합니다. 승인자는 Sheets를 확인하는 것만으로 처리 대기 건수를 파악할 수 있는 상태가 됩니다.

이 유스케이스에서 특히 중요한 것은 스키마(Schema) 설계입니다. 신청 로그 시트의 열(신청자, 이메일 주소, 신청일, 소프트웨어명, 승인자, 승인일, 상태 등)을 구현 전에 확정하지 않으면, 나중에 에이전트 측의 도구 정의도 변경해야 합니다. 팀 내에서 열 구조를 합의한 후 도구 정의 단계로 들어가는 것이 전제 조건입니다.

외부 벤더 액세스 신청

신청자의 이메일 주소를 받은 에이전트가 사원 마스터 시트를 대조하여 소속 부서, 상사, 입사일을 자동으로 보완한 후 신청 로그에 기록합니다. 수기 입력 실수를 줄이면서, 정보시스템 부서가 나중에 감사하기 쉬운 로그 형식을 유지할 수 있습니다. 외부 벤더에 대한 액세스 권한 부여는 감사 추적(Audit Trail)이 중요하기 때문에, 누가, 언제, 어떤 권한을 신청했는지를 Sheets에 지속적으로 기록하는 설계가 감사 시 근거로서 기능합니다.

Claude Agent SDK에서 Sheets API를 호출할 때는 OAuth 스코프(액세스 권한 범위)를 필요 최소한으로 제한하는 것이 원칙입니다.

판단의 기본은 "도구마다 스코프를 나누어 생각하는 것"입니다.

• 시트를 읽기만 하는 도구라면 읽기 전용(Read-only) 스코프로 충분합니다.
• 시트에 쓰는 도구는 쓰기(Write) 스코프가 필요하지만, 액세스 대상 스프레드시트를 특정 파일로 한정할 수 있는지 사전에 확인합니다.

권한 설계에서 흔히 발생하는 실수는 "일단 넓은 범위의 스코프 (Scope)를 부여하는 것"입니다. Drive 전체에 대한 쓰기 권한을 부여하면, 도구의 버그나 예상치 못한 에이전트 (Agent) 동작이 발생했을 때 의도하지 않은 파일이 덮어씌워질 리스크가 생깁니다. 마스터 시트와 신청 로그 시트만을 서비스 계정 (Service Account)과 공유하는 구성으로 해두면 영향 범위를 명확히 할 수 있습니다.

인증 방식은 에이전트를 자동 실행한다면 서비스 계정이 일반적입니다. 서비스 계정에는 필요한 Sheets 권한만 공유하고, Google Drive 전체에 대한 권한은 부여하지 않는 것을 전제로 합니다.

Claude Agent SDK에서는 에이전트가 실행 시점에 어떤 도구 (Tool)를 호출할지가 동적으로 변합니다. 따라서 "정의된 도구 이외에는 액세스할 수 없는 설계"로 만드는 것이 GAS (Google Apps Script)보다 중요해집니다. 도구와 스코프의 세트를 1 대 1로 관리한다는 이미지로 정리하면, 나중에 권한 리뷰를 하기 쉬워집니다.

더불어 서비스 계정의 인증 정보 (키 파일) 관리에도 주의가 필요합니다. GitHub 리포지토리나 GAS 스크립트 내에 키를 하드코딩하는 것은 금지하며, Google Cloud의 Secret Manager나 환경 변수로 주입하는 설계를 채택합니다. 인증 정보가 유출되었을 경우의 로테이션 (Rotation) 절차도 미리 정해두면 인시던트 대응이 원활해집니다.

실제로 연동을 구성하기 전에 다음 4가지 사항을 정리해 두면 재작업을 줄일 수 있습니다.

1. 마스터 시트의 관리 주체를 결정한다

에이전트가 참조하는 Sheets의 소유자와 업데이트 담당자를 처음에 명확히 합니다. "누구나 편집할 수 있는" 상태는 부정 데이터가 에이전트로 흘러 들어올 리스크 요인입니다. 최소한 편집자와 열람자의 역할을 나누고, 마스터 데이터의 업데이트 권한은 제한해 둡니다. 에이전트가 사용하는 서비스 계정에는 열람 권한만 부여하고, 쓰기 권한은 신청 로그 전용 시트로 한정하는 것이 기본 구성입니다.

2. 스키마 (열 정의)를 먼저 확정한다

에이전트가 읽고 쓰는 시트의 열 구조는 구현 전에 확정합니다. 나중에 열을 추가하거나 이동하면 도구의 로직이 깨지기 때문에, 열 이름과 열 순서를 팀과 합의한 후 연동 설계에 들어가는 것이 전제 조건입니다. 버전 1에서는 최소한의 열만 정의하고, 나중에 열을 추가할 경우에는 도구 정의도 동시에 리뷰하는 규칙을 마련해 두면 안전합니다.

3. 에러 케이스의 동작을 결정한다

대상 Sheets를 일시적으로 가져올 수 없을 때 에이전트가 어떻게 행동할지를 사전에 결정해 둡니다. "에러로 처리하여 신청을 중단할지", "이전의 캐시 값을 사용할지", "기본 선택지로 동작할지" 중 무엇을 선택할지는 업무 요구사항에 따라 다릅니다. 설계 단계에서 에러 시나리오를 작성하고, 에러 발생 시 알림 대상 (정보 시스템 팀으로의 알럿 등)을 포함하여 합의해 두면 구현 시의 사양 흔들림이 줄어듭니다.

4. 에이전트의 조작 로그를 남긴다

에이전트가 무엇을 읽고 무엇을 썼는지에 대한 기록은 나중에 감사 및 디버깅에 필수적입니다. "언제, 어떤 도구를, 어떤 시트에 대해 실행했는지"는 로그로 남기는 설계로 합니다. 기존 GWS (Google Workspace) 인프라에 맞춰 Google Cloud의 로깅 서비스나 Sheets 자체에 로그 탭을 추가하는 것 등을 검토합니다. 에러가 발생했을 때의 트러블슈팅에도 로그가 필수적이므로, 동작 확인 단계부터 기록 메커니즘을 포함해 두는 것이 안전합니다.

GAS와 Claude Agent SDK는 "Sheets를 자동화한다"는 목적에서는 겹치지만, 특기 분야가 다릅니다.

조건	선택 기준
처리 플로우가 고정되어 변하지 않음	GAS
...

"GAS로 작성했더니 if/else 문이 너무 많아져서 유지보수가 힘들다"라는 경험이 있다면, Claude Agent SDK로 도구를 정의하고 에이전트에게 판단을 맡기는 구성을 검토할 여지가 있습니다. 반대로 처리가 단순하여 GAS로 충분하다면, 새로 SDK를 도입하는 비용을 정당화하기 어려운 경우도 많습니다.

비용 측면에서 Claude Agent SDK는 Claude API 호출 비용이 발생합니다. 한 번의 신청 처리에서 여러 도구를 호출하는 경우, API 콜이 늘어날수록 비용이 쌓입니다. GAS는 기본적으로 Google Workspace 이용 요금 범위 내에서 동작하므로, 호출 횟수가 많은 처리에서는 GAS가 비용 효율이 높은 경우가 있습니다. 월간 신청 건수와 1건당 처리 스텝 수를 추산한 후 아키텍처를 결정하는 절차를 밟는 것이 현실적입니다.

규모 면에서 보자면, 월 1회 정도의 정기 업데이트라면 GAS (Google Apps Script)로도 충분합니다. 신청 종류가 늘어나거나 폼 (Form)의 선택지 로직이 복잡해지는 시점이 Claude Agent SDK로의 이전을 현실적으로 검토해야 하는 분기점이 됩니다.

Claude Agent SDK × Google Sheets 설계에서는 트리거 (Trigger), 툴 (Tool), 출력 (Output)의 3개 레이어를 분리하고, 툴을 단일 책임 (Single Responsibility) 원칙에 따라 정의하는 것이 시작점입니다. OAuth 스코프 (Scope)를 툴 단위로 고려하여 권한을 최소화하고, 마스터 시트 (Master Sheet)의 스키마 (Schema)를 먼저 확정한 후 구현에 들어가면, 나중에 수정이 필요해지는 상황을 크게 줄일 수 있습니다.

먼저 작은 유스케이스 (단말 마스터 시트를 읽어 폼의 선택지를 업데이트하는 정도)부터 시도하여, 에이전트 (Agent)가 자율적으로 동작하는 감각을 익힌 뒤 범위를 넓혀가는 것이 안전한 진행 방식입니다. GAS로 구현했던 처리를 단계적으로 이행할 경우에는, 처음 1~2개의 툴을 SDK로 옮겨 한동안 병행 운용하며 동작을 확인한 뒤 다음 툴을 추가하는 흐름이 재작업 (Rework)을 방지합니다.

Claude + GWS (Google Workspace)의 구현 설계에 대해서는 DRASENAS에서도 상담을 받고 있습니다.

이 기사에서 다룬 것과 같은 업무 개선 및 자동화의 설계부터 구현까지, DRASENAS는 코포레이트 IT (Corporate IT) 현장에 밀착하여 지원을 수행하고 있습니다.

"우선 상담만" 하는 것도 대환영입니다. DRASENAS 공식 사이트를 통해 편하게 문의해 주세요.

※ 이 기사는 DRASENAS Blog의 전재물입니다. 오리지널 버전에서는 코드와 설정 절차가 수시로 업데이트되고 있습니다.