Claude Cookbook: 에이전트부터 RAG·멀티모달·운영까지

• Claude 애플리케이션을 구현하는 실전 가이드와 예제를 모아 에이전트 구축부터 RAG·도구 사용·멀티모달·평가까지 폭넓게 다룸
• Claude Agent SDK·Managed Agents 예제에는 멀티에이전트 조율, 세션 관리, 배포, 장애 대응, 취약점 탐지, 사용자 기억 등 운영 패턴이 포함됨
• 장기 실행 에이전트를 위한 메모리·컨텍스트 압축, 프로그래밍 방식 도구 호출, 임베딩 기반 도구 검색, 비동기 하위 에이전트 기법을 제공함
• RAG, SQL 생성, 지식 그래프, 문서 요약, 이미지·음성 처리뿐 아니라 평가·비용·관측성·안전장치까지 구현 예제로 확인할 수 있음
• Docker·Modal·Kubernetes 배포, 프롬프트 버전 관리와 롤백, 사람의 승인, 비용 분석을 아우르며 개발과 프로덕션 운영 전반에 활용할 수 있음

에이전트 평가와 안전장치

• Claude의 에이전트 검색 벤치마크 점수 재현: Messages API 하네스로 DeepSearchQA·BrowseComp 점수를 재현하며, 프로그래밍 방식 도구 호출·서버 측 압축·작업 예산을 사용함
• Claude Fable 5의 분류기 폴백과 과금: 안전 분류기의 차단을 감지해 Opus 4.8로 전환하고, 서버 또는 SDK 클라이언트 측 폴백과 스트리밍 및 새 과금 변경을 다룸
• 도구 평가: 평가 작업 파일과 독립적으로 도구에 대한 병렬 에이전트 평가를 실행함
• 평가 구축: 주요 지표에서 Claude의 성능을 측정하고 개선하는 평가 시스템을 구축함
• 프롬프트 템플릿용 합성 테스트 데이터 생성: Claude 프롬프트를 평가하고 개선할 합성 테스트 사례를 생성함
• Claude로 검토 필터 구축: 프롬프트에 규칙과 범주를 정의해 맞춤형 콘텐츠 검토 필터를 만듦

멀티에이전트와 워크플로 패턴

• 비동기 멀티에이전트 조율: 공유 허브에서 동료 메시지를 주고받는 고정된 N개 에이전트 팀과 동적으로 생성되는 비동기 하위 에이전트의 메시징·수명주기 구조를 다룸
• 멀티에이전트: 전문가 팀 조율: 조율자가 웹 검색 연구자·파일 열람 담당·규칙 기반 가격 담당을 이끌어 영업 제안서를 작성함
• multiagent 필드, thread_created·thread_message_received 이벤트, 역할별 도구 범위 제한을 포함함
• Outcomes: 자체 작업을 검증하는 에이전트: 작성자가 인용 연구 요약을 만들고 상태 없는 채점기가 URL과 인용문을 검사한 뒤, 통과할 때까지 수정하는 채점·개선 루프를 구축함
• user.define_outcome, span.outcome_evaluation_* 이벤트와 채점기가 실행할 수 있는 평가 기준 작성법을 다룸
• 기본 워크플로: 비용이나 지연 시간을 성능과 맞바꾸는 세 가지 멀티 LLM 패턴을 제공함
• 평가자-최적화기: 한 LLM이 결과를 생성하고 다른 LLM이 평가 피드백을 제공하는 반복 구조임
• 조율자-작업자: 중앙 LLM이 작업을 동적으로 위임하고 작업자 LLM의 결과를 종합함
• Haiku를 하위 에이전트로 사용: Haiku 하위 에이전트가 금융 보고서를 추출하고 Opus가 결과를 종합함

Claude Agent SDK

