AI가 쓸 도구는, 만드는 것보다 깎는 게 일이었다

Table of contents

들어가며

AI에게 일을 시키려면 바깥세상과 연결해주는 도구가 필요하다.

이번에 나는 opsgate라는 작은 도구를 만들었다.

opsgate는 서버, 데이터베이스, 로그, 지표처럼 운영 중에 자주 들여다봐야 하는 것들을 대신 조회해주는 중간 서버다. AI가 직접 접속하는 대신, opsgate가 API나 SQL을 호출하고 결과만 돌려준다.

비밀번호나 API 토큰 같은 접속 정보는 opsgate 안에만 있다. AI에게는 보이지 않는다.

다만 이 글에서 더 이야기하고 싶은 건 비밀키를 숨긴 구조 자체보다, 그렇게 가져온 결과를 AI에게 어떻게 돌려줬는가다.

실제로 만들어보니 기본 기능은 금방 만들었다. 요청을 받고, 대신 조회하고, 결과를 돌려주는 것 자체는 어렵지 않았다. 진짜 시간을 잡아먹은 건 따로 있었다.

AI에게 결과를 어떻게 돌려줄 것인가.

결국 AI가 쓸 도구를 만든다는 건 기능을 붙이는 일이 아니라, AI가 다음 요청을 잘할 수 있도록 응답을 계속 깎는 일에 가까웠다.

새 사용법을 만들지 않았다

도구를 만들 때 처음부터 정한 방향이 있었다. 모델에게 새로운 사용법을 많이 가르치지 말자는 것이다.

ChatGPT나 Claude 같은 모델은 완전히 낯선 명령어보다, 개발자들이 자주 쓰는 형식에 더 잘 반응한다. API 호출, 로그 조회, 지표 조회, SQL 같은 것들은 이미 공개 문서와 예제가 많고, 실제 개발 환경에서도 흔히 쓰인다.

그래서 opsgate도 별도의 전용 명령어를 계속 늘리는 쪽으로 만들지 않았다. “문제 있는 앱 찾아줘” 같은 기능을 하나씩 감싸기보다, 모델이 익숙한 API나 SQL 형태에 가깝게 부를 수 있게 뒀다.

내가 손댄 건 돌려주는 쪽이었다. 그대로 부르게 하되, 돌아오는 결과가 쓸데없이 커지지 않게 줄이고, 모델이 다음 요청을 이어갈 수 있게 힌트를 붙였다.

정리하면, 부르는 법은 모델에게 맡기고, 돌려주는 법만 깎았다. 이게 이 도구의 기본 방향이었다.

AI는 방금 받은 응답에 묶여 있다

사람은 도구를 쓰다가 막히면 주변을 본다. 문서를 찾아볼 수도 있고, 화면을 훑을 수도 있고, 에러 메시지를 보고 대충 감을 잡을 수도 있다. 필요하면 “아, 이건 내가 잘못 눌렀네” 하고 돌아간다.

AI는 도구를 쓸 때 방금 받은 응답에 훨씬 더 묶인다. 그 응답을 보고 다음 행동을 정한다. 응답에 없는 정보는 모르고, 응답이 잘렸는지·그게 원본의 일부인지 전체인지도 알려주지 않으면 알 수 없다. 잘못된 요청이 왜 틀렸는지도 설명해주지 않으면 같은 방향으로 다시 시도한다.

그래서 AI용 도구의 응답은 단순한 결과값이 아니다. 그 응답은 AI의 다음 행동을 정하는 안내문이라고 생각한다.

AI는 한 번에 정답을 찾는 게 아니라, 도구와 계속 주고받으며 답에 가까워진다. 그러니 한 번에 모든 걸 던지는 게 아니라, AI가 다음 한 걸음을 잘 고를 수 있게 돌려줘야 한다. 내가 실제로 깎은 것도 전부 이 기준에서 나왔다.

무엇을 깎았나

붙여 써보며 부딪힌 문제는 거의 응답에서 나왔다.

너무 많이 주지 않기

가장 먼저 부딪힌 문제는 응답 크기였다.

인프라 도구의 응답은 쉽게 커진다. 서버 목록, 배포 상태, 로그, 지표 같은 것들은 그대로 가져오면 금방 커진다.

사람이야 긴 결과를 받아도 검색해서 필요한 줄만 볼 수 있다. 하지만 AI에게 큰 결과를 그대로 주면 비용이 늘고, 느려지고, 중요한 정보가 묻히고, 모델이 엉뚱한 부분에 주목할 수 있다.

실제로 서버 상태 목록을 그대로 가져오면 양이 꽤 컸다. 하지만 AI가 실제로 필요로 한 건 전체 목록이 아니었다. 대부분은 “문제 있는 항목이 있는지”, “몇 개가 있는지”, “특정 상태인 것만 무엇인지” 정도면 충분했다.

