본문으로 건너뛰기

API로 에이전트 구축하기

고급
What you'll learn
  • 에이전트가 실제로 무엇인지 정의하기: 루프 안에서 실행되는 모델
  • 선택 기준을 적용해 단일 호출 vs 워크플로우 vs 에이전트 고르기
  • 올바른 가드레일을 갖춘 최소한의 에이전트 루프 설계하기
  • 직접 구현하는 대신 Claude Agent SDK를 언제 써야 하는지 알기
  • 에이전트를 견고하게 만들기: 경계 설정, 실패 처리, 권한 제한, 평가

에이전트는 루프 안에서 실행되는 모델입니다: 도구를 호출하고, 결과를 관찰하며, 완료될 때까지 다음 단계를 결정하면서 목표를 추구합니다. 에이전트를 만들기 전에 동작하는 가장 단순한 것을 고르세요.

선택 기준 (과잉 설계 금지)​

모든 작업에 에이전트가 필요한 것은 아닙니다. 먼저 이 트리를 따라가 보세요 — 대부분의 작업은 맨 위에서 멈춥니다.

세 가지 옵션, 단순한 순서대로:

  • 단일 호출 — 하나의 프롬프트로 해결됩니다. 대부분의 작업이 여기에 해당. 가장 저렴하고 가장 안정적.
  • 워크플로우 — 코드에서 고정된 호출 시퀀스를 직접 오케스트레이션합니다(결정론적 제어 흐름). 단계가 알려져 있을 때 사용.
  • 에이전트 — 모델이 단계를 동적으로 결정합니다. 경로를 도저히 하드코딩할 수 없을 때만 사용.
Watch out

적응성이 핵심일 때 에이전트를 선택하세요 — 그럴싸해 보이기 때문이 아니라. 직접 제어하는 워크플로우가 테스트하고 디버깅하기 더 쉽습니다.

루프 설계​

최소한의 커스텀 에이전트는 네 개의 움직이는 부품일 뿐입니다. 이 순서로 만드세요:

Guided walkthrough1 of 4
  1. 목표, 제약 조건, 사용 가능한 도구를 명시합니다. 모델이 매 턴마다 이것을 근거로 추론합니다.

**Claude Agent SDK**는 이 루프 — 도구, 권한, 컨텍스트 처리 — 를 기본 제공하므로 직접 구현할 필요가 없습니다.

Pro tip

직접 루프를 작성하기 전에 Agent SDK가 이미 그것을 다루는지 확인하세요. 루프, 권한, 컨텍스트 처리를 제공하므로 여러분은 도구와 목표에 집중할 수 있습니다.

견고하게 만들기​

도구를 호출할 수 있는 루프는 오작동할 수도 있습니다. 네 가지 습관이 에이전트를 신뢰할 수 있게 유지합니다:

  • 모든 것에 경계 설정: 반복 횟수, 시간, 비용. 에이전트는 무한 루프에 빠질 수 있습니다.
  • 도구 실패를 우아하게 처리하기 (오류를 결과로 반환).
  • 위험한 작업에는 최소 권한 + 휴먼 인 더 루프 — 에이전트 보안 참고.
  • 신뢰하기 전에 실제 사례로 평가하기 — 평가(Evals) 참고.
Key takeaways
  • 에이전트는 목표를 향해 도구를 호출하며 루프 안에서 실행되는 모델이다 — 경로를 하드코딩할 수 없을 때만 사용하라
  • 결정 순서: 단일 호출 → 워크플로우 → 에이전트 → 관리형 에이전트; 동작하는 가장 단순한 것을 선호하라
  • 최소한의 루프 = 시스템 프롬프트 + tool_use/tool_result 루프 + 가드레일 + 컨텍스트 관리
  • Claude Agent SDK는 루프, 도구, 권한, 컨텍스트 처리를 제공한다
  • 견고함 = 반복/시간/비용 경계 설정, 도구 실패 처리, 최소 권한 + 휴먼 인 더 루프, 신뢰 전 평가

스스로 점검하기​

스스로 점검하기

0/5
  1. 이 맥락에서 에이전트를 가장 잘 설명하는 것은?
  2. 작업에 고정되고 알려진 단계들이 있습니다. 무엇을 선택해야 할까요?
  3. 커스텀 에이전트가 실제로 정당화되는 경우는?
  4. 루프에서 모델이 tool_use로 응답하면 무슨 일이 일어나나요?
  5. 에이전트를 견고하게 만드는 가드레일이 아닌 것은?

다음​