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

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

에이전트 평가와 안전장치

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

  • 비동기 멀티에이전트 조율: 공유 허브에서 동료 메시지를 주고받는 고정된 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

메모리와 컨텍스트 관리

도구 사용과 외부 연동

검색·RAG·지식 처리

멀티모달·음성·문서

응답·추론·프롬프트

Skills와 업무 애플리케이션

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

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

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견들

  • 솔직히 거의 모든 AI 사용법 자료가 무의미해 보임. 방법은 AI에 직접 물으면 되고, AI 활용법이라면 하네스에 내장하거나 사소한 기능인 만큼 Anthropic/OpenAI가 구현해 주길 기다리면 됨
    에이전트 워크플로, 메모리 관리, 하네스 엔지니어링 같은 것도 대부분 보여주기식으로 느껴짐

    • 2023년에는 프롬프트 엔지니어링이 새로운 소프트웨어 엔지니어링이 될 것이라며 CoT, ReAct 등을 열심히 익혔지만, 2024년에는 대부분 추론 모델과 하네스 업데이트로 불필요해졌음
      최신 AI 기법이나 프레임워크도 3개월 주기로 흡수되거나 대체되니 투자할 가치가 적어 보임
    • 모델의 능력이 커지면서 주변 도구를 자체적으로 흡수하므로, 이런 도구는 유효 기간이 너무 짧음. 이미 같은 패턴을 계속 목격해 왔음
    • Vercel은 도구 호출보다 명확한 지침을 담은 단일 Markdown 파일이 더 효과적일 수 있고, 압축 인덱스를 활용하는 방법도 소개했음. 나도 도구 호출을 완성하려고 여러 시간을 썼지만 비슷한 결과를 겪었고, 이후에는 Claude.md, Agents.md, 필요하면 Project.md만 사용함
    • LLM은 하네스 안에서 다른 LLM을 활용하는 능력이 형편없어 보임. 맡겨 두면 .md 파일에 온갖 내용을 넣어 컨텍스트를 오염시키기도 함
      결국 LLM이 이런 자료를 검색하게 해야 하므로, 사람보다 LLM을 위한 자료일 수도 있음
    • 모두가 MCP를 추켜세울 즈음에는 skills가 더 효율적인 대안이 됐고, 공격적인 컨텍스트 관리도 긴 컨텍스트 창과 에이전트 기능 때문에 덜 중요해졌음. 좋은 기법이라면 다음 버전에 내장될 가능성이 큼
      그래서 꼭 필요하지 않으면 플러그인과 MCP를 피하고 충실한 프롬프트를 사용함. 덕분에 낡은 최적화를 LLM에 강제해 발전을 방해하는 일을 피할 수 있었음

  • 프런트엔드 미학 프롬프팅의 전후 이미지는 우스울 정도임. 이 skill이 정말 디자인을 개선했는지 아무도 확인하지 않은 듯함

    • 제시된 결과가 전부 개선이 아니라 퇴보로 보임
    • 많은 가이드가 전형적인 LLM식 화물 숭배처럼 프런트엔드 디자인 skill을 무작정 추천하지만, 실제 내용은 사람들이 생각하는 것과 다름
    • 미학을 적용한 사이트가 2000년대 초반 키젠처럼 보이며, 테크노 음악만 더하면 될 듯함
    • 실제로 꽤 민망한 결과임. 사실상 “검은 배경과 끔찍하게 넓은 글꼴을 사용하라”는 수준임
    • 효과가 있다는 인상을 만들려고 전후 차이를 최대화한 예시를 고른 건지 궁금함. 개인적으로는 모든 예시에서 적용 전 디자인이 더 좋음

  • 프런트엔드 미학 프롬프팅의 결과는 적용 전에는 밋밋하고, 적용 후에는 그라데이션이 추가된 밋밋함임

    • 몇몇 예시는 적용 전이 더 낫고, 실제로 개선됐다고 할 만한 것은 블로그 예시뿐임
    • 오히려 미학을 적용하지 않은 버전이 더 마음에 듦
    • AI가 디자인한 페이지의 전형적인 특징인 대문자 레이블도 추가됨

  • 집에서 Matt Pocock의 skills를 사용 중인데 꽤 훌륭함. 자동 호출이 아니라 사용자가 직접 호출하도록 설계돼 있어, 존재하는 것만으로 컨텍스트를 많이 차지하지 않음
    프로그래머를 최종 결과에서 배제하기보다 결과를 더 깊이 고민하도록 유도함. grill skills는 실제 요구사항을 명확히 하고, prototype skill은 직접 체험해야 어려운 결정을 내릴 수 있는 부분을 탐색하는 데 도움을 줌

  • OpenAI Cookbook도 유용함. 다른 AI 연구소도 GitHub와 Hugging Face에 예제와 요리책을 자주 공개하므로 계속 살펴볼 가치가 있음

  • 코딩 에이전트는 백엔드보다 프런트엔드에서 버그가 많고, 깨졌거나 불완전하며 어색한 기능을 훨씬 자주 내놓음. 두 영역의 검증 가능성 차이가 원인으로 보이고 기본 테스트 모음만으로는 부족함
    Garry Tan의 gstack 같은 접근이 적절해 보이지만 도입할 만큼 성숙했는지는 모르겠음. Gemini 3.5 Flash가 프런트엔드 작업에서 Opus나 GPT-5.5보다 낫다는 평가도 있는데, 멀티모달 능력이나 Chrome 이해도 때문인지 실제 사용자 평가가 궁금함

    • Claude의 Front End Design skill처럼 에이전트와 결합된 선택지도 있을 수 있지만 직접 써보지는 않았음. Magic Patterns는 기능과 제약을 아는 에이전트가 조종할 때 초기 프로토타입 생성에 특히 뛰어남
      창의적인 결과를 얻으려면 적극적으로 요구해야 하지만 표준적인 프런트엔드 디자인에는 좋음. 다만 임의 기능 추가나 수정이 아니라 아이디어를 시험하는 용도로만 사용함
    • 에이전트는 복잡한 비동기 상태 갱신을 컨텍스트에 표현하기 어려워 잘 처리하지 못함. 반면 복잡한 컴포넌트를 독립적으로 만들거나 애니메이션처럼 결합도가 낮은 기능을 구현하는 데는 괜찮음

  • LLM으로 그럴듯하고 실제 조리 가능한 요리법을 만드는 진짜 요리책인 줄 알았는데, 아직 그런 단계는 아닌 듯함

    • 1년 넘게 한 달에 몇 번씩 LLM의 도움으로 요리했고 열 번 중 아홉 번은 잘됐음. 모델 가중치에 담긴 평균적인 조리법도 대체로 탄탄하며, “재료 X가 없다”거나 “채식으로 바꿔 달라”는 식의 재료 대체에도 뛰어남
      조리법을 받은 뒤 “더 맛있게 만들어 줘”라고 한두 번 요청해 결과를 보는 것도 재미있음
    • ChatGPT로 이탈리아 요리를 배우고 있는데, 몇 차례 시행착오를 제외하면 놀라울 정도로 잘 작동함
    • 올해 Gemini와 몇 차례 요리해 봤는데 예상보다 훌륭했음. “식료품 저장실에 이런 재료가 있고 키토 식단을 원한다”라고 말한 뒤 대화로 후보를 좁힐 수도 있음
    • 나도 디지털 식단 계획 도구를 기대했음

  • Claude로 조리법을 생성하는 새 제품인 줄 알았음

    • Claude 프로젝트를 조리법에 활용 중인데, 메뉴를 추천하고 저장실에 있는 재료에 맞게 조리법을 조정하는 데 훌륭해서 나도 그런 제품을 기대했음
    • 실제로 그런 용도로도 사용할 수 있음

  • 요리책 적용 전후의 디자인이 양쪽 모두 바이브 코딩으로 만든 것처럼 보임. 정확한 원인을 짚을 만큼 디자이너는 아니지만 Claude가 구사하는 스타일의 폭은 다소 제한적인 듯함
    필요한 변경 사항을 더 구체적으로 지정하면 이런 경향을 억제할 수 있을지도 모름

  • UI를 최소한 한 번은 검토했어야 함. 간단한 표 간격조차 제대로 맞추지 못했음

답변달기