BigQuery 에이전트 분석 사용
BigQuery 에이전트 분석은 요청, 응답, 도구 호출, 오류와 같은 원시 에이전트 상호작용을 BigQuery로 직접 스트리밍하여 멀티모달 에이전트 상호작용 데이터를 대규모로 캡처, 분석, 시각화할 수 있는 오픈소스 솔루션입니다. 이 솔루션을 사용하면 AI 기반 평가를 수행하고, 에이전트 프롬프트를 최적화하고, 장기 기억을 추출하여 향후 상호작용을 개선할 수 있습니다. BigQuery 에이전트 분석은 에이전트 개발 키트 (ADK) 및 LangGraph(프리뷰)에서 지원됩니다.
아키텍처
BigQuery 에이전트 분석은 에이전트 실행을 차단하지 않고 높은 처리량과 짧은 지연 시간의 로그 스트리밍을 제공하는 BigQuery Storage Write API (gRPC)를 사용하여 에이전트 활동 데이터를 BigQuery로 스트리밍합니다.
데이터 흐름은 다음 단계로 구성됩니다.
- 캡처 ADK의 로깅 플러그인 또는 LangGraph의 콜백 핸들러를 사용하여 에이전트 상호작용 이벤트를 가로채고 캡처합니다.
- 스트림. 상호작용 이벤트는 Storage Write API (gRPC)를 통해 BigQuery로 전송됩니다. 표준화된 스키마가 없으면 에이전트가 자동으로 스키마를 만듭니다.
- 사용. 로깅된 에이전트 데이터를 분석하고 평가합니다. SQL로 원시 데이터를 쿼리하거나, 커스텀 대시보드에서 측정항목을 추적하거나, BigQuery 에이전트 분석 SDK를 사용하여 복잡한 멀티턴 에이전트 실행 trace를 재구성하고 평가할 수 있습니다.
에이전트 분석 이점
- 코드 한 줄로 포괄적인 로깅을 사용 설정하고 스키마 관리를 자동화합니다.
- 객체 테이블을 사용하여 텍스트, 이미지, 동영상, 오디오와 같은 멀티모달 데이터를 로깅하고 분석합니다.
- 사전 정의된 강력한 스키마 내에서 토큰 소비 및 지연 시간과 같은 운영 측정항목을 추적합니다.
- BigQuery 생성형 AI 함수 및 벡터 검색을 사용하여 최적화 기회를 식별합니다.
- 세분화된 액세스 제어, 데이터 마스킹, 암호화로 에이전트 로그를 보호합니다.
각 워크플로 단계에 맞는 라이브러리 선택
BigQuery 에이전트 분석에는 로깅 통합 2개와 애널리틱스 SDK 1개가 있습니다. 로깅 통합과 애널리틱스 SDK는 워크플로의 여러 단계에 사용됩니다.
- Logging 에이전트 이벤트 로깅: 에이전트 프레임워크에 ADK 플러그인 또는 LangGraph 및 LangChain 콜백 핸들러와 같은 로깅 통합을 사용합니다. 로깅 통합은 하나만 필요하며 이벤트를 로깅하는 데 애널리틱스 SDK가 필요하지 않습니다. 다른 프레임워크의 경우 또는 대화형 분석 데이터 에이전트에 기본 제공 대화 로깅을 사용 설정하려면 에이전트 로그 데이터를 캡처하는 방법을 참조하세요.
- 에이전트 이벤트 분석: BigQuery 에이전트 분석 SDK를 사용하여 로깅된 이벤트를 쿼리, 재구성, 평가합니다. SQL 쿼리 및 대시보드를 사용하여 이벤트를 분석할 수도 있습니다.
다음 다이어그램은 각 워크플로 단계에서 사용할 라이브러리를 보여줍니다.
다음 표에서는 각 로깅 통합 및 애널리틱스 SDK를 설명합니다.
| 워크플로 단계 | 통합 또는 SDK | 패키지 및 진입점 | 사용해야 하는 경우 |
|---|---|---|---|
| Logging 에이전트 이벤트 로그 | ADK BigQuery 에이전트 분석 플러그인 |
Java와 같은 다른 언어의 경우 ADK 플러그인 가이드를 참고하세요. |
ADK 에이전트에서 LLM 요청, 도구 호출, 워크플로 이벤트를 BigQuery로 스트리밍하는 데 사용합니다. |
| Logging 에이전트 이벤트 로그 | LangGraph 및 LangChain BigQuery 콜백 핸들러 (프리뷰) |
|
LangGraph 또는 LangChain 애플리케이션에서 에이전트 실행 이벤트를 BigQuery로 스트리밍하는 데 사용합니다. |
| 에이전트 이벤트 분석 | BigQuery 에이전트 분석 SDK |
|
평가 파이프라인, 노트북 또는 감사 서비스에서 사용하여 로깅 통합이 쓰는 이벤트 테이블을 읽고, 멀티턴 세션을 재구성하고, 자동 평가를 실행합니다. |
에이전트 로그 데이터를 캡처하는 방법
에이전트의 상호작용 원격 분석 (요청, 응답, 도구 호출, 오류 로그)을 BigQuery에 기본적으로 캡처하려면 여러 가지 방법으로 이벤트 데이터를 로깅하면 됩니다.
- 조정 프레임워크 플러그인: 에이전트 조정 도구 키트에서 제공하는 표준 로깅 플러그인을 사용합니다. 예를 들어 ADK의
BigQueryAgentAnalyticsPlugin는 에이전트 실행기에 후크하여 이벤트를 자동으로 가로채고, 직렬화하고, 스트리밍합니다. - 프레임워크 콜백 핸들러: 인기 있는 에이전트 환경에 표준 콜백을 통합합니다. 예를 들어 LangGraph 및 LangChain의
langchain-google-community패키지에서BigQueryCallbackHandler를 사용하여 trace를 가로채고 BigQuery로 전달할 수 있습니다. - 직접 API 수집: 커스텀 또는 독점 프레임워크의 경우Google Cloud 클라이언트 라이브러리를 사용하여 Storage Write API (gRPC)를 통해 구조화된 이벤트를 이벤트 테이블로 직접 스트리밍합니다.
- 대화형 분석 데이터 에이전트: BigQuery Studio에서 또는 Conversational Analytics API를 통해 BigQuery 데이터 에이전트의 설정을 구성할 때 기본 제공 대화 로깅을 사용 설정하여 대화 이벤트를 대상 BigQuery 테이블로 자동 스트리밍하고 대화 로그를 분석합니다.
방법에 관계없이 모든 로깅 옵션은 지연 시간이 짧고 처리량이 높은 BigQuery Storage Write API (gRPC)를 사용합니다. 이 API는 커밋하기 전에 메모리에서 비동기식으로 행을 버퍼링하고 직렬화하는 (PyArrow 엔진 사용) 강력한 스트리밍 엔드포인트를 제공하여 모니터링 가능성 파이프라인 태스크가 사용자 대상 에이전트 실행 차례를 차단하지 않도록 합니다.
에이전트 로그 데이터를 분석하는 방법
에이전트의 성능을 이해하고 최적화하려면 다음과 같은 방법으로 상호작용 로그를 분석하고 평가하세요.
- 직접 SQL 쿼리: BigQuery에서 커스텀 쿼리를 실행하여 토큰 소비 및 실행 지연 시간과 같은 측정항목을 계산합니다.
AI.GENERATE를 사용하여 오류의 근본 원인을 자동으로 분석하거나 비즈니스 테이블과 조인을 수행하여 비즈니스 영향을 측정할 수도 있습니다. - 대화형 대시보드: 데이터 스튜디오와 같은 시각화 도구를 사전 빌드된 또는 커스텀 BigQuery 뷰에 연결하여 시간 경과에 따른 에이전트 상태, 오류율, 사용량 추세를 추적합니다. Looker 고객은 Looker Marketplace에서 사전 빌드된 BigQuery Agent Analytics 대시보드 템플릿(Looker 블록)을 사용할 수도 있습니다.
- Jupyter 노트북: 대화형 환경에서 Python 라이브러리, pandas 또는 BigFrames를 사용하여 로그 데이터를 탐색하고 실험합니다.
- Python SDK: 애플리케이션 코드 또는 자동화된 평가 파이프라인에서 직접 에이전트 실행 trace를 프로그래매틱 방식으로 쿼리, 재구성, 감사합니다.
에이전트 로그 데이터 작업 예시
다음은 BigQuery에서 에이전트 로그 데이터를 사용하는 일반적인 사용 사례와 예시입니다.
모니터링 가능성 및 운영 측정항목
- 데이터를 쿼리하여 에이전트 흐름별로 비용을 세분화하고, 정제 에이전트와 같은 특정 에이전트가 최종 응답에 기여하는 정도에 비해 과도한 양의 토큰을 소비하는지 확인합니다.
AI.GENERATE함수로 쿼리를 실행하여 AI 기반 근본 원인 분석을 위해 BigQuery 대화형 분석 에이전트를 사용합니다. 예를 들어 '이 대화 로그를 분석하고 실패의 근본 원인을 설명해 줘.'
상담사 평가 및 품질 분석
AI.SCORE함수를 사용하여 대화 순위를 매기고 시간 경과에 따른 상담사 순위를 측정합니다.- 벡터 검색과 함께 SQL 쿼리를 사용하여 에이전트가 사용자를 지원하지 못한 대화 클러스터를 식별한 후 사용자의 원래 의도와 비교합니다. 이를 통해 에이전트의 도구 또는 기술 자료의 격차를 파악할 수 있습니다.
비즈니스 인사이트 및 맥락화
에이전트 데이터를 맥락화하려면 agent_events 테이블을 다른 비즈니스 테이블과 조인합니다. 예를 들어 AI 에이전트와 상호작용한 고객과 검색창을 사용한 고객의 평균 주문 금액 (AOV)을 표시합니다.
더 많은 예시는 쿼리 레시피를 참조하세요.
Jupyter 노트북을 사용하여 에이전트 로그 작업
이 예시 Colab Jupyter 노트북을 사용하여 에이전트 로그를 대화형으로 쿼리, 시각화, 평가합니다.
BigQuery 에이전트 분석 SDK 사용
BigQuery 에이전트 분석 SDK는 장기 에이전트 관측 가능성을 위한 소비 및 평가 레이어를 제공하는 오픈소스 Python 라이브러리입니다. 대시보드와 노트북은 임시 탐색에 적합하며, SDK는 에이전트 동작을 대규모로 체계적으로 분석하고 감사하는 방법을 제공합니다.
SDK로 할 수 있는 작업
BigQuery 에이전트 애널리틱스 SDK를 사용하여 다음 태스크를 수행할 수 있습니다. 로그 분석의 자세한 예시는 SDK의 GitHub 저장소를 참조하세요.
- trace 재구성: 다형성 이벤트 로그를 이벤트의 인과적 체인으로 재구성하여 중첩된 도구 및 LLM 호출을 포함한 여러 차례에 걸친 세션을 디버깅합니다.
- 결정론적 및 시맨틱 평가: 지연 시간, 대화 수, 오류율과 같은 규칙 기반 기준과 정확성, 감정, 할루시네이션과 같은 시맨틱 기준을 기준으로 에이전트 품질을 평가합니다.
- 궤적 일치: 실제 에이전트 실행 경로를 예상 골든 궤적과 비교하여 단계 효율성과 도구가 올바른 순서로 사용되었는지 확인합니다.
- 동작 모니터링 및 드리프트 감지: 비결정론적 에이전트 출력에 대한 통계 분석을 수행하고, 사용자 요청 분포를 모니터링하고, 프로덕션 회귀 또는 시맨틱 드리프트를 감지합니다.
- 장기 에이전트 메모리: 에이전트에 세션 간 컨텍스트, 사용자 프로필 시맨틱 검색, BigQuery에 기본적으로 저장되는 토큰 예산 인식 일시적 메모리를 제공합니다.
에이전트 활동 로깅 및 분석
SDK는 로깅 통합에서 작성하는 이벤트를 읽고 평가합니다. 일반적인 워크플로에는 다음 단계가 포함됩니다.
- 상호작용 로깅: 에이전트 조정 프레임워크에서 ADK의
BigQueryAgentAnalyticsPlugin또는 LangGraph의BigQueryCallbackHandler와 같은 로깅 통합을 연결합니다. 사용자가 에이전트와 상호작용하면 통합은 높은 처리량의 Storage Write API (gRPC)를 사용하여 이벤트를 BigQuery에 비동기식으로 스트리밍합니다. 이 단계에서는 SDK가 필요하지 않습니다. 클라이언트 초기화: Python SDK에서 로그 데이터 세트에 연결합니다.
from google.cloud import bigquery from bigquery_agent_analytics import Client client = Client( project_id="YOUR_PROJECT_ID", dataset_id="YOUR_DATASET_ID", table_id="agent_events", )이 스니펫은 다음 구성요소를 사용합니다.
client: 프로그래매틱 방식으로 쿼리를 라우팅하고 활성 데이터베이스 연결을 관리하는 상위Client인스턴스입니다.project_id: 대상 데이터 세트가 있는 Google Cloud 프로젝트 ID입니다.dataset_id: 로그를 저장하는 BigQuery 데이터 세트 이름입니다.table_id: 로깅된 이벤트를 저장하는 테이블입니다(기본값은agent_events). 이 값은 로깅 통합이 쓰는 테이블과 일치해야 합니다. 예를 들어langchain-google-community버전 4.0.0 이하의BigQueryCallbackHandler는 기본적으로agent_events_v2에 씁니다.
세션 trace 재구성: 특정 대화 세션을 가져와 정확한 이벤트 시퀀스를 시각화하고 검토합니다.
trace = client.get_session_trace( session_id="YOUR_SESSION_ID" ) trace.render()이 스니펫은 다음 구성요소를 사용합니다.
trace: 모든 사용자 및 에이전트 작업의 재구성된 인과 관계가 있는 계층적 DAG 스팬 트리를 포함하는 하이드레이션된Trace객체입니다.YOUR_SESSION_ID: 검사하려는 세션의 고유 ID입니다.
자동 평가 실행: 프로그래매틱 방식으로 세션 궤적을 채점하거나 골든 테스트 모음을 기준으로 회귀를 확인합니다.
from bigquery_agent_analytics import ( LLMAsJudge, TraceFilter, ) # Run semantic evaluations across target sessions evaluator = LLMAsJudge.correctness() filters = TraceFilter(session_ids=["session_1", "session_2"]) report = client.evaluate(evaluator, filters=filters) print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")이 스니펫은 다음 구성요소를 사용합니다.
evaluator: 세션 점수를 매기는 데 사용되는 시맨틱(LLMAsJudge) 평가자입니다. 규칙 기반SystemEvaluator검사를 실행하거나 평가자를 가중치가 적용된GraderPipeline로 결합할 수도 있습니다.filters: BigQuery에서 일괄 평가를 실행할session_ids목록 (또는 기간 및 에이전트 필터)을 지정하는TraceFilter인스턴스입니다.report: 원시 세션 등급, 측정항목 요약, 자동 평가자 의견이 포함된 결과EvaluationReport객체입니다.
워크플로에 BigQuery 에이전트 분석 통합
BigQuery 에이전트 분석을 워크플로에 통합하려면 다음을 수행합니다.
에이전트 프레임워크의 로깅 통합을 설정합니다.
BigQuery 에이전트 애널리틱스 SDK, 예시 Colab 노트북 또는 SQL 쿼리 레시피를 사용하여 로깅된 이벤트를 분석합니다.