AI 루프 엔지니어링의 도구란? API 연결부터 권한·오류 처리까지

AI 루프 엔지니어링의 도구란? API 연결부터 권한·오류 처리까지#

“오늘 일정을 요약해 이메일로 보내 줘.” 문장 자체는 어렵지 않다. 하지만 실제로 일정을 읽으려면 캘린더에 접속해야 하고, 이메일을 보내려면 이메일 서비스의 발송 기능이 필요하다. AI가 메일 본문을 작성하는 능력과 메일을 실제로 보내는 권한은 다른 것이다.

루프에서 도구는 계획을 실제 행동으로 옮기고, 그 행동의 결과를 다시 관찰하게 해 주는 연결점이다. calendar_read(date)는 일정을 조회하고, email_draft(to, subject, body)는 발송 전 초안을 만들 수 있다. 이런 기능은 서비스 API, 파일 처리기, 검색기, 데이터베이스 조회기, 코드 실행 환경 등으로 구현된다.

도구가 늘어나면 AI가 할 수 있는 일도 늘어난다. 동시에 잘못 조회할 자료, 바꿀 수 있는 기록, 실수로 발송할 대상도 늘어난다. 루프 엔지니어링에서는 도구를 능력인 동시에 권한으로 본다.

루프의 한 바퀴에서 도구는 언제 호출되는가#

뉴스 브리핑 업무를 ‘계획 → 실행 → 관찰 → 검증’으로 나누면 도구 호출의 위치가 선명해진다.

1. 계획: 오늘 날짜와 대상 뉴스 소스를 정한다.
2. 실행: 기사 조회 도구를 호출하고 결과를 초안 파일에 저장한다.
3. 관찰: 조회 도구가 기사 0건을 반환했는지, 일부 소스에서 오류가 났는지 확인한다.
4. 검증: 실제 기사 주소가 붙은 항목만 브리핑에 남기고, 승인 없이 외부 발송하지 않는다.

도구는 2단계에서만 의미가 있는 것이 아니다. 도구의 반환값이 3단계의 증거가 되고, 4단계에서는 반환된 출처와 상태가 완료 판단의 근거가 된다. 원고의 ‘검색 → 분석 → 이메일’ 같은 도구 나열 사이에 확인 단계를 넣어야 루프가 된다.

식당 비유로 이해하는 도구 호출#

사용자는 손님처럼 원하는 결과를 말한다. AI는 가능한 메뉴를 확인하고 어떤 기능이 필요한지 결정한다. 도구 호출은 주문서처럼 정해진 입력을 전달한다. 도구가 돌려준 결과는 주문한 요리가 실제로 나왔는지 확인할 자료가 된다.

그러나 메뉴에 없는 음식을 주문할 수 없듯, 도구가 연결되지 않았다면 AI는 이메일을 발송할 수 없다. 또한 “요리가 나왔다”는 보고와 실제 음식의 상태가 같은 것이 아니듯, 도구 호출 성공과 업무 결과의 정확성도 다르다. 일정 조회가 성공했어도 다른 날짜의 일정을 읽었다면 브리핑은 틀린다.

도구와 API·스킬·플러그인의 관계#

말	주된 의미	예
API	프로그램이 다른 서비스에 정해진 방식으로 요청하는 통로	캘린더 일정 조회 API
도구	AI 시스템이 호출할 수 있도록 노출된 기능	get_today_events
스킬	특정 작업을 수행하기 위한 지침이나 기능 묶음	일정 읽기·형식화·오류 안내를 묶은 처리 방식
플러그인·커넥터	서비스 기능을 제품에 연결하는 구성 요소	메일 계정 연결

제품마다 이름과 구현 방식이 다르다. 원고에서 이를 모두 같은 것으로 부르는 부분은 혼란을 줄 수 있다. 사용자가 확인해야 할 공통 요소는 어떤 자료를 읽고, 어떤 행동을 하며, 실패하면 무엇을 반환하는지다.

‘도구를 여러 개 연결하면 곧 에이전트가 된다’고 생각할 필요도 없다. 정해진 순서로 도구를 호출하는 자동화 워크플로에도 같은 계약이 필요하다. AI가 다음 도구를 선택하는 경우에는 반환값과 오류 설명이 더 중요해진다.

좋은 도구는 ‘계약서’가 분명하다#

사내 지식 문서 검색 도구를 만든다고 하자. 이름만 search라면 AI는 인터넷 전체를 검색하는지, 내부 승인 문서만 검색하는지 모른다. 결과도 문서 원문인지 일부 발췌인지 알 수 없다.

도구 계약은 다섯 가지를 적어야 한다.

계약 요소	설계 질문	문서 검색 예
목적	왜 호출하는가	승인된 사내 문서에서 답의 근거 찾기
입력	무엇을 어떻게 받는가	검색어, 접근 범위, 최대 반환 수
권한	무엇을 읽고 바꿀 수 있는가	허용 문서 읽기만 가능
반환	무엇을 돌려주는가	발췌, 원문 위치, 갱신일
오류	실패를 어떻게 표현하는가	빈 결과·권한 거부·시간 초과 구분

다음은 제품에 종속되지 않는 설계 예시다. 실제 도구 설정 문법은 연결 서비스에 따라 다르다.

name: approved_kb_search
purpose: 승인된 사내 문서에서 근거 찾기
input:
  query: 검색할 질문
  scope: 허용된 문서 영역
  max_results: 반환 건수 상한
permission: 읽기 전용
returns:
  - 발췌문
  - 문서 식별값과 위치
  - 문서 갱신일
errors:
  no_result: 검색 결과 없음
  access_denied: 권한 부족
  timeout: 검색 시간 초과
side_effect: 없음

