컨텍스트 엔지니어링 에이전트를 사용하여 컨텍스트 세트 빌드

이 문서에서는 데이터 에이전트 애플리케이션에서 높은 QueryData 쿼리 정확도를 달성하는 데 도움이 되는 컨텍스트 세트를 만들고 최적화하는 방법을 설명합니다. 컨텍스트 엔지니어링 에이전트는 컨텍스트 세트의 생성 및 최적화를 자동화하여 컨텍스트 세트를 빌드, 평가, 개선하는 데 도움이 됩니다.

컨텍스트 세트 및 QueryData에 대해 알아보려면 컨텍스트 세트 개요 및 QueryData 개요를 참고하세요.

엔터프라이즈급 데이터 애플리케이션을 빌드하려면 텍스트-SQL 모델 정확도가 일반적으로 100% 에 가까운 품질을 달성해야 합니다. 잘못된 쿼리 결과는 전반적인 애플리케이션 유용성과 사용자 경험에 영향을 미칩니다. 높은 정확도로 설명 가능한 비즈니스 관련 답변을 얻으려면 최적의 정확도를 달성하기 위해 컨텍스트를 만들고 반복적으로 최적화하는 프로세스인 컨텍스트 엔지니어링이 필요합니다.

비즈니스 애플리케이션을 타겟팅하는 컨텍스트를 QueryData 에 제공하면 시스템에서 미묘한 사용자 의도를 해결하는 데 필요한 정확한 비즈니스 규칙을 제공할 수 있습니다.

컨텍스트 엔지니어링 에이전트

컨텍스트 엔지니어링 에이전트는 이 최적화 워크플로를 자동화합니다. 에이전트와 대화하여 컨텍스트를 최적화하는 임시 작업을 처리할 수 있습니다. 다음 목록은 에이전트에 지시하는 데 사용할 수 있는 자연어 프롬프트의 예와 에이전트가 응답하는 방식을 설명합니다. 이러한 예를 사용하여 컨텍스트를 빌드하고 최적화하세요.

  • 실패 분석을 위한 프롬프트 예: "'디즈니 월드 항공편'과 같은 쿼리에 대해 공항을 올바르게 식별하도록 컨텍스트를 업데이트합니다." 에이전트는 실패를 분석하고, 격차를 추론하고, 값 검색 쿼리와 같은 적절한 컨텍스트 항목을 추가하도록 권장합니다.
  • 컨텍스트 제안을 위한 프롬프트 예: "내 앱 코드를 읽고 추가할 컨텍스트를 제안합니다." 에이전트는 코드를 파싱하고, 애플리케이션의 도메인을 추론하고, 관련 컨텍스트 항목을 제안합니다.
  • 일괄 처리를 위한 프롬프트 예: "다음은 질문 과 SQL 쿼리의 10가지 예입니다. 템플릿으로 전환합니다." 에이전트는 입력을 일괄 처리하고 컨텍스트 세트를 업데이트합니다.

골든 데이터 세트의 중요성

컨텍스트를 최적화하려면 먼저 애플리케이션의 자연어 입력과 일치하는 데이터 세트를 만들어야 합니다. 에이전트는 사용자 질문과 예상되는 데이터베이스 쿼리로 구성된 이 골든 데이터 세트를 빌드하는 데 도움이 됩니다. 골든 데이터 세트를 사용하면 다음 작업을 할 수 있습니다.

  • 쿼리 성능의 기준을 설정합니다.
  • 정답 데이터베이스 쿼리에 대해 업데이트를 검증합니다.
  • 반복 전반에서 정확도 개선을 측정합니다.

체계적인 언덕 오르기 프로세스

체계적인 언덕 오르기에서 에이전트는 골든 데이터 세트 평가, 격차 분석, 업데이트를 통해 컨텍스트 세트를 반복적으로 개선하여 정확도를 100%에 가깝게 만듭니다.

  • 기준 컨텍스트 자동 생성: 데이터베이스 스키마 및 애플리케이션 아티팩트에서 파생된 시작 컨텍스트 세트를 만듭니다.
  • 언덕 오르기 최적화 워크플로: 에이전트가 QueryData 정확도를 평가하고, 실패에 대한 격차 분석을 실행하고, 정확도를 높이기 위한 개선사항을 자동으로 제안하도록 합니다.

다음 다이어그램은 체계적인 언덕 오르기 워크플로를 보여줍니다.

컨텍스트를 반복적으로 빌드하는 워크플로

