Claude Agent SDK: 기능 및 평가 방법

Claude Agent SDK 는 Claude가 제한된 도구 사용 워크플로우를 실행할 수 있도록 애플리케이션을 구축하기 위한 개발자 인터페이스입니다. SDK는 세션을 관리하고, 도구를 호출하고, 작업을 조정할 수 있지만, 애플리케이션 권한, 소스 제어, 평가 또는 사람의 승인이 필요하지 않게 되는 것은 아닙니다. 완전한 프로덕션 시스템이 아닌 에이전트 런타임 구성 요소로 간주하십시오.

에이전트 런타임을 소유하지 않고 소스 기반 작업을 완료해야 하는 팀을 위해 Ottermind는 관리형 작업 공간 경로를 제공합니다. 이를 통해 파일, 연구 컨텍스트, 결정 및 결과물을 연결된 상태로 유지하면서 담당자가 결과를 검토할 수 있습니다. SDK와 관리형 작업 공간은 서로 다른 운영 문제를 해결합니다.

연구 및 공개: 이 가이드는 2026년 9월 3일에 검토된 Claude Agent SDK 저장소, Anthropic 도구 사용 설명서 및 AWS 에이전트 코어 Claude Agent SDK 문서를 기반으로 합니다. API 및 제한 사항은 변경될 수 있으므로 구현 전에 최신 릴리스를 확인하십시오.

핵심 구성 요소

되돌릴 수 있는 작업 하나부터 시작

승인된 저장소 파일을 변경 개요로 변환하는 것과 같은 읽기 중심 워크플로 프로토타입 제작. 입력 세트, 프롬프트, 모델 버전, 도구 호출, 출력, 검토자 수정 사항 및 최종 결정 사항을 기록합니다. 추적 내용이 이해 가능하고 오류 복구가 가능해진 후에만 쓰기 권한을 추가합니다.

최소 작업 계약

목표: 소스 기반 구현 개요 작성
허용된 소스: 첨부된 저장소 파일만 해당
허용된 도구: 파일 목록 및 파일 읽기; 쓰기 또는 네트워크 호출은 허용되지 않음
출력: 결과, 제안된 변경 사항, 증거, 위험 및 미해결 질문.
중지 조건: 필수 소스가 없거나 권한이 불분명한 경우.

세션 및 하위 에이전트

워크플로의 연속성이 여러 단계에 걸쳐 필요한 경우 세션을 사용합니다. 역할, 도구 또는 평가 기준이 실제로 다른 경우에만 하위 에이전트를 사용합니다. 에이전트 수가 많아지면 조정, 지연 및 오류 발생 가능성이 증가합니다. 각 역할에 필요한 최소한의 컨텍스트를 전달하고 상태 및 증거가 포함된 구조화된 결과를 반환합니다.

실용적인 아키텍처

SDK를 다음 다섯 가지 책임이 있는 애플리케이션 경계 내에 유지합니다.

1. 요청 처리기: 사용자를 인증하고, 허용된 프로젝트를 선택하고, 예산을 설정합니다.
2. 컨텍스트 로더: 허용된 파일만 검색하고 해당 파일의 식별자와 날짜를 기록합니다.
3. 에이전트 실행기: 세션을 시작하고, 도구를 제공하며, 각 도구 요청과 결과를 저장합니다.
4. 정책 계층: 인수를 검증하고, 허용되지 않는 작업을 차단하고, 확인을 요청합니다.
5. 결과 어댑터: 반환된 형태를 검증하고 초안을 검토자 또는 다음 시스템에 전달합니다.

이러한 분리는 SDK가 모델이 도구를 요청하도록 도울 수 있지만, 해당 요청을 허용할지 여부는 애플리케이션에서 결정하기 때문에 중요합니다. 권한 부여 로직을 프롬프트에 배치하거나 모델이 테넌트 경계를 자체적으로 유지할 것이라고 가정하지 마십시오.

세션, 재개 및 실패

모든 실행에 completed, needs_review, blocked 또는 failed와 같은 명확한 식별자와 종료 상태를 부여합니다. 모델 및 SDK 버전, 프롬프트 수정, 입력 소스, 도구 호출 및 검토자 결정을 저장합니다. 쓰기 후 네트워크 오류가 발생하면 멱등성 키를 사용하고 재시도하기 전에 기록 시스템에 쿼리합니다. 사람이 편집한 후 세션이 재개되면 불투명한 대화를 다시 재생하는 대신 편집된 아티팩트와 변경 이유를 포함합니다.

도구 설계 예시

범용 셸 도구보다는 create_draft_task(title, owner, due_date)와 같은 특정 기능을 선호합니다. 이 기능은 날짜 형식, 허용된 소유자, 프로젝트 범위 및 초안 상태를 강제할 수 있습니다. 파일 검색 도구는 파일 식별자와 발췌 내용을 반환해야 하며, 드라이브 전체를 몰래 노출해서는 안 됩니다. 브라우저 도구는 허용 목록을 사용하고 인증 또는 결제 전에 중지해야 합니다.

비용 및 지연 시간