‘검색 결과 없음’과 ‘권한 부족’을 같은 빈 목록으로 반환하면 AI가 결과가 없다고 오해한다. 반대로 빈 결과를 정상 응답으로 돌려주되 “확인할 근거가 없다”고 표현하도록 하면, 불필요한 추측을 줄일 수 있다.

반환값이 다음 단계의 판단을 바꾼다#

검색 도구가 문장 하나만 돌려주면 AI는 그 문장이 언제 작성되었는지, 어느 문서에서 왔는지 알기 어렵다. 같은 문장에 문서 위치, 날짜, 접근 범위를 붙이면 검증이 가능해진다.

예를 들어 고객 환불 규정을 찾았을 때:

발췌: 개봉 후 환불 가능 여부는 상품 유형에 따라 다름
출처: 고객정책/환불규정/상품유형
갱신일: 문서에 표시된 날짜
상태: 조회 성공

이 결과는 AI가 고객에게 무조건 “환불 가능합니다”라고 답할 근거가 아니다. 해당 상품 유형을 확인해야 한다는 다음 작업의 입력이다.

아침 일정 브리핑에 필요한 도구를 분해해 보자#

목표는 매일 아침 오늘의 일정을 요약해 본인에게 전달하는 것이다.

1. 예약 트리거가 정해진 시각에 작업을 시작한다.
2. 캘린더 읽기 도구가 오늘 일정과 시간대를 반환한다.
3. AI가 겹치는 일정이나 장소 정보를 정리한다.
4. 검증 단계가 날짜와 일정 건수를 원본 응답과 대조한다.
5. 이메일 초안 도구가 결과를 임시 저장한다.
6. 사용자 승인 뒤 발송 도구를 실행하고 결과를 기록한다.

처음에는 1~5단계만 만든다. 초안이 안정적으로 생성되는지 확인한 뒤에 발송을 연결한다. AI의 문장 생성 품질과 도구의 전달 성공을 각각 확인할 수 있기 때문이다.

도구가 많을수록 좋은가#

메일 읽기·보내기·삭제, 캘린더 읽기·수정, 파일 읽기·덮어쓰기, 웹 검색까지 한꺼번에 연결하면 선택지는 풍부해진다. 그러나 ‘이 업무에서 사용하면 안 되는 도구’를 통제하기도 어려워진다.

일정 브리핑에는 캘린더 읽기와 초안 작성으로 시작할 수 있다. 받은 메일 삭제나 캘린더 일정 수정 권한은 필요 없다. 도구를 적게 두면 장애가 발생했을 때 어느 호출이 문제였는지도 추적하기 쉽다.

읽기와 쓰기는 별도의 위험이다#

행동	가능한 일	운영 기준
읽기	일정·문서·데이터 조회	허용 범위와 민감정보 범위 확인
초안 쓰기	새 임시 문서 생성	저장 위치와 공유 범위 지정
기존 기록 수정	일정·고객 정보 변경	변경 전 값 기록, 승인 또는 검토
외부 발송	고객·팀에 메시지 전송	수신자·본문 확인과 발송 결과 기록
삭제·결제	되돌리기 어려운 행동	더욱 엄격한 승인과 실행 제한

프롬프트의 “승인받으라”는 문구만으로 권한이 제한되지는 않는다. 가능한 경우 시스템도 승인 없이는 해당 도구를 실행하지 못하게 해야 한다.

도구가 실패했을 때 AI는 무엇을 해야 할까#

흔한 실패는 세 종류다.

빈 결과#

정상적으로 검색했지만 오늘 일정이 하나도 없다. 이때는 ‘일정 없음’이 정확한 결과다. AI가 예전에 나온 일정을 가져와 채우면 오류다.

권한 거부#

캘린더에 접속하지 못했다. ‘일정 없음’과 다르다. 업무를 보류하고 접근 권한을 확인해 달라고 해야 한다.

시간 초과·일시 장애#

서비스가 응답하지 않았다. 일정한 간격과 횟수로 재시도할 수 있지만, 반복해 실패하면 중단해야 한다. 이미 이메일을 보낸 뒤 발송 응답만 유실된 상황이라면 재시도 전에 발송 기록을 확인해야 중복 메일을 막을 수 있다.

기록할 것은 무엇인가#

‘어떤 도구를 언제 호출했는가’뿐 아니라 어떤 업무 실행을 위해 호출했고 어떤 상태를 반환했는가를 남긴다. 오류 분석에는 입력 값의 전체 사본이 불필요할 수 있다. 개인정보나 비밀키는 로그에 그대로 남기지 않고, 필요한 식별 정보만 기록한다.

업무 ID: weekly-report-2026w39
도구: approved_kb_search
입력 범위: 영업팀 승인 문서
상태: access_denied
다음 처리: 담당자에게 접근 권한 요청

도구 연결 전에 만들어 볼 한 장짜리 계약서#

도구 이름:
해결할 업무:
호출하는 상황:
필수 입력과 형식:
읽을 수 있는 자료:
수정할 수 있는 자료:
정상 반환값과 출처:
빈 결과의 의미:
권한 거부 시 행동:
일시 장애 시 재시도 횟수:
사람 승인 필요 여부:
로그에 남길 항목:

이 계약서를 채우기 어렵다면 새 도구를 붙이기 이르다. 도구가 무엇을 할 수 있는지보다, 무엇을 했는지 확인하고 실패 후 어디로 돌아갈 수 있는지가 두 번째 부품의 핵심이다.

트리거에서 부여한 업무 ID를 도구 로그와 연결하고, 도구가 만든 파일은 다음 글의 작업 공간에 저장한다. 그러면 도구 호출이 끝난 뒤에도 이번 루프의 중간 결과를 다시 확인할 수 있다.