도구 호출을 훅으로 막는다: AgentCore 하네스 라이프사이클 훅·컨센트 포털 운영 가이드

하네스 레벨에 박아넣는 네 지점

AgentCore 하네스는 모델 호출 앞뒤(before_invocation, after_invocation)와 도구 호출 앞뒤(before_tool_call, after_tool_call)에 게이트를 둡니다. 네 지점을 Lambda로 보내면 동기 승인·거부를 받고, SNS·EventBridge로 보내면 결정 없는 기록용 알림만 남습니다. 둘을 구분하지 않으면 감사 로그는 쌓이는데 실제로 막히는 호출은 하나도 없는 상태에 빠집니다.

거부 이후에 벌어지는 일은 지점마다 다릅니다. before_tool_call이 도구 B를 거부하면 B만 건너뛰고 다음 도구 C로 넘어가지만, after_tool_call의 거부는 전체 실행을 멈춥니다. 이 분기를 설계 단계에서 표로 박아 둬야 운영 중 혼선이 줄어듭니다.

컨센트 포털이 메우는 틈

브라우저 팝업을 띄울 수 없는 에이전트 IDE 클라이언트는 OAuth 동의 화면을 보여줄 방법이 없습니다. AgentCore Identity의 컨센트 포털은 이를 서버사이드로 돌려 풉니다. 관리자가 포털 URL을 세션 시작 전에 공유하면 사용자가 거기서 OIDC 로그인과 동의를 끝내고, 토큰은 브라우저를 거치지 않은 채 토큰 볼트에 저장됩니다. 포털은 Gateway 하나당 하나씩 붙고, 그 게이트웨이의 JWT 검증기가 신뢰하는 IdP와 같은 곳을 가리켜야 합니다.

동의는 한 번으로 끝나지 않습니다. 액세스 토큰이 만료되면 저장된 리프레시 토큰으로 자동 재발급되지만, 리프레시 토큰마저 무효화되면 처음부터 다시 동의해야 합니다. 3-legged OAuth에서는 에이전트가 인가 URL을 호출 측 앱에 돌려줘야 하므로, SDK의 USER_FEDERATION 플로우를 호출 경로에 미리 넣어 재동의 시점에 흐름이 끊기지 않게 합니다.

설계에서 운영까지: 훅·컨센트 게이트 체크리스트

(a) 기획과 목표 지표: 훅 타임아웃과 SDK 타임아웃의 관계를 숫자로 먼저 고정합니다. 훅을 900초로 설정했다면 SDK 읽기 타임아웃은 1000초 이상, 예상되는 가장 긴 유휴 구간보다 길게 잡습니다. before_tool_call 거부율, 컨센트 완료율 90% 이상, 재동의 발생률을 배포 전 대시보드 항목으로 선언해 둡니다.

(b) 실패 패턴 네 가지: SDK 타임아웃을 훅보다 짧게 둬 승인 전에 연결이 끊기는 경우, after_invocation으로 유출을 잡으려다 스트리밍이 끝난 뒤라 이미 나간 출력을 되돌리지 못하는 경우, 리프레시 토큰이 끊겨 세션 중간에 재동의 화면을 마주치는 경우, before_tool_call 거부가 조용히 다음 도구로 넘어가 무엇이 왜 생략됐는지 로그로 추적이 안 되는 경우입니다.

복구 분기는 지점별로 둡니다. 마스킹은 after_invocation이 아니라 before_tool_call이나 인라인 함수 래퍼에서 출력 전에 처리하고, 리프레시 토큰 무효화는 정상 분기로 다뤄 재동의 URL을 즉시 호출자에게 돌려줍니다. before_tool_call 거부는 EventBridge로 사유·도구명·세션 ID를 함께 내보내 감사 로그만으로 재구성할 수 있게 합니다.

(c) 운영 체크리스트: 배포 전에 거부·타임아웃·EventBridge 알림·3LO 동의 URL 전달 네 경로를 각각 실제로 발생시켜 확인합니다. 로그에는 훅 지점, 결정, 지연 시간, 도구 이름, 컨센트 제공자, 리프레시 성공 여부를 필수 필드로 남깁니다. IdP별 설정도 넣습니다 — LinkedIn은 앱 설정에서 리프레시 토큰 발급을 따로 켜야 하며, 빠뜨리면 액세스 토큰 만료마다 전체 사용자가 재동의 화면으로 떨어집니다.

(d) 개선 루프: 매주 거부 사유 상위 유형을 집계해 반복해서 걸리는 도구를 추립니다. 재동의로 떨어진 세션 비율이 늘면 해당 IdP의 토큰 수명 정책을 점검 대상에 올리고, 훅 버전이 바뀔 때마다 변경 로그를 체크리스트와 별도 문서로 분리해 과거 거부 패턴과 섞이지 않게 합니다.

한눈에 보는 적용 포인트

도구 호출을 모델 프롬프트가 아니라 하네스 훅으로 막으면 거부·타임아웃·재동의 분기가 코드로 고정됩니다. 훅보다 긴 SDK 타임아웃, before_tool_call과 after_tool_call의 거부 흐름 차이, 컨센트 포털의 토큰 재사용과 재동의 분기까지 체크리스트에 넣어 두면 AgentCore 기능이 늘어나도 같은 운영 틀로 흡수할 수 있습니다.

참고 링크

Harness lifecycle hooks — Amazon Bedrock AgentCore 개발자 가이드

AgentCore Identity managed consent portal — Amazon Bedrock AgentCore 개발자 가이드