실행 시작 전에 예산을 설정하세요: 최대 모델 회전 수, 도구 호출 수, 토큰 수, 경과 시간, 하위 에이전트 수. 품질이 허용하는 경우 더 작은 모델로 추출을 라우팅하고, 모호한 단계에만 복잡한 추론을 적용하세요. 실제 사용량을 결과와 함께 기록하여 성공적인 데모로 비효율적인 워크플로가 가려지지 않도록 하세요. 시간이 오래 걸리는 작업은 비동기식으로 처리하고, 취소할 수 있도록 하며, 사용자에게 표시되어야 합니다.

SDK와 관리형 워크스페이스 비교

팀에서 애플리케이션별 도구, 배포 제어 또는 사용자 지정 런타임이 필요하고 보안, 관찰 가능성 및 유지 관리를 직접 담당할 수 있는 경우 SDK를 사용하여 빌드하세요. 주요 요구 사항이 파일, 연구, 의사 결정 및 결과물을 연결하여 사람이 검토할 수 있도록 하는 것인 경우 관리형 워크스페이스가 더 나은 시작점입니다. 선택은 운영 책임에 관한 것이지 어떤 명칭이 더 자율적으로 들리는지에 관한 것이 아닙니다.

예: 연구-브리핑 에이전트

매주 경쟁사 분석 보고서가 필요한 팀을 상상해 보세요. 요청 처리기는 분석가의 신원을 확인하고 승인된 프로젝트를 선택합니다. 컨텍스트 로더는 소스 목록을 검색하고 검색 날짜를 기록합니다. 에이전트 세션은 search_approved_sources와 draft_brief만 호출할 수 있습니다. 정책 계층은 임의의 URL, 외부 게시물 또는 프로젝트 외부 파일에 대한 요청을 거부합니다. 결과 어댑터는 검토자에게 초안을 제시하기 전에 결과, 인용, 불확실성 및 미해결 질문에 대한 섹션을 요구합니다.

유용한 산출물은 최종 문서만이 아닙니다. 사용 가능한 소스, 호출된 도구, 차단된 사항, 검토자가 변경한 내용, 그리고 브리핑이 승인되었는지 여부와 같은 추적 기록도 중요합니다. 이러한 추적 기록은 디버깅, 비용 분석, 그리고 모델이나 SDK가 변경될 때 반복 가능한 평가 세트를 지원합니다.

버전 관리 및 업그레이드

각 환경에서 SDK 및 모델 버전을 고정하십시오. 권한 모드, 도구 스키마, 세션 동작 및 지원 모델 변경 사항은 릴리스 노트를 참조하십시오. 업그레이드 전에 회귀 테스트를 실행하고, 금지된 도구가 여전히 금지된 상태로 유지되는지 확인하는 테스트를 포함하십시오. 롤백 버전을 준비해 두고, 마이그레이션 계획 없이 장기 실행 워크플로 도중에 업그레이드하지 마십시오.

프로덕션 준비 체크리스트

• 컨텍스트 검색 전에 인증 및 테넌트 확인이 수행됩니다.
• 모든 도구에는 세부 스키마, 시간 초과 및 권한 확인 기능이 있습니다.
• 세션에는 예산, 취소, 만료 및 종료 상태가 있습니다.
• 출력은 시스템에 기록되기 전에 유효성 검사를 거칩니다.
• 민감한 작업에는 명시적인 사람의 승인이 필요합니다.
• 로그에는 비밀 키를 저장하지 않고도 오류를 재현할 수 있도록 충분한 출처 정보가 포함되어 있습니다.
• 평가 사례는 품질, 안전성, 비용 및 지연 시간을 다룹니다.

권한 및 보안 경계

애플리케이션 코드에서 도구 인수의 유효성을 검사합니다. 자격 증명은 프롬프트 외부에 유지하고, 파일 시스템 및 네트워크 액세스 범위를 설정하고, 시간 제한을 설정하고, 전송, 삭제, 구매 또는 액세스 변경 시 확인을 요구합니다. 모든 중요한 도구 호출을 담당자 신원 및 승인 결정과 함께 로그에 기록합니다.

데모가 아닌 워크플로를 평가합니다.

정상, 불완전, 모순, 공격적, 권한 민감형 케이스를 포함하는 테스트 세트를 구축합니다. 정확한 완료, 안전한 에스컬레이션, 도구 오류, 지연 시간, 비용 및 검토자 수정 사항을 측정합니다. 각 평가 실행에 대해 모델 및 SDK 버전을 고정합니다.

자주 묻는 질문(FAQ)

Claude Agent SDK는 Claude API 도구 사용과 동일한가요?

아니요. 도구 사용은 모델 상호 작용 패턴입니다. SDK는 에이전트 세션 및 워크플로를 위한 애플리케이션 수준의 구성 요소를 더 많이 제공하며, 정책, 스토리지, 권한 및 평가는 여전히 애플리케이션에서 관리합니다.

에이전트를 여러 개 사용해야 하나요?

일반적으로 처음에는 그렇지 않습니다. 제한된 도구와 명확한 체크포인트를 가진 단일 에이전트가 테스트 및 운영하기 더 쉽습니다.

SDK가 파일을 안전하게 편집하거나 명령을 실행할 수 있습니까?

그러한 도구에 연결할 수는 있지만, 안전성은 샌드박스, 허용 목록, 유효성 검사, 검토 및 롤백 설계에서 비롯됩니다. 생성된 명령을 사전 승인된 것으로 절대 취급하지 마십시오.

더 넓은 시스템 경계에 대해서는 AI 에이전트 아키텍처 및 AI 에이전트 보안를 참조하십시오.