Google AQuA 사용법: 운영 중인 AI 에이전트 오류 자동 진단하기

Google AQuA로 어떤 AI 에이전트 오류를 찾나요?

AQuA는 2026년 10월 8일 Google 개발자 블로그에서 소개됐습니다. 요청 처리 경로 밖에서 운영 기록을 살펴보고, 진단할 때 배포 당시 소스 스냅샷을 대조합니다. 정상 응답 여부와 업무 성공 여부를 분리해 볼 때 활용할 수 있습니다. 근거: Google 공식 AQuA 발표

예를 들어 고객지원 에이전트가 주문 조회 없이 “환불 가능”이라고 답했다고 가정해 보세요. HTTP 요청이 성공했어도 기대한 확인 절차를 수행했는지는 별도 문제입니다. 이는 글의 이해를 위한 가상 사례이며 AQuA가 실제로 탐지했다는 시험 결과가 아닙니다.

로컬 데모로 AQuA 사용법 먼저 익히기

저장소를 내려받아 데모를 열 수 있습니다. 아래 명령은 Google의 합성 데이터 데모를 시작하는 예시입니다. 설치 과정의 패키지 다운로드와 실행 환경은 별도로 필요합니다.

git clone https://github.com/google/adk-recipes.git
cd adk-recipes/core/python/ambient-quality-agent
make demo

make demo는 프런트엔드를 빌드하고 모의 화면을 실행합니다. make standalone은 실제 모델·인증과 배포된 에이전트를 사용하는 모드이므로 같은 것으로 취급하면 안 됩니다. 근거: 데모·standalone 실행 대상

데모를 볼 때는 수치를 성능 증명으로 받아들이기보다 “어떤 문제를 묶었는지, 근거 대화는 어디 있는지, 실제 관측과 기대 동작이 어떻게 다른지”를 확인하세요. 화면 접속 성공이 자신의 운영 에이전트 연결 성공을 뜻하지는 않습니다.

운영 적용 준비: ADK·Google Cloud·텔레메트리

README의 요구사항은 Python 3.11~3.13, uv·npm, agents-cli 1.6 이상, Terraform과 Google Cloud 프로젝트·Application Default Credentials입니다. 데이터 소스는 BigQuery Agent Analytics, Cloud Telemetry의 연결된 BigQuery 데이터셋, agents-cli 기본 텔레메트리 경로를 지원합니다. 대시보드 접근에는 IAP 권한도 확인해야 합니다. 근거: AQuA 사전 조건

agents-cli 초기 설치는 공식 시작 문서의 다음 명령을 사용할 수 있습니다. 일반 로컬 개발 인증과 Google Cloud 배포용 인증은 구분하고, 대상 프로젝트를 먼저 확인하세요.

uvx google-agents-cli setup
agents-cli info

agents-cli는 CLI만으로도 사용할 수 있습니다. 코딩 에이전트에 스킬을 설치하는 방식이 필수는 아닙니다. 근거: 설치·인증·독립 CLI 사용

AQuA 확장 설치와 배포 명령

기존 agents-cli 에이전트 프로젝트 안에서 실행할 예시입니다. 확인일의 README는 확장 리비전을 고정하고 AQuA 전용 옵션을 명시합니다. 실행 전 고정 태그의 문서와 설치된 CLI 도움말도 대조하세요.

agents-cli extension add google/adk-recipes#core/python/ambient-quality-agent \
  --ref ambient-quality-agent/v0.1.0
agents-cli install

export GOOGLE_CLOUD_PROJECT='YOUR_PROJECT_ID'
export TF_VAR_ui_iap_members='["user:YOUR_ADMIN_EMAIL"]'

# 구성 검토
agents-cli infra single-project --project="${GOOGLE_CLOUD_PROJECT}" --apply-aqua

# 실제 클라우드 리소스 생성·변경
agents-cli infra single-project --project="${GOOGLE_CLOUD_PROJECT}" --apply-aqua --apply
agents-cli deploy --project="${GOOGLE_CLOUD_PROJECT}" --deploy-aqua
agents-cli aqua info --ui-url

자리표시자를 실제 프로젝트·허용 사용자로 바꾸세요. --apply와 deploy는 리소스를 변경하고 비용이 발생할 수 있습니다. 확장 디렉터리와 agents-cli-extensions.yaml도 버전 관리 대상입니다. README는 AQuA 전용 옵션 없이 infra·deploy를 실행하면 관측 대상 에이전트만 처리한다고 설명합니다. 근거: 확장 고정·배포 옵션·IAP

10월 8일 블로그의 짧은 배포 예시에는 위 전용 옵션이 생략돼 있습니다. 복사한 명령만 믿기보다 자신이 설치한 리비전과 도움말을 기준으로 적용 범위를 확인하는 것이 이 가이드의 권고입니다.

운영 대화 검토를 실행하고 진단 결과 확인하기

배포 후 설정과 새 진단 항목을 확인하는 기본 흐름입니다. 꺾쇠 형태의 자리표시자 대신 아래의 YOUR_INSIGHT_ID를 실제 ID로 바꾸세요.

agents-cli aqua show-config
agents-cli aqua schedule-investigation --wait
agents-cli aqua list-insights --status NEW
agents-cli aqua get-insight YOUR_INSIGHT_ID

조회 명령은 JSON을 출력합니다. schedule-investigation은 조회만 하는 명령이 아니라 검토 작업을 요청하므로 실행 빈도와 사용량을 관리하세요. 근거: AQuA 사용 명령

