AI 에이전트 자격증명 금고 — 못 보는 비밀값·나갈 때 치환·서명은 실패

에이전트에게 외부 서비스 열쇠를 쥐여 줘야 하는 순간이 옵니다. 메신저를 읽게 하든, 사내 서비스를 부르게 하든요.

관리형 에이전트의 금고는 이 문제를 색다르게 풉니다. 열쇠를 맡아 두는 데서 그치지 않고 에이전트에게 진짜 값을 끝까지 안 보여 줍니다. 그 대신 못 쓰는 경우가 생기는데, 그 경계가 이 글의 요점입니다.

📌 30초 요약

• 샌드박스 안에는 가짜 문자열이 들어가고, 나가는 길목에서 바뀝니다.
• 그래서 비밀값으로 서명을 만드는 방식은 못 씁니다.
• 기본은 머리글만. 본문에 토큰을 싣는 쪽은 조용히 깨집니다.
• 금고는 작업공간 범위라, 회수하려면 지우는 수밖에 없습니다.

1. 열쇠를 쥐여 주지 않는 방식

금고 하나는 최종 사용자 한 사람의 자격증명 묶음입니다. 미리 만들어 두고 세션을 시작할 때 번호로만 가리킵니다. 호출할 때마다 토큰을 실어 보낼 필요도, 비밀 저장소를 직접 운영할 필요도 없어집니다. 덤으로 이 에이전트가 누구를 대신해 움직였는지가 기록에 남고요.

자격증명은 두 갈래입니다. 도구 서버용은 서버 주소를 열쇠 이름 삼아 보관되고, 에이전트가 그 주소에 접속하는 순간 자동으로 붙습니다. 승인 절차를 쓰는 서버라면 만료됐을 때 대신 갱신까지 해 줍니다.

흥미로운 쪽은 환경 변수용입니다. 샌드박스에 들어가는 건 아무 뜻도 없는 자리표시자 문자열이고, 에이전트가 바깥으로 요청을 보내는 바로 그 길목에서 진짜 값으로 바꿔칩니다. 에이전트도, 그 안에서 도는 어떤 프로그램도 진짜 값을 보지 못합니다. 넣어 둔 비밀값은 쓰기 전용이라 나중에 조회해도 돌려주지 않고요. 읽기 전용으로 걸어도 키가 새는 문제를 다뤘던 자리에 대한 정면 대답입니다.

2. 그래서 못 쓰는 클라이언트가 있습니다

치환이 샌드박스 밖에서 일어난다는 건 대가를 동반합니다. 샌드박스 안에서 그 값을 읽고 계산에 쓰는 프로그램은 가짜 문자열을 만지게 되니까요.

클라이언트가 하는 일	결과
받은 값을 그대로 실어 보냄	정상 동작 · 이 방식만 지원됩니다
시작할 때 열쇠 형식을 검사	형식이 안 맞다며 스스로 거부
비밀값으로 요청 서명을 계산	가짜 값으로 서명해 상대가 거절

셋째 줄이 특히 걸립니다. 큰 클라우드 저장소들이 쓰는 서명 방식이 여기 해당하는데, 열쇠 자체를 보내는 게 아니라 열쇠로 계산한 값을 보내는 구조라서 그렇습니다. 문서가 이 조건을 미리 확인하고 설정하라고 못 박아 뒀습니다. 또 직접 운영하는 샌드박스에서는 환경 변수 방식이 아직 안 됩니다.

3. 가짜 문자열이 상대에게 그대로 날아갈 때

바꿔치기할 자리는 두 축으로 좁힙니다. 어느 상대에게 바꿔 줄지가 한 축이고, 요청의 어느 부분에서 바꿀지가 다른 축입니다. 둘은 서로 독립이라 따로 설정합니다.

부분은 머리글과 본문 둘뿐인데, 문서가 본문이 더 넓은 노출면이라고 설명합니다. 요청 본문은 에이전트가 다루던 내용으로 조립되는 경우가 많아서입니다. 그래서 대부분의 서비스처럼 머리글에서 열쇠를 읽는다면 머리글만 켜는 쪽이 더 좁은 설정입니다.

⚠️ 화면에서 만들면 머리글만 켜집니다

관리 화면으로 자격증명을 만들면 머리글 주입만 켜진 채로 생깁니다. 그런데 본문에 토큰을 실어 보내는 클라이언트가 적지 않습니다 — 양식 형태로 토큰을 요청하는 방식이 대표적이고요.

이때 가짜 문자열이 치환도 제거도 안 된 채 그대로 전송되고, 상대 서비스는 자기 쪽 인증 오류를 냅니다. 우리 쪽 설정이 원인인데 남의 서비스가 고장 난 것처럼 보인다는 게 함정입니다. 만들 때 본문 주입을 같이 켜거나, 나중에 고쳐 주세요.

덕분에 진단법이 아주 깔끔합니다. 상대가 받은 요청에 가짜 문자열이 그대로 들어 있었다면 원인은 둘 중 하나입니다 — 그 부분이 꺼져 있거나, 목적지가 허용한 상대 목록에 없거나. 그 밖의 경우는 아예 없다고 문서가 단언합니다. 도구 서버를 조직에 배포할 때 머리글에 넣은 열쇠는 비밀이 아니라던 이야기와 정확히 반대편에 있는 장치이기도 합니다.

