에이전트 도구 설명 2,279자를 962자로 줄인 기준은 문장 하나였습니다

에이전트에 도구를 붙이면 그 도구의 설명은 호출할 때만 읽히는 것이 아닙니다. 세션이 열릴 때 도구 목록 전체가 한 번에 실립니다. 그 기능을 이번 세션에 한 번도 안 쓰더라도 설명은 그대로 들어갑니다.

내부 프로젝트 관리 도구의 에이전트 연동을 정리하다가 도구 하나의 설명이 2,279자인 것을 봤습니다. 이 연동에 붙은 도구는 44개이고 설명 총량은 약 5천 토큰입니다. 도구 하나가 전체 도구 설명의 23%를 쓰고 있었습니다.

안 쓰는 기능의 설명서를 매 세션이 읽고 갑니다

전체를 44개로 나누면 도구 하나당 평균 225자 정도입니다. 그 도구를 빼고 다시 계산하면 나머지 43개의 평균은 180자 남짓입니다. 한 도구가 나머지 평균의 열 배가 넘는 자리를 쓰고 있었습니다.

그 도구는 고객 안내문을 등록하는 기능입니다. 기능을 배포한 뒤에만 쓰는 도구라 대부분의 세션과는 상관이 없습니다. 그런데도 설명은 접속할 때마다 실립니다. 안내문을 한 번도 만들지 않는 세션이 그 2,279자를 그대로 이고 갑니다.

호출 비용과 설명 비용은 성질이 다릅니다. 호출 비용은 그 기능을 실제로 쓴 세션만 냅니다. 설명 비용은 모든 세션이 나눠 냅니다. 도구가 늘어날수록 이 상시 비용이 조용히 커집니다. 기능을 하나 더 붙일지보다 설명 총량이 얼마인지를 먼저 봐야 하는 시점이 옵니다.

도구 개수 자체를 관리 대상으로 놓고 본 이야기는 따로 정리해둔 적이 있습니다.

자를 기준은 문장 하나로 충분했습니다

줄이기로 정한 뒤에 오래 걸린 것은 방법이 아니라 기준이었습니다. 어디까지가 꼭 있어야 하는 내용인지가 사람마다 달랐습니다. 놓고 볼 수 있는 길은 세 가지였습니다.

채택한 기준은 문장 하나입니다. 이걸 모르면 호출이 실패하는가. 실패하면 남기고, 실패하지 않으면 뺍니다. 알면 좋은 것을 넣기 시작하면 끝이 없습니다. 배경도 사례도 이유도 전부 알면 좋은 것에 들어갑니다.

남긴 것은 전부 계약이었습니다

기준을 대고 한 문단씩 걸러내니 남은 것에 공통점이 있었습니다. 전부 이 도구와 주고받는 계약이었습니다.

금지 구문 — 넣으면 서버가 거부합니다

이미지 참조 문법 — 다른 문법으로 쓰면 이미지가 통째로 안 보입니다

멱등 키가 무엇인지 — 같은 키로 다시 부르면 덮어씁니다

날짜 필드가 작성일이지 업로드일이 아니라는 것

발행하는 도구가 없다는 것 — 등록까지가 이 도구의 끝입니다

발행 중 수정은 즉시 반영되고 버전이 남지 않는다는 것

이 여섯 가지는 몰라서 틀리면 호출이 실패하거나, 호출은 성공했는데 결과가 어긋납니다. 이미지 문법을 다르게 쓰면 안내문은 등록되고 이미지만 통째로 안 보입니다. 날짜 필드를 업로드일로 채우면 저장은 되고 내용이 틀립니다.

뒤쪽 두 항목은 없는 기능을 적어둔 것이라 처음에는 빼려고 했습니다. 그런데 발행 도구가 있는 줄 알면 에이전트가 없는 도구를 찾다가 한 번 더 헛돕니다. 없다는 사실도 계약에 들어갑니다.

걷어낸 쪽이 오히려 좋아졌습니다

