먼저 답부터 말씀드리면, 반복적인 검색·파일 조회·필터·집계는 Programmatic Tool Calling(PTC)의 후보가 될 수 있습니다. 반면 환불, 권한 변경, 외부 발송, 데이터 수정처럼 되돌림과 책임 확인이 필요한 일은 생성된 JavaScript의 허용 목록과 분리하고, 검증·승인·기록이 남는 별도 경로로 두는 편이 안전합니다.
AI 에이전트가 도구를 여러 번 호출하는 업무를 운영하다 보면 같은 질문이 생깁니다. “호출을 코드로 묶으면 빨라질 텐데, 어디까지 맡겨도 될까?” 이 글은 그 경계를 정하는 실무용 결정표입니다. 핵심은 자동화의 양이 아니라 읽기와 변경을 같은 권한으로 취급하지 않는 것입니다.
핵심 요약
- PTC는 반복되는 도구 호출의 중간 결과를 생성 JavaScript에서 필터·집계해 모델에 간결하게 돌려주는 방식입니다.
- 허용 도구는 읽기·검색·집계부터 좁게 시작하고, 입력 형식·호출 횟수·반환 크기를 계약으로 고정해야 합니다.
- 금액, 권한, 외부 메시지, 데이터 변경은 별도 검증과 사람이 이해할 수 있는 승인 단계를 거친 뒤 명시적으로 실행해야 합니다.
- 도입 판단은 “병렬 호출이 됐는가”가 아니라 빈 결과·부분 실패·권한 거부·재시도에서도 통제가 유지되는가로 해야 합니다.
PTC가 바꾸는 것은 무엇인가요?
OpenAI의 공식 문서에서 Programmatic Tool Calling은 애플리케이션이 사용할지와 eligible tool을 결정하고, 모델이 생성한 프로그램이 격리된 V8 런타임에서 도구 호출을 조정하는 흐름으로 설명합니다. 여러 번의 조회 결과를 그대로 대화에 쌓기보다, 프로그램이 필요한 값만 추려 집계한 뒤 모델에 전달할 수 있다는 점이 핵심입니다.
다만 이 구조는 업무 책임을 없애는 장치가 아닙니다. 생성 코드가 도구를 조정할 수 있다는 사실과, 그 코드가 외부 변경을 독립적으로 승인해도 된다는 뜻은 다릅니다. 특히 권한·금액·고객 접점·원본 데이터가 걸린 작업은 실행 전후에 사람이 판단할 수 있는 제어점을 남겨야 합니다.
업무를 세 구간으로 나누는 결정표
새 도구를 허용 목록에 넣기 전에는 “이 도구가 무슨 일을 하는가”보다 “성공해도 외부 상태가 달라지는가”를 먼저 물어보세요. 아래 표는 첫 분류에 쓸 수 있습니다.
| 업무 유형 | PTC 처리 여부 | 필수 제어 | 차단·승인 조건 | 예시 |
|---|---|---|---|---|
| 읽기·검색·집계 | 우선 후보 | 도구별 입력 스키마, 호출 횟수, 반환 크기 제한 | 민감 필드가 포함되면 마스킹 또는 중단 | 최근 문의 검색, 상태별 건수 집계 |
| 검증 후 실행 | 제한적으로 가능 | 사전 조건 검사, 대상 미리보기, 실행 결과 확인 | 검증 실패·대상 불명확 시 실행하지 않음 | 형식이 맞는 초안 생성 요청 준비 |
| 사람 승인 후 변경 | 별도 경로 | 승인 화면, 실행 주체, 변경 전후 기록, 되돌리기 절차 | 금액·권한·외부 발송·데이터 수정이면 항상 분리 | 환불 처리, 계정 권한 부여, 고객 메시지 발송 |
판단 기준은 비용과 신뢰성에도 연결됩니다. 조회·집계는 좁은 반환값으로 모아 모델이 다시 읽어야 할 양을 줄일 수 있습니다. 반대로 잘못된 외부 변경은 호출 한 번의 절약보다 복구·설명·고객 대응 비용이 더 커질 수 있습니다. 그래서 변경 도구를 허용 목록에 넣기 전에 책임 경계를 먼저 정해야 합니다.
도구 계약 카드에 적을 항목
“사용 가능”이라는 한 줄만으로는 운영하기 어렵습니다. 각 도구에 아래처럼 짧은 계약 카드를 두면, 생성 코드가 어떤 범위에서 움직여야 하는지 팀이 함께 검토할 수 있습니다.
| 항목 | 질문 | 예시 기준 |
|---|---|---|
| 허용 목적 | 왜 이 도구가 필요한가요? | 고객 문의의 주제별 건수만 집계 |
| 입력 검증 | 어떤 값만 받을 수 있나요? | 기간, 상태, 익명화된 분류값만 허용 |
| 호출·반환 한도 | 얼마나 많이 호출·반환할 수 있나요? | 한 작업당 호출 수와 결과 항목 수를 제한 |
| 민감정보 | 무엇을 제외하거나 가려야 하나요? | 이메일·전화번호·결제 식별자는 결과에서 제거 |
| 실패 요약 | 실패하면 운영자에게 무엇을 보여 주나요? | 성공·빈 결과·권한 거부·부분 실패를 구분 |
예시: 고객 문의는 집계하고, 환불과 권한 변경은 분리합니다
예를 들어 운영팀이 “이번 주 배송 지연 문의의 흐름을 정리해 달라”고 요청했다고 가정해 보겠습니다. 에이전트는 문의를 검색하고, 상태별·주제별로 필터링하고, 요약을 만들 수 있습니다. 이 단계는 원본 레코드를 바꾸지 않는 읽기 작업이므로 범위를 제한한 PTC 후보가 됩니다.
그런데 요약 과정에서 “환불이 필요해 보이는 주문”이나 “관리자 권한이 필요한 계정”이 발견될 수 있습니다. 이때 에이전트가 바로 환불을 실행하거나 권한을 바꾸게 하면 안 됩니다. 대신 대상, 근거, 예상 변경 내용을 사람이 볼 수 있는 요청으로 만들고, 승인된 뒤에만 별도의 변경 도구가 실행되게 구성합니다.
도입 전 체크리스트
- 반복 읽기·검색·필터·집계만 먼저 후보로 분류했나요?
- 각 도구에 입력 형식, 호출 횟수, 반환값 최대 크기를 정했나요?
- 민감정보를 반환 전에 줄이거나 가리는 규칙이 있나요?
- 외부 변경은 검증과 사람 승인 뒤의 명시적 실행 도구로 분리했나요?
- 운영자가 결과와 실패 이유를 보고 다음 조치를 판단할 수 있나요?
켜기 전 확인할 여섯 가지 회귀 시나리오
공식 에이전트 평가 가이드는 대표 업무를 데이터셋과 grader, trace를 통해 비교하는 접근을 제시합니다. PTC도 한 번의 성공 데모보다, 아래처럼 실패와 경계 상황을 고정한 회귀 세트로 확인하는 편이 좋습니다.
| 시나리오 | 기대 동작 | 차단 기준 | 운영자에게 남길 요약 |
|---|---|---|---|
| 단일 조회 | 정해진 입력으로 한 번 조회 | 스키마 밖 입력 | 조회 범위와 결과 수 |
| 병렬 조회 | 서로 독립적인 읽기 도구만 병렬 실행 | 공유 변경 대상 포함 | 도구별 성공·실패 상태 |
| 빈 결과 | 없음을 그대로 반환 | 빈 값을 추정으로 보완 | 조회 조건과 0건 여부 |
| 부분 실패 | 성공 결과와 실패 대상을 분리 | 실패를 숨긴 전체 성공 처리 | 실패 도구와 재확인 필요 항목 |
| 권한 없는 변경 요청 | 변경 도구를 호출하지 않고 승인 경로 제시 | 승인 없이 외부 상태 변경 | 대상·근거·필요 승인 |
| 과대 반환·재시도 | 반환값을 제한하고 중복 변경 없이 중단 | 한도 초과 또는 식별 불가한 재실행 | 잘린 범위와 수동 확인 지점 |
이 여섯 장면에서 통과 기준을 만족하지 못한다면, 더 많은 도구를 붙이기보다 허용 목록을 줄이는 편이 낫습니다. 도입 초기에는 대표 업무 하나에서 결과 요약과 기록이 충분한지 확인한 뒤, 같은 계약을 가진 읽기 도구로만 천천히 확대하세요.
다음으로 함께 보면 좋은 글
자주 묻는 질문
PTC는 모든 도구 호출을 대신하나요?
아닙니다. 반복되는 읽기·검색·필터·집계처럼 범위를 좁게 계약할 수 있는 작업에서 먼저 검토하는 편이 좋습니다. 지원 모델과 도구 범위는 도입 시점의 공식 문서를 확인해야 합니다.
외부 변경 도구를 eligible tool에 넣으면 안 되나요?
변경 자체가 필요할 수는 있지만, 승인·입력 검증·변경 기록·되돌리기 경로를 생성 코드의 편의와 분리해 설계해야 합니다. 특히 금액, 권한, 외부 발송, 데이터 수정은 사람이 검토할 수 있는 명시적 경로를 권합니다.
병렬 처리면 항상 더 좋은 선택인가요?
독립적인 읽기 작업에는 도움이 될 수 있지만, 결과의 순서·부분 실패·반환량·권한 경계를 함께 관리해야 합니다. 공유된 변경 대상이 있으면 병렬화보다 순서와 검증이 우선입니다.
도입 효과는 어떻게 확인하나요?
대표 업무를 정하고, 기존 방식과 PTC 적용 방식을 같은 입력으로 비교하세요. 성공률만 보지 말고 빈 결과, 부분 실패, 권한 거부, 과대 반환에서 운영자가 충분히 판단할 수 있는 기록이 남는지도 확인해야 합니다.
참고 자료
- OpenAI API — Programmatic Tool Calling: 기능의 실행 흐름, eligible tool, 격리 런타임 설명을 확인할 수 있습니다.
- OpenAI Agents SDK — Tools: ProgrammaticToolCallingTool의 SDK 수준 사용 범위를 확인할 수 있습니다.
- OpenAI API — Changelog: 기능 및 문서 변경 여부를 도입 시점에 다시 확인할 수 있습니다.
- OpenAI API — Evaluate agent workflows: 대표 업무와 실패 시나리오를 평가로 비교하는 방법을 확인할 수 있습니다.
이 글이 마음에 드세요?
FLOWIT on YouTube
영상으로도 FLOWIT을 이어서 보세요
AI 자동화, Claude Code, n8n, 데이터 분석 흐름을 블로그와 영상으로 함께 정리하고 있습니다.
Related Notes
같이 읽으면 좋은 FLOWIT 글
8월 26일 전에 점검하세요: Assistants API 종료, 대화 상태는 어디에 남겨야 할까Assistants API 종료 전, Thread·Run에 흩어진 대화와 도구 이력을 Responses API로 옮기는 방법을 상태 보존·비용·회귀 검증 기준으로 정리합니다.
AI 에이전트가 실행하기 전: 구조화된 출력에 검증을 넣는 법AI 에이전트의 JSON 출력은 파싱 성공만으로 안전하지 않습니다. 스키마 검증, 업무 규칙, 실패 처리 경로를 나눠 자동화 오류를 막는 최소 설계를 정리합니다.
Claude API 400 오류, adaptive thinking 전환 전 점검할 것Claude API에서 budget_tokens 기반 추론 설정이 400 오류를 낼 때, adaptive thinking으로 안전하게 전환하는 방법을 정리합니다. 호출 목록, 대표 작업 검증, effort 기준, 되돌리기…