시작하기 전에

컨텍스트 엔지니어링 에이전트를 사용하기 전에 다음 기본 요건을 완료하세요.

필수 서비스 사용 설정

프로젝트에 대해 다음 서비스를 사용 설정합니다.

Cloud SQL 인스턴스 준비

기존 Cloud SQL 인스턴스에 액세스할 수 있는지 확인하거나 새 인스턴스를 만듭니다. 자세한 내용은 Cloud SQL 인스턴스 만들기 를 참고하세요.

이 튜토리얼에서는 Cloud SQL 인스턴스에 데이터베이스가 있어야 합니다. 자세한 내용은 Cloud SQL 인스턴스에서 데이터베이스 만들기를 참고하세요.

필수 역할 및 권한

Cloud SQL 인스턴스에 executesql 권한 부여

Cloud SQL 인스턴스에 executesql 권한을 부여하고 Cloud SQL Data API를 사용 설정하려면 다음 명령어를 실행합니다. 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
다음을 바꿉니다.
  • PROJECT_ID: 프로젝트의 ID입니다. Google Cloud
  • INSTANCE_ID: Cloud SQL 인스턴스의 ID입니다.
이 튜토리얼의 단계를 수행하려면 Google Cloud에 로그인한 후 데이터베이스를 IAM 인증을 사용하여 인증합니다.

개발 환경 준비

로컬 개발 환경 또는 IDE에서 컨텍스트 세트 파일을 빌드할 수 있습니다. 환경을 준비하려면 다음 단계를 완료하세요.

  • 컨텍스트 엔지니어링 에이전트 설치
  • 데이터베이스 연결 설정

컨텍스트 엔지니어링 에이전트 설치

컨텍스트 엔지니어링 에이전트는 기본 Python 패키지를 관리하는 데 uv가 필요한 모델 컨텍스트 프로토콜 (MCP) 서버를 실행합니다.

  1. uv 설치의 안내에 따라 uv를 설치합니다.

  2. uv가 설치되어 있고 명령줄에서 액세스할 수 있는지 확인합니다.

    uv --version

환경을 준비하려면 선택한 에이전트 하니스(예: Antigravity CLI, Claude Code, Gemini CLI)에 컨텍스트 엔지니어링 에이전트를 설치합니다.

선택한 에이전트 하니스에 따라 해당 설치 단계를 따르세요.

Antigravity CLI

Antigravity CLI에 컨텍스트 엔지니어링 에이전트를 설치하려면 다음 단계를 따르세요.

  1. Antigravity CLI를 설치합니다. Antigravity CLI 시작하기를 참고하세요.
  2. 컨텍스트 생성을 위한 워크플로가 포함된 컨텍스트 엔지니어링 에이전트 플러그인을 설치합니다. VERSION을 필요한 출시 버전으로 바꿉니다. 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. Antigravity CLI를 시작합니다. 
    agy
  4. 선택사항입니다. 플러그인을 업데이트합니다. 
    agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/NEW_VERSION

Claude Code

Claude Code에 컨텍스트 엔지니어링 에이전트를 설치하려면 다음 단계를 따르세요.

  1. 플러그인 마켓플레이스를 추가합니다. 
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. 플러그인을 설치합니다. 
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. 플러그인을 다시 로드하여 변경사항을 활성화합니다. 
    /reload-plugins
  4. 선택사항입니다. 플러그인을 업데이트합니다. 
    /plugin update db-context-engineering@db-context-enrichment-marketplace

Gemini CLI (지원 중단됨)

Gemini CLI에 컨텍스트 엔지니어링 에이전트를 설치하려면 다음 단계를 따르세요.

  1. Gemini CLI를 설치합니다. Gemini CLI 시작하기를 참고하세요.
  2. 확장 프로그램을 설치합니다. 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. 선택사항입니다. 확장 프로그램을 업데이트합니다. 
    gemini extensions update mcp-db-context-enrichment

데이터베이스 연결 설정

에이전트는 스키마를 가져오고 생성된 SQL 컨텍스트의 구문을 검증하는 기능이 있는 데이터베이스 연결이 필요합니다. 에이전트가 데이터베이스와 상호작용하도록 하려면 인증 사용자 인증 정보를 구성하고 데이터베이스 연결 구성을 정의합니다.

애플리케이션 기본 사용자 인증 정보 구성