공식 발표의 처리 흐름은 표본 수집 → 대화 검토 → 실패 군집화 → 근거 검증 → 추적입니다. 원인 분석은 대시보드 Investigate 또는 agents-cli aqua run으로 요청합니다. 샘플링과 일부 대화 검증이므로 모든 세션을 검증한 결과로 읽으면 안 됩니다. AQuA는 자체적으로 수정이나 PR을 만들지 않습니다. 근거: 진단 파이프라인·수정 경계

goal.md 예시: 업무 기준을 진단 기준으로 만들기

진단 목표는 “친절하게 답변”보다 검증할 수 있는 업무 조건으로 적는 편이 유용합니다. 다음은 가상의 주문 상담 에이전트를 위한 편집부 예시입니다. 파일 생성만으로 업로드·활성화되는 설정이라고 가정하지 말고, 해당 리비전의 Configuration 화면·설정 절차에서 적용을 확인하세요.

목표: 실제 조회 결과에 근거해 주문 상태와 환불 가능 여부를 안내한다.
확인할 오류:
- 주문 조회 전에 주문 상태를 확정해서 답한다.
- 사용자가 주문 번호를 바꿨는데 이전 주문으로 처리한다.
- 환불 가능 여부가 불명확한데 완료됐다고 안내한다.
제외: 인사말과 표현 차이만 있는 대화.
근거: 문제가 발생한 대화 차례와 실제 도구 결과를 함께 남긴다.

이런 기준은 정답을 새로 만들어내는 기능이 아닙니다. 담당자는 원문과 도구 결과를 읽어 기대 동작 자체가 맞는지 검토해야 합니다. 먼저 “확인할 수 없는 경우는 미확인으로 안내” 같은 업무 원칙을 합의하면 가설과 검증 결과를 구분하기 쉽습니다.

진단 결과를 수정 작업으로 바꾸는 실무 점검표

아래는 편집부가 제안하는 검토 순서입니다. 진단 문구만으로 수정하기보다 근거와 버전을 함께 기록하세요. 빈 AQuA 운영 진단 점검표 CSV 다운로드를 제공합니다.

재현에는 운영 쓰기 작업을 그대로 다시 실행하지 않는 테스트 환경과 통제된 도구 상태가 필요합니다. 예를 들어 환불 도구는 테스트 대체값으로 바꾸고, 같은 입력에서 조회·판단 순서가 바뀌었는지 확인하세요. 이는 실무 검증 제안이며 이 글에서 재현 시험을 수행했다는 뜻은 아닙니다.

AQuA에 결과가 없거나 대시보드가 열리지 않을 때

오류 메시지와 버전을 남기되 원문 대화에 들어 있는 고객 정보나 자격증명을 공개 지원 글에 그대로 붙여 넣지 마세요. 원문 열람 권한과 보관 기간도 업무 데이터 관리 기준에 맞춰 정하는 것이 좋습니다.

비용과 자동 진단의 한계

오픈소스 코드라는 이유로 운영 비용이 0이 되지는 않습니다. Google Cloud에 배포한 리소스는 사용자가 책임지고 관리합니다. 근거: agents-cli 배포·서비스 조건

실무 예산은 하루 검토 횟수, 표본 수, 대화 길이, 원인 분석 요청 수를 먼저 기록해 비교하세요. 이 글은 단일 세션 고정 단가나 월 비용을 제시하지 않습니다. 짧은 대화의 평균을 긴 도구 호출 기록에도 적용하거나, 모델 호출 비용만 전체 청구액으로 계산하면 예측이 빗나갈 수 있습니다.

AQuA 진단 결과를 수정 전후로 비교하는 기준

아래는 가상 주문 상담의 회귀 검증 계획입니다. AQuA의 진단 문구를 그대로 정답으로 삼지 말고, 담당자가 업무 규칙과 근거 대화를 확인한 뒤 비교 기준을 고정하세요.

수정 전후의 코드 리비전·모델·목표·입력을 기록하고, 외부 도구 상태를 통제합니다. “진단 목록에서 안 보임”, “재현 시험 통과”, “운영 재발 미관측”은 서로 다른 결과입니다. 검토 기간에 데이터가 없었다면 개선 성공으로 계산하지 마세요.

자주 묻는 질문

AQuA는 모든 AI 에이전트에 바로 붙일 수 있나요?

이 글은 공개된 ADK·agents-cli 기반 참조 구현을 다룹니다. 다른 프레임워크라면 텔레메트리·소스 스냅샷·프로젝트 구조의 적합성을 먼저 검토해야 합니다.

로컬 데모 성공이면 운영 자동 진단도 검증된 건가요?

아닙니다. 데모는 합성 데이터 화면입니다. 운영 연결에서는 데이터 수집·권한·설정·모델 호출 결과를 각각 확인해야 합니다.

수정안을 자동으로 운영에 적용해도 되나요?

담당자가 근거를 검토하고 테스트를 통과한 변경을 배포하는 흐름으로 사용하세요. 탐지와 코드 변경·배포의 승인 기준을 각각 정하는 것이 좋습니다.

관련 AI 에이전트 검증 가이드

진단한 문제를 배포 전 검증에 반영하려면 GitHub Actions PR 검증 가이드를 참고하세요. 실행 경계를 함께 점검할 때는 Copilot 샌드박스 네트워크 제한 가이드도 활용할 수 있습니다.