• 한 줄짜리 연구 에이전트: Claude Code SDK와 WebSearch로 자율 연구 에이전트를 구축함
• 비서실장 에이전트: 하위 에이전트, 훅(hook), 출력 스타일, 계획 모드로 멀티에이전트 시스템을 만듦
• 관측성 에이전트: MCP 서버로 에이전트를 외부 시스템에 연결해 GitHub 모니터링과 CI 워크플로를 처리함
• 사이트 신뢰성 에이전트: 읽기·쓰기 MCP 도구로 장애를 진단·복구하고 사후 보고서를 작성함
• OpenAI Agents SDK에서 마이그레이션: 비용 승인 에이전트를 예로 들어 도구·가드레일·세션·핸드오프를 Claude Agent SDK 기본 요소에 대응시킴
• 세션 브라우저 구축: 디스크의 Agent SDK 세션을 나열·열람하고 이름 변경·태그·포크해, 별도 대화 기록 파서 없이 사이드바를 만듦
• 취약점 탐지 에이전트: C 대상을 위협 모델링하고 내장 파일 도구로 메모리 안전성 버그를 찾은 뒤 구조화된 보고서로 분류함
• 에이전트 호스팅: 동일한 컨테이너 이미지와 HTTP 인터페이스를 유지하며 연구 에이전트를 Docker·Modal·Kubernetes 세 단계로 배포함

Claude Managed Agents

• 사용자를 기억하는 에이전트 구축: Memory 저장소를 이용해 여러 상호작용에 걸쳐 사용자 선호를 학습하고 기억함
• Claude Managed Agents로 SRE 장애 대응 에이전트 구축: 경보가 발생하면 로그와 런북을 읽고 근본 원인을 찾아 수정 PR을 열며, 사람의 승인 후 병합함
• 데이터 분석 에이전트 구축: 샌드박스 환경과 파일 마운트를 이용해 CSV를 대화형 차트가 포함된 HTML 보고서로 변환함
• Slack 데이터 분석 봇 구축: CSV와 함께 봇을 멘션하면 스레드에 분석 보고서를 생성하고 같은 세션에서 후속 대화를 지원함
• Managed Agents 튜토리얼: 실패하는 테스트 모음 개선: 에이전트·환경·세션 생성, 파일 마운트, 스트리밍 이벤트 루프를 이용해 calc.py 패키지의 세 가지 버그를 수정함
• Managed Agents 튜토리얼: 프로덕션 설정: 금고 기반 MCP 자격 증명, 장기 연결 없이 사람을 개입시키는 session.status_idled 웹훅, 리소스 수명주기 CRUD를 다룸
• Managed Agents 튜토리얼: 프롬프트 버전 관리와 롤백: 서버에서 v1을 만들고 레이블된 테스트 세트로 평가한 뒤, v2 회귀를 감지해 세션을 버전 1로 고정함
• agents.update, sessions.create의 버전 고정, 프롬프트가 코드가 아닐 때 검토 관문이 이동하는 위치를 포함함

메모리와 컨텍스트 관리

• 컨텍스트 엔지니어링: 메모리·압축·도구 제거: 장기 실행 에이전트에서 전략별 적용 시점·비용·조합 방식을 비교함
• 세션 메모리 압축: 백그라운드 스레딩과 프롬프트 캐싱으로 장기 대화의 세션 메모리를 즉시 압축함
• 자동 컨텍스트 압축: 장기 에이전트 워크플로에서 대화 기록을 자동으로 압축해 컨텍스트 한도를 관리함
• Claude Sonnet 4.6의 메모리와 컨텍스트 관리: Claude의 메모리 도구와 컨텍스트 편집으로 영속 메모리 에이전트를 구축함
• 추측적 프롬프트 캐싱: 사용자가 질의를 작성하는 동안 캐시를 미리 준비해 첫 토큰 응답 시간을 줄임
• Claude API의 프롬프트 캐싱: 프롬프트 컨텍스트를 캐시하고 재사용해 비용과 응답 시간을 줄임

