API가 수십 개라면 전부 모델 문맥에 넣기보다 요청에 맞는 소수만 검색해 주는 편이 낫습니다. 다만 검색 결과를 곧 실행 권한으로 취급해서는 안 됩니다. 레지스트리는 선택지를 줄이는 색인이고, 권한, 승인, 입력 검증은 실제 실행 경계에서 별도로 유지해야 합니다.
에이전트 스킬 레지스트리는 도구 이름, 설명, 입력 스키마와 권한 메타데이터를 모으고 사용자 의도에 맞는 상위 후보만 런타임에 제공합니다. MCP나 함수 호출은 선택된 도구를 모델에 전달하는 형식이 될 수 있지만, 레지스트리의 검색, 승인 정책 자체를 대신하지는 않습니다.
배송 조회, 교환, 환불 API 150개를 매 요청마다 넣으면 토큰이 늘고 비슷한 이름 사이에서 모델이 혼동할 수 있습니다. 레지스트리는 요청을 임베딩하거나 키워드로 검색해 관련성이 높은 k개 도구만 보여 줍니다. 문서 RAG와 비슷하지만 반환물이 실행 가능한 행동이라는 점에서 오탐의 피해가 더 큽니다.
설명만 비슷한 환불 조회와 환불 실행을 구분하려면 BM25와 벡터 검색, 도메인, 동작 유형 필터를 함께 쓰는 편이 좋습니다. 짧고 모호한 요청에서는 바로 실행하지 말고 사용자에게 대상을 확인하거나 안전한 조회 도구만 제공해야 합니다.
일반 사용자에게 관리자 도구를 검색하지 않게 하는 RBAC 필터는 유용합니다. 그래도 클라이언트가 도구 이름을 직접 보내거나 캐시된 스키마를 재사용할 수 있으므로 실제 API 경계에서 사용자 권한, 대상 자원과 입력 값을 다시 검사해야 합니다.
삭제, 환불과 외부 전송에는 검색 점수와 무관한 승인 정책이 필요합니다. 도구 메타데이터에 읽기, 쓰기, 되돌릴 수 있는지, 예상 범위와 필요한 승인자를 기록하고 실행 직전에 평가합니다. ‘도구가 모델에게 보이지 않는다’는 것은 보조 방어이지 접근 통제의 전부가 아닙니다.
상위 k를 너무 작게 잡으면 필수 도구가 빠지고, 크게 잡으면 원래의 컨텍스트 과다가 돌아옵니다. 정답 도구가 알려진 실제 문의를 모아 top-1과 top-k 재현율, 잘못 선택된 위험 도구, 검색 지연과 주입 토큰을 기록해야 합니다. 복합 업무는 필요한 도구 집합 전체가 검색됐는지도 봅니다.
‘환불’처럼 여러 단계를 가진 작업은 결제 취소, 재고 복구와 알림을 모델이 임의 순서로 조립하게 두기보다 검증된 복합 스킬로 묶을 수 있습니다. 이 경우에도 각 단계의 부분 실패, 재시도와 보상 동작을 상태 머신에서 관리해야 합니다.
백엔드 파라미터가 바뀌고 레지스트리만 오래되면 모델은 낡은 입력으로 요청합니다. OpenAPI 같은 원본 스키마의 버전과 레지스트리 항목을 결속하고, 호환되지 않는 변경은 해당 스킬을 비활성화한 뒤 회귀 테스트를 통과해야 다시 노출하도록 합니다.
첫 도입은 한 도메인의 조회 API 10개로 제한하세요. 정상 질문뿐 아니라 모호한 질문, 권한 없는 사용자, 오래된 스키마와 검색 서버 장애를 시험합니다. 전체 도구 주입 방식보다 성공률과 비용이 나아지고 실행 경계의 권한 검사가 독립적으로 작동할 때 레지스트리를 넓히는 것이 맞습니다.
이름과 자연어 설명만으로는 운영하기 어렵습니다. 입력, 출력 스키마, 읽기 또는 쓰기 여부, 되돌릴 수 있는지, 필요한 사용자 범위, 예상 지연과 비용, 소유 팀, 계약 버전과 상태 확인 주소가 필요합니다. ‘고객 찾기’와 ‘고객 삭제’가 같은 고객 도메인이라는 이유로 가까이 검색되어도 부작용 메타데이터로 후자를 재정렬하거나 제외할 수 있어야 합니다.
검색은 후보를 넓게 찾는 첫 단계와 정책, 문맥으로 다시 줄이는 두 단계가 실용적입니다. 첫 단계에서는 키워드와 벡터 검색으로 재현율을 확보하고, 두 번째에서는 현재 테넌트, 사용자 역할, 요청한 동작과 스키마 호환성을 반영해 재정렬합니다. 최종 후보의 이름이 비슷하거나 점수 차이가 작으면 추측 실행 대신 선택 이유를 보여 주고 확인 질문을 합니다.
예상 지연과 비용은 최적화용 장식 정보가 아닙니다. 같은 결과를 내는 도구가 둘이라면 빠르고 저렴한 조회를 먼저 쓰고, 대량 내보내기처럼 오래 걸리는 작업은 비동기 실행으로 전환할 수 있습니다. 응답 시간 상한이 짧은 대화에서 느린 도구가 선택되면 모델 호출 자체는 성공해도 사용자 경험은 실패합니다.
일반 문서 검색의 오탐은 잘못된 답변으로 끝날 수 있지만 도구 검색의 오탐은 실제 상태를 바꿉니다. 평가 세트에는 정답 도구만 넣지 말고 절대 선택하면 안 되는 부정 후보를 함께 표시해야 합니다. ‘지난달 환불 내역을 보여 줘’에 refund.list는 맞지만 refund.create와 refund.cancel은 위험한 오탐입니다.
모호한 ‘환불 처리해 줘’에는 주문 ID, 금액과 취소 범위를 확인하기 전 쓰기 도구를 노출하지 않는 정책을 둘 수 있습니다. 조회 결과를 바탕으로 변경 계획을 만든 다음 사용자가 확인한 짧은 승인 토큰을 실행 요청에 붙입니다. 승인 토큰은 사용자, 대상, 도구, 입력 해시와 만료 시각에 결속해야 다른 작업에 재사용되지 않습니다.
도구 설명 안의 예시도 회귀 테스트 대상입니다. 긍정 예시만 많으면 범용 도구가 모든 질문에 검색될 수 있습니다. 가까운 경쟁 도구와 구분되는 조건, 선택하지 말아야 할 표현과 필요한 전제를 함께 기록하세요. 설명 변경 뒤에는 기존 질의의 순위와 위험 오탐이 어떻게 달라졌는지 비교합니다.
모델은 먼저 도구 이름, 정규화된 입력과 예상 부작용을 담은 계획을 만들고 정책 엔진은 이를 검사합니다. 읽기 작업은 자동 승인할 수 있지만 대량 변경과 외부 전송은 사람에게 diff나 대상 수를 보여 줍니다. 실행 API는 레지스트리에서 왔는지와 무관하게 인증된 주체와 정책 결정을 요구해야 합니다.
같은 요청이 네트워크 재시도로 두 번 실행되지 않도록 쓰기 도구에는 idempotency key를 전달합니다. 부분 성공이 가능한 복합 스킬은 각 단계의 상태와 보상 동작을 저장하고, 모델의 대화 기록을 트랜잭션 로그 대신 사용하지 않습니다. 도구 호출 결과가 민감하면 모델에 반환할 필드도 최소화해야 합니다.
사용자가 도구 이름을 직접 보내거나 이전 응답에서 본 스키마를 재사용해도 같은 검사를 통과해야 합니다. 검색은 ‘무엇을 보여 줄지’, 정책 엔진은 ‘무엇을 계획할 수 있는지’, 도구 서버는 ‘지금 이 주체가 실제로 실행할 수 있는지’를 담당합니다. 세 계층의 로그에 공통 요청 ID를 남기면 오선택 원인을 추적할 수 있습니다.
평가 질의는 짧은 명령, 긴 자연어, 오타, 동의어, 권한 없는 요청과 여러 도구가 필요한 복합 질문을 섞습니다. top-1 정확도만 보면 첫 후보가 틀렸지만 안전한 두 번째 후보가 있는 경우와 위험한 쓰기 도구가 1위인 경우를 같게 취급합니다. top-k 재현율, 위험 오탐률, 확인 질문 비율, 최종 업무 성공률과 주입 토큰을 함께 기록하세요.
온라인에서는 검색 p95 지연, 빈 결과, 오래된 스키마 호출, 도구 서버 실패와 사용자가 선택을 수정한 비율을 봅니다. k를 늘려 성공률이 조금 오르더라도 토큰과 오선택이 크게 늘면 이득이 아닙니다. 도메인별 후보 수와 점수 임계값을 다르게 두고, 저신뢰 요청은 전체 도구를 열기보다 안전하게 중단합니다.
복합 질문은 필요한 도구 집합 전체가 후보에 들어왔는지와 실행 순서가 유효한지를 분리해 측정합니다. 결제 취소와 재고 복구가 모두 필요한데 하나만 검색됐다면 top-1이 맞아도 업무는 완료되지 않습니다. 반복되는 복합 업무는 검증된 상태 머신을 하나의 상위 스킬로 등록하는 편이 예측 가능합니다.
레지스트리가 응답하지 않는다고 캐시된 모든 도구를 모델에 넘기는 것은 위험한 fallback입니다. 마지막으로 검증된 읽기 전용 스킬만 짧은 TTL로 캐시하고, 쓰기 도구는 최신 정책과 상태를 확인하지 못하면 닫힌 상태로 실패시키는 편이 낫습니다. 도구 서버별 상태 확인과 circuit breaker를 두어 한 서비스의 지연이 전체 에이전트 시간을 소모하지 않게 합니다.
캐시 키에는 테넌트, 역할, 스킬 계약 버전과 정책 버전을 포함합니다. 권한이 바뀌었는데 이전 검색 결과가 남으면 금지된 도구가 다시 노출될 수 있습니다. 검색 결과를 실행할 때도 버전과 정책을 재검사하고, 비활성화된 스킬이면 새 후보를 찾거나 사용자에게 작업 불가를 설명합니다.
호환 변경이라도 설명과 예시가 달라지면 검색 순위가 변할 수 있습니다. API 계약 테스트와 별도로 고정 질의 세트의 검색 회귀를 실행하고, 새 버전을 일부 트래픽에만 노출해 잘못된 선택과 지연을 비교하세요. 롤백할 때 레지스트리 항목, 실행 어댑터와 문서 예시가 같은 버전으로 돌아가야 합니다.
소유 팀이 없거나 마지막 검증 시각이 오래된 스킬은 기술적으로 호출 가능해도 운영 후보에서 제외하는 것이 낫습니다. 레지스트리는 도구 카탈로그이면서 수명주기 관리 장부입니다. 신규 등록뿐 아니라 폐기, 대체 버전과 오류 문구까지 관리할 때 도구 수가 늘어도 선택 품질을 유지할 수 있습니다.
고정 개수보다 비슷한 도구가 늘어 선택 오류와 문맥 비용이 커지는지가 기준입니다. 한 도메인의 조회 도구부터 전체 주입과 검색 방식의 성공률, 지연을 비교하세요.
아닙니다. 검색 필터는 노출을 줄일 뿐입니다. 실제 도구 서버가 사용자 권한, 대상 자원, 입력 범위와 승인 상태를 독립적으로 다시 검사해야 합니다.
스킬 버전을 원본 API 계약과 묶고 배포 시 호환성, 검색 회귀 테스트를 실행해야 합니다. 오래되거나 상태 확인에 실패한 버전은 검색과 실행에서 제외합니다.
←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.