새벽 3시입니다. 당신이 잠든 사이, 에이전트가 지원 티켓 큐를 처리하고 있었습니다. 한 티켓은 에스컬레이션처럼 보이자, 에이전트는 요약본을 작성하여 상사에게 이메일로 보냅니다. 요약은 정확했습니다. 문법은 깔끔했습니다. 문제는 아무도 그 이메일을 요청하지 않았고, 아무도 미리 읽지 않았으며, 에이전트가 보내기로 결정한 순간 아무것도 막을 수 없었다는 것입니다. 에이전트는 지시가 허용하는 대로 정확히 행동했습니다. 이 부분이 당신을 밤새 깨어 있게 해야 합니다.
가장 큰 피해를 주는 실패는 모델이 환각을 일으키거나 프로세스가 충돌하는 실패가 아닙니다. 그러한 실패는 시끄럽고, 시끄러운 실패는 포착됩니다. 위험한 실패는 조용합니다. 에이전트가 지시받은 대로 정확히 행동했는데도 결과가 나빴습니다. 이메일을 보내거나, 기록을 삭제하거나, 주문을 했는데, 모델의 결정과 실제 행동 사이에 아무것도 없었기 때문입니다.
그곳에 있는 것이 바로 가드레일입니다. 가드레일은 행동이 발생하기 전에 검사하여 허용할지, 차단할지, 아니면 먼저 사람에게 물어볼지 결정하는 계층입니다. 이 가이드에서는 구축할 수 있는 네 가지 유형(액션 허용 목록, 승인 게이트, 드라이런 모드, 폭발 반경 제한)과 대부분의 팀이 건너뛰는 단계인 가드레일 작동 증명에 대해 다룹니다. 더 넓은 맥락을 먼저 알고 싶다면, AI 에이전트가 프로덕션에서 실패하는 이유에 대한 저희의 핵심 글에서 에이전트 실패를 다섯 가지 모드로 분류하며, 가드레일 누락이 다섯 번째입니다.
행동을 피해 정도에 따라 분류하기
모든 행동에 게이트가 필요한 것은 아닙니다. 달력을 읽거나, 예측을 가져오거나, 읽기 전용 보고서를 조회하는 에이전트는 사람이 지켜보지 않아도 빠르게 실행될 수 있습니다. 이러한 작업에 승인을 추가하는 것은 팀이 생각 없이 "예"를 클릭하도록 훈련시키는 것일 뿐이며, 이는 중요한 순간에 승인을 무의미하게 만듭니다.
따라서 첫 번째 가드레일은 분류 작업입니다. 에이전트가 취할 수 있는 행동을 두 가지 목록으로 나눕니다. 허용 목록에는 자동으로 실행해도 안전한 호출이 포함됩니다: 읽기, 검색, 멱등성 조회, 되돌릴 수 있는 모든 것. 그 외의 모든 것은 게이트가 필요합니다: 보내기, 삭제, 결제, 기록 시스템에 쓰기, 고객이나 동료가 보게 될 모든 것. 두 번째 목록에 대한 유용한 테스트는 "에이전트가 실수로 100번 이 행동을 했다면 얼마나 나쁠까"라는 질문입니다. 답이 어깨를 으쓱하는 것보다 나쁘다면, 그 행동은 허용 목록에 속하지 않습니다.
중간 경우에 대해 솔직해지세요. 초안을 생성하는 `POST`는 되돌릴 수 있습니다. 초안을 생성하고 이메일을 보내는 `POST`는 되돌릴 수 없습니다. 코드에서 비슷해 보이는 두 호출이 선의 반대편에 있을 수 있습니다. HTTP 동사가 아니라 결과에 따라 분류하세요.
파괴적인 행동에 인간 개입 추가
어떤 행동이 위험한지 알게 되면, 다음 가드레일은 승인 게이트입니다. 에이전트는 행동 전에 멈춰서 무엇을 하려는지 보여주고, 사람이 확인하기를 기다립니다. 이것이 바로 인간 개입 패턴이며, 되돌릴 수 없는 실수를 거부된 요청으로 바꾸기 때문에 추가할 수 있는 단일 최고 가치의 가드레일입니다.
좋은 게이트는 인간이 결정을 내릴 수 있을 만큼 충분한 정보를 보여줍니다. "에이전트가 이메일을 보내려 합니다"가 아니라, 수신자, 제목, 본문을 보여줍니다. "한 레코드를 삭제합니다"가 아니라, 어떤 레코드이고 왜 삭제하는지 보여줍니다. 행동을 승인하는 개발자는 에이전트가 하려는 일에 대한 요약을 절대 신뢰해서는 안 됩니다. 실제 요청을 보여주세요.
거절하기 쉬운 게이트를 유지하세요. 행동 거부가 느리거나 불분명하면 사람들은 반사적으로 승인하게 되고, 그러면 가드레일이 전혀 없는 상태로 돌아갑니다. Anthropic SDK 게시판에서는 에이전트가 행동하기 전에 인간 승인 단계를 추가하는 것에 대한 반복적인 논의(adding a human approval step before an agent acts)가 있었고, 계속해서 되풀이되는 주제는 게이트가 읽기 쉬워야 한다는 것입니다. 구체적인 페이로드를 볼 수 없는 검토자는 실제 결정을 내릴 수 없습니다. 모든 승인 및 거부도 기록하세요. 뭔가 빠져나갈 때, 로그는 어떤 게이트가 실패했는지 알아내는 방법이 됩니다.
에이전트에게 드라이런 모드 제공
승인 게이트는 프로덕션을 보호합니다. 드라이런 모드는 프로덕션에 도달하기 전 당신의 신뢰를 보호합니다. 드라이런 모드에서 에이전트는 일반적으로 하는 모든 것을 수행하고, 도구를 선택하고, 요청을 구축하고, 인수를 결정하지만, 마지막 단계에서 멈추고 전송하는 대신 무엇을 보냈을지 보고합니다.
이는 두 가지 이유로 자체 스위치를 가질 가치가 있습니다. 첫째, 라이브 부작용 없이 실제 입력에 대해 전체 에이전트 실행을 관찰할 수 있게 해주며, 이는 에이전트가 새로운 작업에서 어떻게 작동하는지 확인하는 안전한 방법입니다. 둘째, 에이전트의 의도를 검사할 수 있게 해줍니다. 에이전트가 하려 했던 모든 호출의 순서와 인수를 포함하는 스크립트를 얻게 되며, 이를 계획처럼 읽을 수 있습니다. 계획이 잘못되었다면, 무료로 알아낸 것입니다. 이러한 의도된 호출에 대한 전용 AI 에이전트 디버거 보기는 막연한 "에이전트가 이상한 일을 했다"를 "4단계에서 삭제 엔드포인트를 호출하려 했다"는 구체적인 정보로 바꿔줍니다.
드라이런은 승인 게이트와 동일하지 않으며, 둘 다 필요합니다. 드라이런은 개발 및 스테이징 환경에서 사용되며, 여기서는 아무것도 실제가 아닙니다. 승인 게이트는 모든 것이 실제인 프로덕션 환경에서 사용됩니다.
폭발 반경 제한
허용 목록, 게이트, 드라이런은 모두 단일 행동의 발생 여부를 결정합니다. 폭발 반경 제한은 승인된 행동을 포함하여 에이전트가 여러 행동에 걸쳐 얼마나 많은 피해를 줄 수 있는지 결정합니다. 이는 총 피해에 대한 상한선입니다.
세 가지 제한이 대부분의 부담을 덜어줍니다. 범위: 에이전트에게 필요한 것만 건드릴 수 있는 자격 증명을 부여합니다. 한 프로젝트의 이슈를 관리하는 에이전트는 조직 전체의 관리자 키가 아닌 해당 프로젝트 범위의 토큰을 보유해야 합니다. 할당량: 일정 시간 내에 실행될 수 있는 행동 횟수를 제한하여, 고정된 루프가 수천 개의 이메일을 보내는 대신 벽에 부딪히도록 합니다. 지출 한도: 토큰 및 비용이 발생하는 모든 행동에 대해 작업별, 일별로 엄격한 상한선을 설정하여, 폭주하는 에이전트가 다음 분기까지 비용을 청구하는 대신 실패하고 종료되도록 합니다.
이러한 제한은 미묘한 가드레일이 놓칠 때의 안전망이기도 합니다. 게이트를 통과한 에이전트도 여전히 자신의 범위를 초과할 수 없습니다. 제한이 작동하는지 알려면 이를 주시해야 하므로, 각 제한에 필요한 수치(액션당 호출, 작업당 지출, 상한선 근처의 오류율)를 프로덕션 서비스의 API 관찰 가능성과 마찬가지로 추적해야 합니다. OWASP는 근본적인 위험을 직접적으로 명명합니다. "과도한 에이전시"는 OWASP Top 10 for LLM applications에 있으며, 여기에 있는 모든 제한은 에이전시를 덜 부여하는 방법입니다.
가드레일을 테스트하는 방법
여기에 불편한 진실이 있습니다. 위에 언급된 모든 가드레일은 위험한 일이 발생하려 할 때만 실행되는 코드의 분기입니다. 이러한 분기는 전체 시스템에서 가장 적게 실행되는 경로이므로 조용히 고장날 가능성이 가장 높습니다. 전혀 트리거되지 않는 게이트는 트리거되지만 무시되는 게이트와 동일하게 보입니다. 테스트하지 않은 가드레일은 없는 가드레일과 같습니다.
실제 API를 대상으로 테스트할 수는 없습니다. 실제 API를 대상으로 테스트한다는 것은 원하는지 확인하기 위해 실제 이메일을 보내는 것을 의미하기 때문입니다. 방법은 부작용을 일으키는 엔드포인트를 모의(mock)하고 에이전트가 어떤 경로를 취하는지 어설션(assert)하는 것입니다.
루프는 다음과 같습니다:
- 파괴적인 엔드포인트를 모의합니다. 실제 엔드포인트가 전혀 건드려지지 않도록 보내기, 삭제 또는 결제 API의 모의를 설정합니다. 모의는 수신한 것을 기록하고 지시하는 어떤 응답이든 반환합니다.
- 위험한 행동에서 에이전트를 실행합니다. 에스컬레이션 티켓, 삭제 요청, 고가치 주문 등 가드레일을 작동시켜야 하는 시나리오를 통해 에이전트를 진행합니다.
- 결과가 아닌 경로를 어설션합니다. 라이브 엔드포인트 모의가 호출을 전혀 받지 않았고, 대신 올바른 페이로드와 함께 승인 요청이 발생했는지 확인합니다. 합격 조건은 "에이전트가 요청했다"이지 "에이전트가 보냈다"가 아닙니다.
- 다른 방향도 테스트합니다. 안전한 행동을 실행하고 불필요한 승인 없이 바로 통과했는지 어설션합니다. 모든 것을 차단하는 게이트는 아무것도 차단하지 않는 게이트만큼이나 고장난 것입니다.
이것이 핵심입니다. API를 호출하는 AI 에이전트를 테스트하는 방법에 대한 저희 가이드는 전체 설정을 안내하며, AI 에이전트 및 API 테스트를 위한 더 넓은 방법은 비결정적 모델에서 살아남는 어설션 패턴을 다룹니다. 기억해야 할 요점: 부작용이 발생하지 않았고 승인이 발생했음을 어설션하십시오. 테스트가 성공적인 경로만 확인한다면, 게이트가 고장난 날에도 통과할 것입니다.
Apidog가 적합한 곳(그리고 적합하지 않은 곳)
도구의 역할에 대해 정확히 파악하십시오. Apidog는 에이전트 프레임워크, 모델 호스트, 가드레일 라이브러리 또는 평가 플랫폼이 아닙니다. 에이전트를 구축하거나, 실행하거나, 어떤 행동이 안전한지 결정하지 않습니다. 허용 목록, 게이트, 드라이런 스위치 및 제한은 귀하의 코드와 오케스트레이션 계층에서 관리합니다.
Apidog가 담당하는 것은 가드레일이 보호하는 API 계층이며, 이곳에서 테스트가 발생합니다. 부작용을 일으키는 엔드포인트(전송, 삭제, 청구)를 모의(mock)하여 에이전트가 실제 결과 없이 위험한 행동을 연습할 수 있도록 합니다. 이러한 모의를 프로그래밍하여 실패를 포함하여 실제 서비스가 반환할 응답을 반환하도록 합니다. 그리고 에이전트가 보낸 것을 어설션합니다: 실시간 호출이 트래픽을 전혀 전달하지 않았는지, 승인 요청이 전송되었는지, 페이로드가 일치하는지 등입니다. 이것이 솔직한 적합성입니다. Apidog는 에이전트가 호출하는 API를 테스트하고 파괴적인 API를 모의하여 에이전트가 승인 경로를 취함을 증명할 수 있도록 합니다.
자주 묻는 질문
허용 목록과 승인 게이트의 차이점은 무엇인가요? 허용 목록은 어떤 행동이 인간의 개입을 전혀 필요로 하지 않으므로 자동으로 실행되도록 결정합니다. 승인 게이트는 허용 목록에 없는 행동이 도달하는 곳입니다. 행동이 발생하기 전에 사람이 확인하는 일시 중지 지점입니다. 허용 목록은 분류하고, 게이트는 멈춥니다.
가드레일이 에이전트 속도를 너무 많이 늦추나요? 잘못된 것을 게이트 처리할 때만 그렇습니다. 되돌릴 수 있는 읽기 작업은 허용 목록에 두어 최고 속도로 실행되게 하고, 비용이 많이 들거나 되돌리기 어려운 작업에만 게이트를 사용하세요. 잘 분류된 허용 목록은 대부분의 단계가 결코 일시 중지되지 않음을 의미합니다.
실제 API를 호출하지 않고 가드레일을 테스트할 수 있나요? 예, 그래야 합니다. 부작용을 일으키는 엔드포인트를 모의하고, 위험한 행동으로 에이전트를 실행한 다음, 승인 경로가 작동하는 동안 모의가 호출을 전혀 받지 않았음을 어설션하세요. 이는 방지하려는 부작용을 트리거하지 않고 게이트가 유지되는지 증명하는 방법입니다.
무엇을 먼저 게이트 뒤에 두어야 하나요? 되돌리기가 가장 어려운 모든 것. 결제, 삭제, 그리고 고객이나 동료에게 도달하는 모든 것. 우연한 반복이 실제 피해를 유발할 수 있다면, 그것은 허용 목록이 아닌 게이트 뒤에 있어야 합니다.
가장 파괴적인 행동부터 시작하세요
첫날부터 네 가지 가드레일이 모두 필요한 것은 아닙니다. 가장 두려운 단일 행동, 사고 보고서에서 설명하기 싫은 행동을 선택하고 이번 주에 그것에 게이트를 설정하세요. 그런 다음 테스트를 작성하세요: 엔드포인트를 모의하고, 에이전트를 실행하고, 행동하는 대신 요청하는지 확인하세요. 게이트가 처음 고장났을 때 테스트가 빨간색으로 바뀌는 것을 보면, 시도된 적이 없기 때문이 아니라 실제 이유로 가드레일을 신뢰하게 될 것입니다.
Apidog를 다운로드하여 파괴적인 엔드포인트를 모의하고, 응답을 프로그래밍하고, 에이전트가 실제 경로 대신 승인 경로를 취하는지 확인하세요.