그래서 opsgate는 전체를 그대로 넘기지 않고, 필요한 부분만 골라 돌려줄 수 있게 했다. 전체 목록 대신 문제 있는 항목만, 전체 로그 대신 조건에 맞는 일부만, 전체 지표 이름 대신 개수나 필요한 이름만.

여기서 느낀 게 있다. AI용 도구는 “얼마나 많은 정보를 줄 수 있나”보다 얼마나 필요한 정보만 줄 수 있나가 더 중요하다.

잘렸으면 잘렸다고 말하기

처음에는 응답이 너무 크면 그냥 줄이면 된다고 생각했다. 하지만 그건 위험했다.

AI는 잘린 결과를 받으면 그게 잘린 줄 모를 수 있다. 그러면 일부만 보고 전체를 판단한다. 예를 들어 로그가 중간에 잘렸는데 “에러가 없다”고 판단할 수도 있고, 목록이 일부만 왔는데 “이게 전부”라고 생각할 수도 있다.

그래서 opsgate는 응답이 너무 클 때 그냥 조용히 잘라서 주지 않게 했다. 대신 “원본이 너무 컸고, 그래서 그대로 내보내지 않았으며, 다음에는 이렇게 좁혀서 다시 요청하면 된다”고 알려준다.

이건 단순한 에러 메시지가 아니라, 다음 요청을 위한 안내다. AI는 이 응답을 보고 “전체를 다 줘”에서 “문제 있는 항목만 줘”로 요청을 바꾼다.

막을 때도 다음 행동을 알려주기

AI는 가끔 틀린 요청을 보낸다. 허용되지 않은 동작을 하려 하거나, 정책상 막힌 경로를 호출하려 하기도 한다. 이건 당연히 막아야 한다.

하지만 그냥 “안 됨”이라고만 하면 부족하다. AI는 왜 안 됐는지 모르면 같은 방향으로 다시 시도한다. 그래서 막힌 요청에도 설명이 필요하다.

나쁜 응답은 여기서 끝난다.

안 됨.

좋은 응답은 다음 행동을 만든다.

이 요청은 허용되지 않는다. 먼저 허용된 동작을 확인하고, 그 안에서 다시 요청해라.

막는 것도 결국, AI가 다음에 제대로 요청하게 만드는 일이었다.

붙여 써보면서 알게 됐다

이런 것들을 처음부터 다 알고 만든 건 아니다.

처음에는 하나의 AI 도구에 붙여서 써봤다. 그때 바로 문제가 보였다. 응답이 너무 컸고, AI는 큰 응답 속에서 필요한 값을 찾느라 헤맸다. 어떤 경우에는 잘린 결과를 보고도 그게 전부인 것처럼 판단하려 했다. 그래서 응답을 줄이는 기능과 다시 요청하는 힌트를 넣었다.

그다음에는 다른 AI에도 붙여봤다. 여기서는 인증 쪽에서 문제가 생겼다. 흥미로웠던 건, 그 문제를 찾는 데 opsgate 자신을 다시 썼다는 점이다.

여기서 특별한 기능이 있었던 건 아니다. opsgate는 로그 서비스를 대신 조회할 수 있고, opsgate 자신의 로그도 그 로그 서비스에 쌓인다. 그래서 평소처럼 로그를 조회했더니, 그 안에 opsgate 자신의 기록도 있었다. 어떤 요청이 들어왔고 어디서 막혔는지 확인했고, 문제를 고친 뒤 정상 동작하는 것도 같은 방식으로 확인했다.

이 경험이 흥미로웠다. 인프라를 보는 도구가, 그 인프라의 일부였기 때문에 자기 기록까지 같은 방식으로 볼 수 있었다.

아직 자동으로 고치는 단계는 아니다. 하지만 최소한 “보고, 원인을 좁히고, 다음 행동을 제안하는” 흐름은 가능하겠다는 감이 왔다.

마무리

핵심 기능은 빨리 끝났다. 요청을 받고, 정책을 확인하고, 대신 호출하고, 결과를 돌려준다. 그 정도는 어렵지 않았다. 길었던 건 그다음, 그 결과를 AI가 잘 쓰도록 다듬는 일이었다.

그래서 지금 와서 보면, opsgate를 만든 일은 “도구를 구현한 일”이라기보다 “AI가 쓸 수 있게 도구의 응답을 다듬은 일”에 가까웠다. 사람이 쓰는 도구라면 대충 보여줘도 알아서 해석하지만, AI가 쓰는 도구는 응답 자체가 다음 행동을 이끌어야 한다. 기능은 도구를 작동하게 만들고, 깎인 응답은 AI가 그 도구를 제대로 쓰게 만든다.

opsgate를 만들면서 배운 건 이거다.

AI가 쓸 도구는 만드는 것보다, 깎는 게 일이었다.

opsgate 소스 코드: github.com/cagojeiger/opsgate

이 글은 opsgate를 실제 AI 도구에 연결해 써보며 겪은 일을 바탕으로 정리했다.