콘텐츠로 이동

에이전틱 루프와 도구 실행 (How Tool Use Works)

모델이 "어떻게" 도구를 호출하고, 우리 코드가 "언제" 그 호출을 실행하고 결과를 되돌리는지 이해하면 어떤 도구 유형(클라이언트 vs 서버)을 쓸지, 에이전틱 루프를 어떻게 구성할지가 명확해집니다. 데이터스케쳐스의 AI 에이전트(Neuron)·문서 자동화 관점에서 정리합니다.

도구 실행 위치: 클라이언트 vs 서버

도구는 코드가 어디서 도는지로 구분됩니다.

  • 클라이언트 도구(Client tools): 우리가 정의한 함수·스키마를 우리 앱에서 실행합니다. 모델은 stop_reason: "tool_use" 와 함께 하나 이상의 tool_use 블록을 반환하고, 우리 코드가 그 작업을 실제로 실행한 뒤 tool_result 로 결과를 다시 모델에 보냅니다.
  • 서버 도구(Server tools): 공급자(예: Anthropic 의 web_search, code_execution) 인프라에서 실행됩니다. 우리가 실행 코드를 다루지 않고 결과를 바로 받습니다. 단, 클라이언트 도구와 같은 병렬 그룹에서 호출되면 폴백 로직이 필요합니다.

에이전틱 루프

전형적인 루프는 다음과 같이 돕니다.

  1. 요청에 tools(스키마+설명)를 실어 모델에 보낸다.
  2. 모델이 필요하면 tool_use 블록을 응답한다.
  3. 우리 코드가 그 작업을 실행한다(함수 호출, DB 조회, API, 크롤링 등).
  4. tool_result 로 실행 결과를 다시 모델에 보낸다.
  5. 모델이 최종 답변을 내놓을 때까지 2~4 를 반복한다.

이 루프를 직접 돌리는 대신 Tool Runner(SDK 가 도구를 자동 실행·결과 반환)를 쓰면 왕복 코드를 덜 쓸 수 있습니다.

데이터스케쳐스 실무 예시

  • Neuron(문서 자동화): "이 계약서에서 만료일을 찾아 캘린더에 넣어줘"에서 문서 파싱 → 만료일 추출 → 캘린더 생성 은 클라이언트 도구 루프로 구성합니다. 각 단계 실행(파싱·쓰기)은 우리 코드가 하고, 판단만 모델이 하게 분리하는 게 데이터를 안전하게 다루는 핵심이에요.
  • 이벤트 데이터 수집: 크롤링·저장 같은 "실행"은 우리 쪽(클라이언트)에 두고, "어떤 필드를 뽑을까" 같은 결정만 모델에 맡기는 구조가 일반적입니다.

확인 필요

  • 이벤트 루프는 제품·공급자별로 턴 수 상한, 병렬 폴백, 오류 신호가 다르므로 실제 연동 시 해당 공급자 세부 문서를 다시 확인하세요. (확인 필요)

더 알아보기