Claude Agent SDK 한국어 패턴 12가지

에이전트가 무한 루프에 빠지지 않도록 max_turns(보통 20-50)로 제한. 초과 시 graceful fallback 또는 에러 반환.

언제: tool 호출이 자기 자신을 호출하는 재귀 패턴, 또는 stop 조건이 명확하지 않을 때.

Claude가 더 이상 tool을 호출하지 않으면 stop_reason이 'end_turn'. 이때 최종 텍스트 응답을 반환하고 루프 종료.

언제: 표준 agentic loop 종료 조건. tool_use를 받으면 다시 루프, end_turn이면 종료.

Claude가 한 응답에서 여러 tool_use 블록을 반환할 수 있음. asyncio.gather (Python) 또는 Promise.all (TS)로 병렬 실행. 모든 결과를 single user 메시지에 묶어서 다음 턴에 전달.

언제: 독립적인 tool 호출 (예: 여러 파일 읽기, 여러 DB 쿼리). 직렬 실행 대비 5-10x 빠름.

tool 실행 실패 시 예외를 throw하지 말고 {error: '...'} JSON으로 반환. Claude가 읽고 재시도하거나 다른 접근 결정.

언제: 외부 API 호출, 파일 I/O, DB 쿼리 등 실패 가능한 모든 tool.

RateLimitError → exponential backoff. APITimeoutError → 빠른 재시도. APIConnectionError → 단일 재시도. 외 다른 종류는 즉시 raise.

언제: 프로덕션 에이전트의 모든 client.messages.create() 호출 주변.

다음 user 메시지의 tool_result는 이전 assistant 메시지의 tool_use_id와 정확히 매칭되어야 함. 불일치 시 400 에러. 명시적 검증 + 로깅.

언제: 복잡한 multi-tool 호출에서 메시지 history를 직접 조립할 때.

응답 길이 상한. 단순 분류는 256, 코드 생성은 4096, agent reasoning은 8192. 미설정 시 모델이 길게 응답.

언제: 모든 messages.create() 호출. 미설정 = 비용 폭탄 가능성.

각 응답의 usage.input_tokens / output_tokens / cache_read_input_tokens / cache_creation_input_tokens를 합산. 사용자별 또는 세션별 비용 임계값 설정 (예: $5/세션).

언제: 사용자가 트리거하는 에이전트, 외부에 노출된 에이전트.

단순 작업(분류, 추출, 요약)은 Haiku로 시작. 복잡 추론이 필요할 때만 Sonnet/Opus로 escalate. 80% 절감 가능.

언제: 다양한 복잡도의 작업을 처리하는 에이전트. router 함수로 자동 분류.

Supervisor agent가 작업을 sub-task로 분할하고 worker agent에 위임. Worker는 독립 컨텍스트로 실행, 결과를 supervisor에 반환.

언제: 복잡한 멀티스텝 작업 (예: 코드베이스 분석 + 리팩토링). 컨텍스트 격리로 재사용성 ↑.

Worker 출력을 supervisor가 받기 전 schema 검증 (Pydantic 또는 Zod). 잘못된 출력은 worker에 재요청 (1-2회 한정).

언제: JSON 출력을 다음 단계 input으로 사용하는 모든 multi-agent flow.

에이전트 동작을 테스트할 때 LLM 응답을 mock하지 말고, 고정된 input으로 cassette 녹화 (vcrpy 또는 nock). 동일 prompt → 동일 response 검증.

언제: CI에서 에이전트 회귀 테스트. 모델 응답에 의존하지 않고 비즈니스 로직만 검증.