도구 사용과 외부 연동

• 프로그래밍 방식 도구 호출: Claude가 코드 실행 환경에서 도구 호출 코드를 작성하게 해 지연 시간과 토큰 소비를 줄임
• 임베딩을 이용한 도구 검색: 의미 임베딩 기반 동적 검색으로 Claude 애플리케이션을 수천 개 도구까지 확장함
• Claude 3.7 Sonnet의 병렬 도구 호출: 배치 도구 메타 패턴을 우회책으로 이용해 병렬 호출을 활성화함
• 도구 선택: tool_choice 매개변수로 Claude의 도구 선택을 강제하거나 자동화함
• Pydantic와 Anthropic 도구 사용을 결합한 메모 저장 도구: Pydantic 모델로 검증되는 타입 안전 도구를 생성함
• Claude에서 계산기 도구 사용: 산술 연산과 수학 문제 해결을 위한 계산기 도구를 제공함
• 클라이언트 측 도구로 고객 서비스 에이전트 만들기: 고객 조회와 주문 관리 도구를 사용하는 챗봇을 구축함
• Claude와 도구 사용으로 구조화된 JSON 추출: 여러 입력에서 구조화된 JSON 데이터를 추출함
• Claude에서 Wolfram Alpha LLM API를 도구로 사용: 계산 질의와 답변을 위해 Wolfram Alpha LLM API를 통합함
• 위협 인텔리전스 보강 에이전트: 여러 위협 정보원에서 침해 지표를 조사·교차 검증하고 MITRE ATT&CK에 매핑해 SIEM·SOAR용 보고서를 생성함

검색·RAG·지식 처리

• Claude로 지식 그래프 구축: 비정형 텍스트에서 개체와 관계를 추출하고 중복을 제거해 다중 홉 그래프 질의를 지원함
• Claude를 이용한 Text-to-SQL: RAG, 사고 과정, 자기 개선 기법으로 자연어를 SQL로 변환함
• 컨텍스트 검색으로 RAG 개선: 임베딩 전 청크에 컨텍스트를 추가하고 프롬프트 캐싱을 적용해 RAG 정확도를 높임
• 검색 증강 생성: 요약 인덱싱과 재순위화로 RAG 시스템을 구축하고 최적화함
• Claude를 이용한 분류: 보험 티켓을 대상으로 RAG와 사고 과정을 활용하는 분류 시스템을 구축함
• 인용: 문서 기반 질의에 검증 가능한 상세 출처 인용을 제공함
• Claude 3 Haiku로 웹페이지 콘텐츠 요약: URL에서 콘텐츠를 가져와 Claude 3 Haiku로 요약함
• Claude로 SQL 질의 만들기: 데이터베이스 스키마 컨텍스트를 제공해 자연어 질문에서 SQL을 생성함
• Pinecone을 이용한 검색 증강 생성: Claude를 Pinecone 벡터 데이터베이스와 연결해 RAG와 의미 검색을 구현함
• Claude 3와 MongoDB로 RAG 시스템 구축: 기술 뉴스를 지식 기반으로 사용하는 Claude·MongoDB 챗봇을 구축함
• Claude 3 RAG 에이전트와 LangChain v1: LangChain v1의 갱신된 에이전트 프레임워크 패턴으로 RAG 에이전트를 만듦
• 다중 문서 에이전트: DocumentAgents와 ReAct 패턴으로 대규모 문서 컬렉션용 RAG를 구축함
• LlamaIndex를 이용한 RAG 파이프라인: 문서 검색과 질의응답을 위한 기본 파이프라인을 만듦
• RouterQuery 엔진: LlamaIndex RouterQueryEngine으로 질의를 서로 다른 인덱스에 전달함
• SubQuestionQueryEngine: 복잡한 질의를 여러 문서에 걸친 하위 질문으로 분해함
• API를 통해 PDF를 Claude에 ‘업로드’하기: 텍스트 추출과 인코딩으로 PDF 문서를 처리하고 요약함
• Claude로 Wikipedia 반복 검색: Claude 2로 Wikipedia를 반복 검색하는 연구 워크플로의 레거시 노트북임

