본문으로 건너뛰기

API로 에이전트 구축하기

고급

What you'll learn

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

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

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

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

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

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

Watch out

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

루프 설계

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

Guided walkthrough1 of 4

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

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

Pro tip

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

견고하게 만들기

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

모든 것에 경계 설정: 반복 횟수, 시간, 비용. 에이전트는 무한 루프에 빠질 수 있습니다.
도구 실패를 우아하게 처리하기 (오류를 결과로 반환).
위험한 작업에는 최소 권한 + 휴먼 인 더 루프 — 에이전트 보안 참고.
신뢰하기 전에 실제 사례로 평가하기 — 평가(Evals) 참고.

Key takeaways

에이전트는 목표를 향해 도구를 호출하며 루프 안에서 실행되는 모델이다 — 경로를 하드코딩할 수 없을 때만 사용하라
결정 순서: 단일 호출 → 워크플로우 → 에이전트 → 관리형 에이전트; 동작하는 가장 단순한 것을 선호하라
최소한의 루프 = 시스템 프롬프트 + tool_use/tool_result 루프 + 가드레일 + 컨텍스트 관리
Claude Agent SDK는 루프, 도구, 권한, 컨텍스트 처리를 제공한다
견고함 = 반복/시간/비용 경계 설정, 도구 실패 처리, 최소 권한 + 휴먼 인 더 루프, 신뢰 전 평가

스스로 점검하기

스스로 점검하기

0/5

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

다음

선택 기준 (과잉 설계 금지)
루프 설계
견고하게 만들기
스스로 점검하기
다음