컨텍스트 엔지니어링 에이전트에서 리소스에 액세스하기 위한 사용자 인증 정보를 제공하도록 애플리케이션 기본 사용자 인증 정보 (ADC) 를 구성합니다. Google Cloud

  • 도구 상자 MCP 서버: 사용자 인증 정보를 사용하여 데이터베이스에 연결하고, 스키마를 가져오고, 검증을 위해 SQL을 실행합니다.
  • Evalbench: 사용자 인증 정보를 사용하여 평가를 위해 QueryData를 호출합니다.

터미널에서 다음 명령어를 실행하여 인증합니다.

gcloud auth application-default login

데이터베이스 연결 파일 구성

에이전트에는 컨텍스트 생성을 위한 데이터베이스 연결이 필요하며, MCP 도구 상자는 구성 파일 내에서 이를 지원하고 정의합니다.

구성 파일은 스키마를 가져오거나 SQL을 실행하는 데 필요한 데이터베이스 소스 및 도구를 지정합니다. 컨텍스트 엔지니어링 에이전트에는 구성을 생성하는 데 도움이 되는 사전 설치된 에이전트 기술이 포함되어 있습니다.

  1. 에이전트 환경을 시작합니다.

  2. 에이전트에게 데이터베이스 연결 설정을 도와달라고 요청합니다(예: '데이터베이스 연결 설정 도와줘' 프롬프트). 에이전트의 안내에 따라 현재 작업 디렉터리에 autoctx/tools.yaml로 구성 파일을 만듭니다.

  3. 새 tools.yaml 구성을 적용하려면 연결을 다시 로드합니다.

    • Antigravity CLI에서 /mcp를 실행하고 toolbox를 선택하여 다시 시작합니다.
    • Gemini CLI에서 /mcp reload를 실행합니다.
    • Claude Code에서 /reload-plugins를 실행합니다.

데이터베이스 구성 파일을 수동으로 구성하는 방법에 대한 자세한 내용은 MCP 도구 상자 구성을 참고하세요.

컨텍스트 생성 및 최적화

컨텍스트 엔지니어링 에이전트는 코딩 에이전트의 컨텍스트 엔지니어링 기능을 개선하기 위한 에이전트 기술 및 MCP 도구 세트를 제공합니다. 이러한 도구를 함께 사용하여 기준을 생성하고, 효과를 측정하고, 개선사항을 반복적으로 적용할 수 있습니다. 하지만 워크플로의 어느 단계에서든 시작할 수 있습니다.

  • 컨텍스트 세트가 이미 있는 경우 평가로 바로 진행할 수 있습니다.
  • 수정하려는 실패한 쿼리가 있는 경우 격차 분석으로 바로 진행할 수 있습니다.

각 기능은 에이전트의 작업, 사용 사례, 호출 명령어를 설명합니다.

프롬프트 예는 자연어로 에이전트를 쿼리하는 방법을 보여줍니다. 에이전트가 요청을 완료하기 위해 추가 세부정보가 필요한 경우 명확한 설명을 요청합니다.

평가 데이터 세트 빌드 및 확장

성능을 개선하려면 먼저 성능을 측정해야 합니다. 사용자 질문과 예상되는 SQL로 구성된 골든 데이터 세트가 없는 컨텍스트 엔지니어링에는 체계적인 검증이 부족합니다. 골든 데이터 세트를 사용하면 모든 변경사항이 정답에 대해 검증할 수 있는 측정 가능한 개선사항이 됩니다.

대표적인 골든 데이터 세트를 수동으로 만드는 데는 시간이 오래 걸리며, 작은 데이터 세트에서는 사용자 표현의 변형이 누락될 수 있습니다. 에이전트는 다음을 통해 이 문제를 해결합니다.

  • 데이터베이스 스키마를 기반으로 후보 질문-SQL 쌍을 생성합니다.
  • 필터 변형, 동의어, 재작성을 사용하여 작은 시드 데이터 세트를 확장합니다.

선택적으로 에이전트가 생성된 SQL을 데이터베이스에 대해 실행하도록 할 수 있습니다. 이 검증은 데이터 세트에 쿼리를 추가하기 전에 쿼리가 성공적으로 실행되는지 확인합니다.

데이터 세트는 질문-SQL 쌍이 포함된 JSON 파일입니다.

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for the top 5 products?",
    "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
  }
]

승인된 쌍은 평가를 위해 준비된 작업공간의 autoctx/golden.json 파일을 채웁니다. 기존 파일을 제공하거나 에이전트가 확장할 수 있도록 일부 평가 예를 인라인으로 작성할 수 있습니다.