멀티모달·음성·문서

• 이미지 분석 개선을 위한 자르기 도구 제공: 차트·문서·다이어그램의 특정 영역을 확대해 자세히 분석함
• Claude에서 비전과 도구 함께 사용: 이미지 이해와 도구를 결합해 영양성분표 같은 이미지에서 구조화된 데이터를 추출함
• Claude 비전 사용 모범 사례: 이미지 처리 성능을 높이는 기법과 팁을 제공함
• 시작하기: Claude에 이미지 전달: Claude 3 API에 이미지를 전달해 비전 기반 텍스트 분석을 수행함
• Claude로 문서 전사: 이미지와 PDF의 비정형 텍스트를 추출하고 구조화함
• 차트·그래프·슬라이드 덱 작업: Claude 비전으로 차트·그래프·프레젠테이션에서 정보를 추출함
• 멀티모달: LlamaIndex의 Anthropic MultiModal LLM 추상화로 이미지 이해와 추론을 수행함
• ElevenLabs를 이용한 저지연 음성 비서: ElevenLabs의 음성-텍스트·텍스트-음성 기능을 Claude와 결합함
• Deepgram으로 오디오를 전사하고 Anthropic으로 인터뷰 질문 준비: 오디오를 전사하고 Claude로 인터뷰 질문을 생성함

응답·추론·프롬프트

• 확장 사고: 예산 관리와 함께 Claude의 단계별 확장 사고를 사용함
• 도구 사용을 결합한 확장 사고: 다단계 워크플로에서 확장 사고와 도구를 결합함
• 프런트엔드 미학을 위한 프롬프팅: 일반적인 미학을 피하면서 개성 있고 완성도 높은 프런트엔드를 생성하는 프롬프트 작성법을 다룸
• Claude로 요약: 평가와 고급 기법을 포함해 법률 문서를 요약함
• 최대 토큰 한도를 넘어 Claude 응답 샘플링: 프리필과 메시지 이어쓰기로 max_tokens를 넘는 긴 응답을 생성함
• Metaprompt: 빈 페이지 문제를 줄이기 위해 작업용 시작 프롬프트를 생성함
• Claude에 ‘JSON 모드’ 프롬프팅: 제한 샘플링 없이 프롬프트 기법으로 신뢰성 있는 JSON 출력을 얻음
• Message Batches API를 이용한 일괄 처리: 대량 요청을 비동기로 처리하며 비용을 50% 절감함

Skills와 업무 애플리케이션

• 금융 애플리케이션용 Claude Skills: Excel·PowerPoint·PDF Skills로 금융 대시보드와 포트폴리오 분석을 구축함
• Claude용 사용자 정의 Skills 구축: 조직 특화 워크플로를 확장하는 Skills를 생성·배포·관리함
• Claude Skills 소개: Excel·PowerPoint·PDF Skills로 문서 생성, 데이터 분석, 워크플로 자동화를 수행함
• Claude 3 Haiku를 Amazon Bedrock에서 파인튜닝: 맞춤 작업을 위해 Claude 3 Haiku를 Amazon Bedrock에서 파인튜닝하는 절차를 제공함
• 사용량 및 비용 Admin API Cookbook: Admin API로 Claude API 사용량과 비용 데이터에 프로그래밍 방식으로 접근하고 분석함

LlamaIndex 에이전트 패턴과 커뮤니티 기여

• ReAct 에이전트: LlamaIndex로 도구 기반 추론과 행동 워크플로를 수행하는 ReAct 에이전트를 구축함
• 새로운 Cookbook 아이디어를 위한 커뮤니티 기여를 받고 있으며, 기여 가이드를 제공함