걷어낸 것 중 가장 큰 덩어리는 문서에 쓰면 안 되는 표현 네 종류였습니다. 이건 몰라도 호출은 성공합니다. 도구 호출 규칙이 아니라 문서 저작 규칙이기 때문입니다. 호출 규칙과 저작 규칙이 한 설명 안에 섞여 있으면 둘 다 흐려집니다.

그래서 지우지 않고 안내문 작성 스킬로 옮겼습니다. 그 스킬에는 원칙이 이미 있었습니다. 미결정 사항은 빼고, 내부 식별자는 쓰지 않고, 내부 용어는 고객 용어로 바꾼다는 세 줄입니다. 원칙은 있는데 실제 사고에서 나온 구체 문구가 없었습니다.

걷어낸 표현 네 종류를 표로 정리해 그 스킬에 넣었습니다. 원칙 옆에 실제로 사고가 났던 문장이 붙으니 스킬 쪽 문서가 전보다 나아졌습니다. 잘라낸 내용이 다른 문서의 빈칸을 메우는 경우가 생각보다 많습니다. 도구 설명이 길어지는 이유가 대개 갈 곳 없는 지식이 거기 쌓여서입니다.

2,279자가 962자가 됐습니다

정리 결과 설명은 962자가 됐습니다. 58% 줄었습니다. 파싱을 확인했고 연동 테스트 32개가 통과했습니다. 호출에 필요한 계약은 하나도 빠지지 않았습니다.

여기서 한 번 헤맬 수 있는 자리가 있습니다. 도구 서버는 에이전트와 별도 프로세스로 돕니다. 도구 정의는 에이전트가 접속하는 시점에 한 번 읽힙니다. 설명을 고쳐도 서버를 재시작하기 전에는 예전 설명이 그대로 붙어 있습니다. 고쳐놓고 왜 그대로인지 찾느라 시간을 쓰기 쉬운 지점입니다.

이 기준이 안 통하는 자리도 있습니다

이 방식으로 자르면서 걸리는 부분도 같이 적어둡니다.

모르면 실패하는가는 실패 경험이 쌓인 뒤에야 정확해집니다. 새로 만든 도구는 무엇이 실패를 부르는지 모른 채 설명을 씁니다

설명을 줄이면 에이전트가 엉뚱하게 호출하는 빈도가 늘 수 있습니다. 재시도 비용이 아낀 토큰보다 클 수 있어서 줄인 뒤 실패율을 봐야 합니다

이관한 저작 규칙은 그 스킬을 부르는 경로에서만 읽힙니다. 다른 경로로 문서를 만들면 규칙이 안 걸립니다

도구와 스킬에 적어둔 설명 한 줄이 에이전트의 행동 범위를 어디까지 넓히는지는 따로 겪은 적이 있습니다.

도구 설명을 줄이기 전 점검할 것들

전체 도구 설명이 몇 자인지, 그중 상위 한두 개가 몇 %를 쓰는지 먼저 잽니다

문단마다 이걸 모르면 호출이 실패하는가를 물어봅니다

남긴 것이 제약·형식·멱등성·없는 기능 중 하나에 해당하는지 확인합니다

뺀 것은 버리지 말고 갈 문서를 먼저 정합니다

줄인 뒤 한동안 호출 실패율과 재시도 횟수를 봅니다

설명을 고쳤으면 도구 서버를 재시작합니다

마무리

기능을 하나 더 붙이는 일은 눈에 보입니다. 설명 총량이 늘어나는 일은 눈에 안 보입니다. 44개 도구에 붙은 5천 토큰은 누가 정해서 만든 숫자가 아니라 하나씩 붙이다 보니 그렇게 된 숫자입니다.

도구를 붙일 때마다 이 설명이 모든 세션에 실린다는 것을 한 번 떠올리면 무엇을 적을지가 달라집니다. 그 지식이 정말 필요하면 필요한 순간에 해당 문서를 읽게 만드는 길도 있습니다. 도구 설명은 그 지식을 두는 유일한 자리가 아닙니다.