다음 프롬프트 예를 사용하여 에이전트에 지시할 수 있습니다.

  • "내 스키마에서 평가 데이터 세트를 생성합니다."
  • "다음은 시드 질문과 SQL입니다. 더 넓은 데이터 세트로 확장하고 쿼리가 실행되는지 확인합니다. 쿼리가 실행되는지 확인합니다."

기준 컨텍스트 세트 생성

컨텍스트를 처음부터 만들지 않으려면 에이전트가 비즈니스 규칙, 샘플 쿼리, README 파일과 같은 데이터베이스 스키마 및 애플리케이션 아티팩트에서 초기 컨텍스트 세트를 파생하도록 할 수 있습니다. 이 기준 컨텍스트는 최종 컨텍스트가 아니지만 데이터베이스 모델을 기반으로 검증된 시작점을 제공합니다.

다음 프롬프트 예를 사용하여 에이전트에 지시할 수 있습니다.

  • "내 스키마에서 컨텍스트 세트를 생성합니다."
  • "이러한 스키마와 의 비즈니스 규칙을 사용하여 초기 컨텍스트를 생성합니다.requirements.md"

에이전트는 생성된 아티팩트를 구성하는 실험의 이름을 지정하라는 메시지를 표시하고 데이터베이스 스키마가 큰 경우 범위를 좁히도록 요청할 수 있습니다. Cloud SQL Studio를 사용하여 컨텍스트를 업로드하려면 에이전트가 JSON 파일을 생성한 후 안내를 따르세요.

컨텍스트 효과 평가

컨텍스트 세트와 골든 데이터 세트를 설정한 후 에이전트가 각 골든 질문으로 데이터 에이전트의 QueryData API를 쿼리하여 컨텍스트 성능을 측정하도록 할 수 있습니다. 에이전트는 생성된 SQL과 실행 결과 를 예상 답변과 비교하여 Evalbench를 사용하여 비교를 처리합니다.

평가를 실행하면 다음이 제공됩니다.

  • 통과 및 실패 결과, 집계 점수와 같은 정량적 측정항목을 통해 컨텍스트 반복 전반에서 진행 상황을 추적합니다.
  • 실험 폴더의 eval_reports/ 디렉터리에 작성된 인라인 대화 요약 및 상세 CSV 보고서

평가를 시작하려면 골든 데이터 세트 경로와 컨텍스트 세트 ID를 제공합니다. 컨텍스트 세트 ID를 찾는 방법은 에이전트 컨텍스트 ID 찾기를 참고하세요.

다음 프롬프트 예를 사용하여 에이전트에 지시할 수 있습니다.

  • "golden.json에 대해 내 컨텍스트를 평가합니다."
  • "내 마지막 실험의 구성을 사용하여 평가를 다시 실행합니다."

이전에 생성된 평가 구성을 다시 설정하지 않고 다시 실행하려면 에이전트에게 요청하거나 CLI를 직접 호출합니다.

uvx google-evalbench --run_config=autoctx/experiments/my-experiment/eval_configs/run_config.json

평가 구성 스키마 및 평가 실행을 맞춤설정하는 방법에 대한 자세한 내용은 Evalbench 문서를 참고하세요.

격차 분석 실행 및 개선사항 제안

쿼리 실패를 해결하려면 잘못된 열, 누락된 테이블 조인, 해결되지 않은 퍼지 용어와 같은 근본 원인을 식별해야 합니다. 이러한 문제를 수동으로 식별하려면 평가 보고서를 광범위하게 분석해야 합니다.

에이전트는 이 분석 및 수정 루프를 자동화합니다.

  • 격차 분석: 에이전트는 평가 결과와 컨텍스트 세트를 읽어 유사한 실패를 그룹화하고 템플릿, 패싯, 값 검색과 같은 타겟팅된 컨텍스트 추가를 권장합니다.
  • 제안된 수정사항: 에이전트는 구체적인 수정을 제안하고 선택적으로 데이터베이스에 대해 SQL을 테스트하여 해결을 검증합니다.
  • 기준 보존: 에이전트는 개선사항을 기준 컨텍스트와 함께 새 JSON 파일에 작성하여 원본 파일을 보존합니다.

다음 프롬프트 예를 사용하여 에이전트에 지시할 수 있습니다.

  • "내 마지막 평가에 대해 격차 분석을 실행하고 수정사항을 제안합니다."
  • "golden.json에 대해 이 컨텍스트 세트를 최적화합니다."