설정 규칙에 비대칭이 하나 있어 적어 둡니다. 만들 때는 부분을 명시하면 안 적은 쪽이 꺼지고, 통째로 생략하면 둘 다 켜집니다. 고칠 때는 적은 것만 바뀌고 나머지는 그대로고요. 둘 다 끄는 요청은 거절되고, 비워 두겠다고 빈 값을 보내는 것도 거절됩니다. 「그 필드를 아예 빼라」는 게 답입니다.

4. 넣은 뒤에 바꾸고 지우기

가장 반가운 성질은 돌고 있는 세션을 재시작하지 않아도 된다는 점입니다. 자격증명은 세션 도중에도 주기적으로 다시 확인되기 때문에, 값을 바꾸거나 치우거나 지운 것이 그대로 굴러가는 세션에 전파됩니다. 승인 절차를 쓰는 자격증명은 이 시점에 만료된 토큰도 같이 갱신됩니다.

처리	무슨 일이 일어나나
값 교체	비밀값·표시 이름·주입 부분만 변경 · 재시작 없이 반영
치워 두기	비밀값은 파기 · 기록은 감사용으로 남음 · 열쇠 이름은 재사용 가능
완전 삭제	기록까지 사라짐 · 감사 흔적이 필요하면 쓰지 말 것

금고를 치우면 앞으로의 세션은 실패하지만 이미 도는 세션은 계속 갑니다. 그리고 열쇠 이름 자체는 만든 뒤에 못 바꿉니다. 서버 주소나 환경 변수 이름을 고치려면 치워 두고 새로 만드는 수밖에 없습니다. 금고 하나에 스무 개까지, 같은 열쇠 이름을 두 번 넣으면 거절되고요.

치워지거나 지워지거나 갱신에 실패했을 때 알림을 받을 수도 있습니다. 다섯 가지 사건에 통지를 걸어 둘 수 있는데, 그중 갱신 실패가 실무에서 제일 자주 볼 항목입니다. 사용자가 승인을 철회하면 여기로 떨어지니까요. 세션 단위로 붙는 비용과 상한은 에이전트 요금 상한의 함정에서 따로 다뤘고, 도입 순서를 잡는 중이라면 AI 도입 한 바퀴를 모아 둔 글을 같이 보시면 좋습니다.

자주 묻는 질문 (FAQ)

Q. 잘못된 열쇠를 넣으면 바로 알 수 있나요?

아닙니다. 넣을 때는 검사하지 않고 받은 그대로 보관하고, 세션이 실제로 돌 때 처음 드러납니다. 게다가 그 오류가 세션을 멈추지도 않습니다. 오류만 밖으로 알리고 에이전트는 계속 일합니다. 그래서 「돌긴 돌았는데 결과가 이상한」 형태로 나타나기 쉽습니다.

Q. 맞는 자격증명이 없으면 연결이 막히나요?

막지 않습니다. 서버 주소가 일치하는 게 없으면 인증 없이 그냥 붙어 봅니다. 상대가 인증을 요구하는 서버라면 그때 오류가 나고요. 반대로 금고를 여러 개 붙였는데 같은 주소가 겹치면 먼저 찾은 쪽이 이깁니다. 순서에 기대는 설정은 피하는 게 좋습니다.

Q. 갱신이 실패했다는 알림을 받으면 뭘 해야 하나요?

진단용 호출이 따로 있습니다. 답이 세 가지로 떨어집니다 — 멀쩡함이면 손댈 게 없고, 무효면 권한이 사라졌다는 뜻이라 사용자에게 다시 승인을 받아야 하고, 알 수 없음이면 상대 서버가 잠깐 흔들린 것이니 기다렸다 재시도하면 됩니다. 실패한 악수 단계까지 같이 돌려줍니다.

Q. 금고에 넣으면 조직 안에서도 안전해지나요?

여기는 오해하기 쉬운 대목입니다. 금고는 작업공간 범위라, 그 작업공간에 닿는 열쇠를 가진 사람이면 누구나 세션을 만들며 가리킬 수 있습니다. 값을 읽지는 못해도 쓸 수는 있다는 뜻입니다. 그리고 한번 내준 접근을 되돌리는 방법은 금고나 자격증명을 지우는 것뿐입니다.

정리하면

• 에이전트는 가짜 문자열만 만집니다.
• 서명을 계산하는 방식은 쓸 수 없습니다.
• 가짜 문자열이 상대에게 닿았다면 부분이나 상대 목록입니다.
• 회수는 지우는 것뿐이라는 점을 기억하세요.

※ 공개된 안내 문서를 읽고 정리했습니다. 필드 이름·설정 항목·명령은 우리말로 풀어 적었고, 직접 금고를 만들어 돌려 보지는 않았습니다.

※ 이 기능은 베타 단계이며 전용 표시를 붙여 호출해야 합니다. 개수 제한·지원 범위·직접 운영 샌드박스에서의 제약은 열람 시점 기준이라 바뀔 수 있습니다. 실제로 붙이기 전에 쓰려는 클라이언트가 열쇠를 어떻게 실어 보내는지부터 확인하세요.