다음 반복을 준비하려면 데이터 에이전트 스튜디오를 사용하여 개선된 컨텍스트를 대상 컨텍스트 세트에 업로드하고 안내를 따르세요.

요청 시 특정 컨텍스트 항목 작성

특정 질문의 템플릿, 반복 필터의 패싯, 특정 열의 값 검색과 같이 필요한 컨텍스트를 이미 알고 있는 경우 컨텍스트 JSON을 수동으로 작성하면 매개변수 이름, 유형 메타데이터 또는 프래그먼트 구문에서 직렬화 오류가 발생할 수 있습니다. 에이전트는 JSON 형식을 처리하여 비즈니스 의도에 집중할 수 있도록 합니다.

이 기능을 사용하여 새 쿼리 패턴을 지원하거나 누락된 스키마 세부정보를 해결해야 하는 경우와 같은 임시 업데이트를 할 수도 있습니다. JSON을 가져오려면 평가를 실행하거나 실험을 설정하지 않고 에이전트에 필요한 컨텍스트를 설명합니다.

일회성 작업을 할 때도 이 기능을 사용하는 것이 좋습니다. 이해관계자가 지원하려는 새 질문-SQL 쌍을 제공하거나 코드 검토 중에 누락된 패싯을 발견하는 경우입니다. 실험을 설정하거나 평가를 실행하여 수정할 필요가 없습니다. 원하는 내용을 설명하면 에이전트가 JSON을 생성합니다.

다음 프롬프트 예를 사용하여 에이전트에 지시할 수 있습니다.

  • "SQL: SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'를 사용하여 '캘리포니아에 있는 공항은 어디인가요?'의 템플릿을 만듭니다."
  • "'red eye'라는 라벨이 지정된 departure_time BETWEEN '00:00:00' AND '06:00:00' 필터의 패싯을 만듭니다."
  • "airports.iata의 값 검색을 만듭니다."

컨텍스트 유형 선택에 대한 추론

템플릿, 패싯, 값 검색에 관계없이 올바른 컨텍스트 유형을 선택하면 컨텍스트 블로트 및 데이터베이스 쿼리 회귀를 방지하는 데 도움이 됩니다. 예를 들어 패싯 대신 템플릿을 사용하면 규칙이 중복될 수 있으며, 템플릿으로 충분한 경우 값 검색을 도입하면 쿼리 지연 시간이 늘어날 수 있습니다. 올바른 스키마 형식을 찾으려면 컨텍스트 항목을 만들기 전에 에이전트에게 쿼리 구조 또는 데이터베이스 열을 기반으로 유형을 추천하도록 요청합니다. 에이전트는 컨텍스트 옵션을 이해하는 데 도움이 되도록 추론을 설명합니다.

다음 프롬프트 예를 사용하여 에이전트에 지시할 수 있습니다.

  • "여러 쿼리에서 필터 departure_time BETWEEN '00:00:00' AND '06:00:00' 를 계속 작성합니다. 이 필터를 캡처하는 가장 좋은 방법은 무엇인가요?"
  • "사용자는 자유 형식 텍스트로 항공편 상태를 설명하며 이를 flights.status와 일치시키려고 합니다. 어떤 종류의 값 검색을 설정해야 하나요?"
  • "템플릿과 패싯의 차이점은 무엇이며 언제 각각을 사용해야 하나요?"

컨텍스트 세트 전반에 일괄 작업 적용

에이전트는 대규모 컨텍스트 세트를 일관되게 관리하기 위한 일괄 업데이트를 지원합니다. 데이터베이스 열의 이름이 바뀌거나, 코드 값의 형식이 변경되거나, 템플릿이 지원 중단된 테이블을 참조하는 경우와 같이 여러 컨텍스트 항목을 동시에 업데이트해야 하는 경우 에이전트는 관련 없는 항목을 변경하지 않고 영향을 받는 모든 항목에 변경사항을 적용할 수 있습니다.

다음 프롬프트 예를 사용하여 에이전트에 지시할 수 있습니다.

  • "golden.txt를 읽고 모든 쌍을 템플릿으로 전환합니다."
  • "context_set.json에서 'United'를 참조하는 항목의 airline = 'UA'를 airline = 'United Airlines' 로 바꿉니다. 관련 없는 항목은 그대로 둡니다."

다음 단계