컨텍스트 세트를 애플리케이션과 통합

이 튜토리얼에서는 Google Cloud 콘솔을 사용하여 PostgreSQL용 Cloud SQL에서 컨텍스트 세트를 설정하고 사용하는 방법과 이를 애플리케이션과 통합하는 방법을 설명합니다. 컨텍스트 세트 파일을 빌드하고, 컨텍스트 세트 파일을 사용하는 컨텍스트 세트를 만들고, MCP 도구 상자를 사용하여 QueryData API를 호출하여 자연어 질문에 대한 SQL 쿼리를 생성하고, 이를 애플리케이션과 통합하는 방법을 알아봅니다.

자세한 내용은 컨텍스트 세트 개요를 참고하세요.

목표

  • 데이터베이스 테이블을 만들고 데이터를 채웁니다.
  • Gemini CLI 및 MCP 도구 상자로 컨텍스트 세트 파일을 빌드합니다.
  • 컨텍스트 세트를 만들고 컨텍스트 세트 파일을 업로드합니다.
  • 컨텍스트 세트를 테스트하고 스튜디오에서 SQL 쿼리를 생성합니다.
  • MCP Toolbox의 Gemini 데이터 분석 QueryData 도구를 사용하여 컨텍스트 세트를 애플리케이션과 통합합니다.
  • 값 검색 쿼리를 사용하여 LLM 대답에 그라운딩 추가

비용

이 문서에서는 비용이 청구될 수 있는 Google Cloud구성요소를 사용합니다.

프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용합니다.

신규 Google Cloud 사용자는 무료 체험판을 이용할 수 있습니다.

요금이 계속 청구되지 않도록 이 문서의 작업을 완료한 후 만든 리소스를 삭제합니다. 자세한 내용은 삭제를 참조하세요.

시작하기 전에

컨텍스트 세트를 만들기 전에 다음 기본 요건을 완료하세요.

필수 서비스 사용 설정

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

Cloud SQL 인스턴스 준비

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

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

필수 역할 및 권한

  • 인스턴스에 IAM 사용자 또는 서비스 계정을 추가합니다. 자세한 내용은 Cloud SQL용 IAM 데이터베이스 인증으로 사용자 관리를 참고하세요.
  • 프로젝트 수준에서 IAM 사용자에게 cloudsql.studioUser, cloudsql.instanceUser, geminidataanalytics.queryDataUser 역할을 부여합니다. 자세한 내용은 프로젝트의 IAM 정책 바인딩 추가를 참고하세요.
  • 또한 postgres 사용자와 같은 슈퍼 사용자 권한이 있는 사용자로 로그인하여 IAM 사용자 또는 서비스 계정에 읽기 전용 데이터베이스 권한을 부여해야 합니다.

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO USER_NAME;

    USER_NAME를 사용자의 이메일 주소로 바꿉니다. 특수문자 (@ 및 .)가 포함되어 있으므로 이메일을 따옴표로 묶어야 합니다.

    자세한 내용은 개별 IAM 사용자 또는 서비스 계정에 데이터베이스 권한 부여를 참고하세요.

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: Google Cloud 프로젝트의 ID입니다.
  • INSTANCE_ID: Cloud SQL 인스턴스의 ID입니다.
이 튜토리얼의 단계를 수행하려면 Google Cloud에 로그인한 다음 IAM 인증을 사용하여 데이터베이스를 인증합니다.

flights 및 airports 스키마와 테이블 만들기

이 섹션에서는 이 튜토리얼의 flights 및 airports 데이터베이스 테이블을 만듭니다.

  1. Google Cloud 콘솔에서 Cloud SQL 페이지로 이동합니다.

    Cloud SQL로 이동

  2. 목록에서 인스턴스를 선택합니다.

  3. 탐색 메뉴에서 Cloud SQL Studio를 클릭합니다.

  4. Identity and Access Management 인증을 사용하여 스튜디오에 로그인합니다.

  5. 인증을 클릭합니다. 탐색기 창에 데이터베이스의 객체 목록이 표시됩니다.

  6. 새 SQL 편집기 탭 또는 새 탭을 클릭하여 새 탭을 엽니다.

  7. airports 테이블과 스키마를 만들려면 다음 SQL 문을 실행하세요.

    CREATE TABLE IF NOT EXISTS airports (
  id INT PRIMARY KEY,
  iata TEXT,
  name TEXT,
  city TEXT,
  country TEXT
  );

  8. flights 테이블과 스키마를 만듭니다.

    CREATE TABLE IF NOT EXISTS flights (
  id INT PRIMARY KEY,
  airline VARCHAR(10),
  flight_number INT,
  departure_airport VARCHAR(5),
  arrival_airport VARCHAR(5),
  departure_time TIMESTAMP,
  arrival_time TIMESTAMP,
  departure_gate VARCHAR(10),
  arrival_gate VARCHAR(10)
);

flights 및 airports 테이블 채우기

이 섹션에서는 제공된 SQL 스크립트를 사용하여 flights 및 airports 테이블을 채웁니다.

  1. airports 테이블을 채웁니다.

  2. flights 테이블을 채웁니다.

  3. 다음 쿼리를 실행하여 테이블이 채워졌는지 확인합니다.

    SELECT * FROM "public"."flights" LIMIT 10;
SELECT * FROM "public"."airports" LIMIT 10;

스튜디오에서 컨텍스트 세트 만들기

이 섹션에서 flights-assistant라는 컨텍스트 세트를 만듭니다. 이 컨텍스트 세트에는 업로드된 컨텍스트 세트 파일이 포함되어 있지 않습니다.

  1. Google Cloud 콘솔에서 Cloud SQL 페이지로 이동합니다.

    Cloud SQL로 이동

  2. 목록에서 인스턴스를 선택합니다.

  3. 탐색 메뉴에서 Cloud SQL Studio를 클릭합니다.

  4. IAM 인증을 사용하여 스튜디오에 로그인합니다.

  5. 탐색기 창에서 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.

  6. 컨텍스트 세트 만들기를 클릭합니다.

  7. 컨텍스트 세트 이름에 flights-assistant를 입력합니다.

  8. 만들기를 클릭합니다.

스튜디오에서 컨텍스트 테스트

이 섹션에서는 flights-assistant 컨텍스트에 자연어 질문을 설정하여 SQL 쿼리를 생성합니다. 컨텍스트 세트에 업로드된 컨텍스트 세트 파일이 없으므로 nighttime traffic과 같은 컨텍스트를 사용하여 질문한 후에도 QueryData는 최적화되지 않은 쿼리를 생성합니다.

  1. 탐색기 창에서 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.
  2. Test context set을 클릭합니다.
  3. 쿼리 편집기에서 flights-assistant로 QueryData를 사용하여 SQL 생성을 클릭합니다.

  4. 다음 자연어 질문을 입력하여 SQL 쿼리를 생성하고 생성을 클릭합니다.

    Find flights from SFO to JFK.

    SQL 쿼리를 검토합니다. QueryData가 이 명확한 질문에 대해 올바른 SQL을 생성하는 것을 확인할 수 있습니다.

      SELECT
    *
  FROM
    "flights"
  WHERE
    "departure_airport" = 'SFO' AND "arrival_airport" = 'JFK';

  5. 다음으로 QueryData를 사용하여 SQL 생성: flights-assistant 창에서 수정을 클릭합니다.

  6. 다음 자연어 질문을 입력하여 SQL 쿼리를 생성하고 업데이트를 클릭합니다.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    데이터베이스에서 nighttime 트래픽이라는 용어를 이해하지 못합니다. 이로 인해 SQL 쿼리가 생성되지 않거나 다음 쿼리에서와 같이 용어를 무시하는 쿼리가 생성될 수 있습니다.

    -- The database schema does not contain information about traffic.
-- Returning all flights departing from New York airports.
SELECT
  f.airline,
  f.flight_number,
  a.name AS departure_airport_name,
  f.departure_time,
  b.name AS arrival_airport_name,
  f.arrival_time
FROM
  flights AS f
JOIN
  airports AS a
  ON f.departure_airport = a.iata
JOIN
  airports AS b
  ON f.arrival_airport = b.iata
WHERE
  a.city = 'New York'
ORDER BY
  f.departure_time;

  7. 다음으로 QueryData를 사용하여 SQL 생성: flights-assistant 창에서 수정을 클릭합니다.

  8. 다음 자연어 질문을 입력하여 SQL 쿼리를 생성하고 업데이트를 클릭합니다.

    flight to disney world

    컨텍스트 설정 논리는 이름에 'disney world'가 포함된 공항을 찾는 쿼리를 생성합니다. 데이터베이스에 이러한 공항이나 도시가 없으므로 쿼리는 행을 반환하지 않습니다.

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
INNER JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."name" ILIKE '%Disney World%';

컨텍스트 세트의 컨텍스트 생성

이 섹션에서는 컨텍스트 세트의 쿼리 기능을 개선하는 데 도움이 되는 컨텍스트 파일을 만듭니다.

환경 설정

컨텍스트 생성을 시작하려면 먼저 환경을 준비해야 합니다.

환경을 설정하려면 다음 단계를 수행하세요.

  1. Gemini CLI를 설치합니다. 자세한 내용은 Gemini CLI 빠른 시작을 참고하세요.
  2. gcloud CLI를 설치 합니다.

  3. 애플리케이션 기본 사용자 인증 정보 (ADC)를 설정합니다. 터미널에서 다음 명령어를 실행하여 인증하고 프로젝트를 선택합니다.

    gcloud auth application-default login

  4. 컨텍스트 생성 워크플로가 포함된 DB 컨텍스트 보강 확장 프로그램을 설치합니다.

    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

    버전이 0.4.2 이상인지 확인합니다. DB 컨텍스트 보강 확장 프로그램을 업데이트하려면 다음 명령어를 실행합니다.

    gemini extensions update mcp-db-context-enrichment

  5. DB 컨텍스트 보강 확장 프로그램을 업데이트하거나 GEMINI_API_KEY를 바꾸려면 다음 명령어를 실행합니다.

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    GEMINI_API_KEY를 Gemini API 키로 바꿉니다.

  6. 터미널에서 Gemini CLI를 시작합니다.

    gemini

  7. Gemini CLI 인증 설정을 완료합니다.

  8. 데이터베이스 연결을 설정합니다. 확장 프로그램에는 컨텍스트 생성을 위한 데이터베이스 연결이 필요하며, 이는 MCP 도구 상자에서 지원되고 tools.yaml 구성 파일 내에 정의됩니다.

    현재 디렉터리에 tools.yaml 구성 파일을 만들려면 Help me set up the database connection과 같은 프롬프트를 입력하고 스킬에서 제공하는 안내를 따르세요. tools.yaml 파일에 대한 자세한 내용은 MCP 도구 상자 문서를 참고하세요.

  9. tools.yaml 파일을 만든 후 구성을 다시 로드하려면 Gemini CLI에서 다음 명령어를 실행합니다.

    /mcp reload

  10. MCP 도구 상자와 데이터베이스 보강 확장 프로그램이 연결되어 있고 사용할 준비가 되었는지 확인합니다.

    /mcp list

템플릿 컨텍스트 생성

이 섹션에서는 QueryData가 nighttime traffic라는 용어를 인식하지 못했던 이전 섹션의 문제를 해결하기 위해 컨텍스트 세트 파일에서 nighttime traffic라는 용어를 5:00 PM와 7:00 PM 사이에 발생하는 트래픽으로 정의합니다.

템플릿 컨텍스트를 생성하려면 다음 단계를 수행하세요.

  1. /generate_targeted_templates 명령어를 실행하고 워크플로를 따릅니다.

    /generate_targeted_templates

  2. 터미널에서 쿼리 템플릿에 추가할 자연어 쿼리를 제공합니다.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

  3. 쿼리 템플릿에 추가할 SQL 쿼리를 제공합니다. 이 쿼리 템플릿은 nighttime이 5:00 PM와 7:00 PM 사이에 발생한다고 정의합니다.

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
  ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  4. Enter를 누릅니다. Gemini는 다양한 사용자 쿼리에서 컨텍스트 세트의 성능을 개선하는 특정 형식으로 입력을 변환합니다. 자세한 내용은 컨텍스트 세트 개요를 참고하세요.

    원하는 경우 /generate_bulk_templates 워크플로를 실행하여 Gemini CLI가 데이터베이스 스키마를 스캔하고 관련 컨텍스트를 제안하여 더 많은 컨텍스트를 생성하도록 합니다.

  5. 생성된 쿼리 템플릿을 검토합니다. 쿼리 템플릿을 새 에이전트 컨텍스트 파일로 저장하거나 기존 에이전트 컨텍스트 파일에 추가할 수 있습니다.

  6. 새 에이전트 컨텍스트 파일을 만드는 옵션을 선택합니다. Gemini는 동일한 디렉터리에 다음 콘텐츠가 포함된 INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json 파일 이름을 만듭니다.

    {
  "templates": [
    {
      "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
      "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
      "parameterized": {
        "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
        "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
      }
    }
  ]
}

값 검색 컨텍스트 생성

이 섹션에서는 컨텍스트 설정 논리가 데이터베이스 열에 저장된 특정 값에 값 문구를 매핑하는 데 도움이 되는 값 검색 컨텍스트를 생성합니다. 예를 들어 사용자가 '디즈니 월드행 항공편'을 요청하면 값 검색은 데이터베이스의 airports.city 열과 관련된 개념 유형을 기반으로 이를 '올랜도' 도시의 디즈니 월드에 매핑할 수 있습니다.

값 검색 컨텍스트를 생성하려면 다음 단계를 실행하세요.

  1. /generate_targeted_value_searches 명령어를 실행합니다.

    /generate_targeted_value_searches

  2. postgresql을 입력하여 Cloud SQL을 데이터베이스 엔진으로 선택합니다.

  3. 다음과 같이 값 검색 구성을 입력합니다.

    Table: airports
Column: city
Concept: Airport City
Match Function: SEMANTIC_SIMILARITY_MATCH

  4. 값 검색 정의를 생성할지 확인합니다.

  5. 생성된 값 검색 정의를 검토합니다. 값 검색 정의를 새 컨텍스트 세트 파일로 저장하거나 기존 컨텍스트 세트 파일에 추가할 수 있습니다.

  6. 기존 컨텍스트 세트 파일에 추가하는 옵션을 선택합니다. 이렇게 하면 이전 섹션에서 만든 컨텍스트 파일에 값 검색 정의가 추가됩니다.

  7. 컨텍스트 세트 파일이 생성된 데이터베이스 인스턴스와 데이터베이스 이름을 입력합니다.

    기존 컨텍스트 파일이 값 검색 정의로 업데이트됩니다. Gemini는 동일한 디렉터리에 다음 콘텐츠가 포함된 INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json 파일 이름을 만듭니다.

      {
    "templates": [
      {
        "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
        "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
        "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
        "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
        "parameterized": {
          "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = $1 AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
          "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from $1"
        }
      }
    ],
    "value_searches": [
      {
          "query": "/* Requires extensions: vector, google_ml_integration */ WITH SemanticMetrics AS (    SELECT T.city AS original_value, (        (google_ml.embedding('gemini-embedding-001', $value)::vector <=>          google_ml.embedding('gemini-embedding-001', T.city)::vector) / 2.0    ) AS normalized_dist     FROM airports T     WHERE T.city IS NOT NULL) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, ''::text AS context FROM SemanticMetrics",
          "concept_type": "Airport City",
          "description": "Semantic search for airport city name"
      }
  ]
  }

컨텍스트 세트 파일을 QueryData에 업로드

이 섹션에서는 컨텍스트 세트 파일을 QueryData에 업로드하여 데이터베이스에서 QueryData의 SQL 생성 기능을 개선합니다.

컨텍스트를 업로드하려면 다음 단계를 수행합니다.

  1. Google Cloud 콘솔에서 Cloud SQL 페이지로 이동합니다.

    Cloud SQL로 이동

  2. 목록에서 인스턴스를 선택합니다.

  3. 탐색 메뉴에서 Cloud SQL Studio를 클릭합니다.

  4. Identity and Access Management 인증을 사용하여 스튜디오에 로그인합니다.

  5. 탐색기 창에서 컨텍스트 세트 옆에 있는 작업 () 아이콘을 클릭합니다.

  6. 컨텍스트 세트 수정을 클릭합니다.

  7. (선택사항) 컨텍스트 세트 설명을 수정합니다.

  8. 컨텍스트 세트 파일 업로드 섹션에서 찾아보기를 클릭하고 이전에 생성한 컨텍스트 세트 파일을 선택합니다.

  9. 저장을 클릭합니다.

설정된 컨텍스트를 사용하여 SQL 쿼리 생성

이 섹션에서는 업로드한 컨텍스트 설정 파일을 사용하여 자연어 질문을 합니다. 이를 통해 QueryData가 nighttime traffic와 같은 용어 및 기타 관련 문구의 정의를 올바르게 이해하고 적용하는지, 값 검색이 값 문구를 데이터베이스 열에 저장된 특정 값에 매핑하는지 (예: '디즈니 월드'를 '올랜도'에 매핑) 확인할 수 있습니다.

SQL 쿼리를 생성하려면 다음 단계를 수행하세요.

  1. 탐색기 창에서 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.
  2. Test context set을 클릭합니다.
  3. 쿼리 편집기에서 QueryData를 사용하여 SQL 생성: 항공편 어시스턴트를 클릭합니다.

  4. 다음 자연어 질문을 입력하여 SQL 쿼리를 생성하고 생성을 클릭합니다.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    생성된 SQL 쿼리는 다음과 유사합니다.

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

    이는 QueryData의 컨텍스트에 추가한 질문과 동일합니다. 이제 QueryData가 nighttime traffic라는 용어를 정확하게 해석할 수 있습니다.

    컨텍스트는 하나의 특정 질문에서 비롯되지만 QueryData는 이를 사용하여 다양한 유사한 질문에 대한 SQL 생성을 개선합니다.

  5. 다음으로 QueryData를 사용하여 SQL 생성: flights-assistant 창에서 수정을 클릭합니다.

  6. 다음과 유사한 질문을 입력하여 SQL 쿼리를 생성하고 업데이트를 클릭합니다.

    What are the flights that can help me avoid evening traffic if departing from Boston

    질문에서 nighttime traffic이라는 용어를 유사한 용어인 evening traffic로 대체하므로 QueryData는 동일한 해석을 적용하여 이 질문에 일관된 답변을 제공합니다.

    생성된 SQL 쿼리는 다음과 유사합니다.

    -- What are the flights that can help me avoid evening traffic if departing from Boston
SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
ON
  f.departure_airport = a.iata
WHERE
  a.city = 'Boston'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  7. 다음으로 QueryData를 사용하여 SQL 생성: flights-assistant 창에서 수정을 클릭합니다.

  8. 다음 질문을 입력하여 SQL 쿼리를 생성하고 업데이트를 클릭합니다.

    flights to disney world

    생성된 SQL 쿼리는 다음과 유사합니다.

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."city" = 'Orlando';

    이제 QueryData가 'disney world'가 'Orlando' 도시와 관련이 있음을 정확하게 해석할 수 있습니다.

컨텍스트 세트를 애플리케이션과 통합

이 섹션에서는 항공편 검색 애플리케이션의 QueryData 에이전트를 만듭니다. 이 QueryData 에이전트는 이전에 만든 flights 및 airports 테이블에 대한 대화형 인터페이스를 제공합니다. 또한 에이전트 개발 키트 (ADK), Gemini 데이터 분석 QueryData MCP 도구, 대답의 품질을 개선하기 위해 설정된 컨텍스트를 사용하여 이 QueryData 에이전트를 만들어 애플리케이션에 통합하는 방법을 설명합니다.

  1. MCP 도구 상자 버전 0.31.0 이상을 다운로드합니다. MCP 도구 상자는 애플리케이션이 연결할 수 있는 도구로 QueryData 에이전트를 노출합니다. MCP 도구 상자는 컨텍스트를 생성하는 이전에 설치한 MCP 도구 상자 Gemini CLI 확장 프로그램과 다릅니다.

  2. 애플리케이션 기본 사용자 인증 정보 (ADC)를 설정합니다.

    gcloud auth application-default login

  3. 컨텍스트 세트 ID를 찾습니다. 컨텍스트 세트 ID를 찾는 방법에 관한 자세한 내용은 컨텍스트 세트 ID 찾기를 참고하세요.

  4. MCP 도구 상자를 사용하여 QueryData 에이전트에 연결하도록 tools.yaml 구성을 만듭니다. 자세한 내용은 Gemini 데이터 분석 소스 및 Gemini 데이터 분석 QueryData 도구를 참고하세요.

    kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: "PROJECT_ID"
---
kind: tool
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
location: "REGION_ID"
context:
  datasourceReferences:
    cloudSqlReference:
      databaseReference:
        engine: "POSTGRESQL"
        projectId: "PROJECT_ID"
        region: "REGION_ID"
        instanceId: "INSTANCE_ID"
        databaseId: "DATABASE_ID"
      agentContextReference:
        contextSetId: "CONTEXT_SET_ID"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

    다음을 바꿉니다.

    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • REGION_ID: Cloud SQL 인스턴스의 리전입니다 (예: us-central1).
    • INSTANCE_ID: Cloud SQL 인스턴스의 ID입니다.
    • DATABASE_ID: 연결할 데이터베이스의 이름입니다.
    • CONTEXT_SET_ID: 컨텍스트 세트 ID입니다. 컨텍스트 세트 ID를 찾는 방법에 관한 자세한 내용은 컨텍스트 세트 ID 찾기를 참고하세요.

  5. tools.yaml 파일을 사용하여 MCP 도구 상자 서버를 실행합니다.

    ./toolbox --config "tools.yaml"

  6. MCP 도구 상자의 Python SDK를 사용하여 Gemini 데이터 분석 QueryData 도구를 호출하는 ADK 애플리케이션을 만듭니다. MCP Toolbox의 Python SDK 사용 방법에 대한 자세한 내용은 Toolbox 빠른 시작을, Python ADK에 대한 자세한 내용은 ADK 빠른 시작을 참고하세요.

    1. 애플리케이션을 저장할 디렉터리를 만듭니다(예: flight-assistant-app).

    2. 디렉터리를 flight-assistant-app 디렉터리로 변경합니다.

      mkdir flight-assistant-app
cd flight-assistant-app

    3. flight-assistant-app 디렉터리에서 다음 명령어를 실행하여 가상 환경을 만들고 필요한 구성요소를 설치합니다.

      python3 -m venv .venv
source .venv/bin/activate
pip install toolbox-core
pip install google-genai
pip install google-adk

    4. ADK 에이전트를 설정합니다.

      1. ADK 에이전트를 만듭니다.

        adk create my_agent

      2. gemini-2.5-flash 모델을 선택합니다.

      3. Google AI를 선택하고 Gemini API 키를 입력합니다. API 키를 찾는 방법에 대한 자세한 내용은 Gemini API 키 사용을 참고하세요.

    5. agent.py 파일의 내용을 다음 비행 데이터 어시스턴트 샘플 애플리케이션 코드로 바꿉니다.

      from typing import cast

from google.adk.agents.llm_agent import Agent
from google.adk.agents.llm_agent import ToolUnion

from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = "http://127.0.0.1:5000"

INSTRUCTION = """
# ROLE
You are a friendly and factual flight data assistant. Your goal is to help users find the best flights for their needs by providing accurate information with a helpful, professional tone.
- use the Query Data Tool to answer the user's question, if the tool fails to generate a valid query, ask the user to clarify their question.

# OPERATIONAL CONSTRAINTS
- TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides.
- TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating SQL. Frame all responses as your own direct assistance.
- SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task. Guide the user towards what you can help with.

# COMMUNICATION STYLE
- Be concise and scannable when listing answers.
- Maintain a helpful, professional persona.

=====

# QUERY DATA TOOL

Inputs:
1. query: A natural language formulation of a database query.

Outputs: (all optional)
1. disambiguation_question: Clarification questions or comments where the tool needs the users' input.
2. generated_query: The generated query for the user query.
3. intent_explanation: An explanation for why the tool produced `generated_query`.
4. query_result: The result of executing `generated_query`.
5. natural_language_answer: The natural language answer that summarizes the `query` and `query_result`.

Usage guidance:
1. If `disambiguation_question` is produced, then solicit the needed inputs from the user and try the tool with a new `query` that has the needed clarification.
2. If `natural_language_answer` is produced, use `intent_explanation` and `generated_query` to see if you need to clarify any assumptions for the user.
3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning.
"""

client = ToolboxSyncClient(TOOLBOX_URL)

mcp_tool = client.load_tool("cloud_gda_query_tool")

root_agent = Agent(
    model="gemini-2.5-flash",
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

  7. flight-assistant-app 디렉터리에서 다음 명령어를 실행하여 애플리케이션을 시작하고 http://127.0.0.1:8000에서 ADK 웹 서버에 액세스합니다.

    adk web --port 8000

  8. hello와 같은 텍스트를 입력하여 에이전트와 상호작용을 시작합니다.

    ADK 에이전트는 일반적인 질문에 답변하고 필요한 MCP 도구를 호출합니다.

  9. 다음 항공편 관련 질문을 입력합니다.

    How many flights depart from the west side?

    이 질문에 답하기 위해 MCP 도구가 호출됩니다. 하지만 the west라는 용어는 모호하고 공항을 지정하지 않으므로 MCP 도구는 상담사가 응답을 구성하는 데 사용하는 명확성 확인 질문을 반환합니다.

    I cannot determine how many flights depart from the 'west side' as the database does not contain information about which airports are considered to be on the 'west side'. However, I can help you with questions like:

1. How many flights depart from a specific airport?

2. What are the departure airports for all flights?

3. How many flights depart from each airport? Would you like to rephrase your question based on these options?

  10. 에이전트에 대해 생성된 쿼리 템플릿과 유사한 질문을 입력합니다.

    Help me find flights from San Francisco that avoid the evening rush hour.

    앞서 추가된 QueryData 컨텍스트를 기반으로 MCP 도구는 evening traffic이 오후 5시에서 7시 사이에 발생한다는 것을 이해합니다. MCP 도구는 상담사가 대답을 구성하는 데 사용할 수 있는 연결된 데이터를 반환합니다.

    Here are the flights departing from San Francisco that avoid the evening rush hour (defined as 5 PM to 7 PM):

* UA 1532 departing at 05:50:00
* UA 1158 departing at 05:57:00
* CY 922 departing at 06:38:00
* OO 5441 departing at 07:08:00
* UA 616 departing at 07:14:00
* AA 24 departing at 07:14:00
* B6 434 departing at 08:00:00
* AA 242 departing at 08:18:00
* UA 1739 departing at 08:22:00
* OO 6336 departing at 08:32:00
* US 1784 departing at 08:47:00
* DL 1631 departing at 09:00:00
* DL 1106 departing at 09:06:00
* OO 5427 departing at 09:06:00
* CY 352 departing at 09:25:00

  11. QueryData 에이전트 컨텍스트에 추가한 개념 유형을 기반으로 질문을 입력합니다.

    Get me flights to disney world

    앞서 추가된 값 검색 컨텍스트를 기반으로 QueryData 에이전트는 disney world가 도시 Orlando와 관련이 있음을 이해하고 QueryData 에이전트가 응답을 구성하는 데 사용할 수 있는 연결된 데이터를 반환합니다.

    Here are the flights heading to Orlando, which is the location of Disney World:

* Flight UA 1249 departs from SFO and arrives at MCO on 2025-01-02 at 18:15:00Z.
* Flight UA 698 departs from SFO and arrives at MCO on 2025-01-02 at 22:33:00Z.
* Flight UA 292 departs from SFO and arrives at MCO on 2025-01-03 at 06:37:00Z.

에이전트 성능 반복

ADK 웹 UI를 사용하면 Gemini 데이터 분석 QueryData MCP 도구의 요청과 응답을 검사할 수 있습니다. 이 응답을 사용하여 생성된 SQL 쿼리, 결과 집합, 의도 설명, 명확성 질문, 자연어 답변과 같은 도구 응답을 관찰하여 에이전트의 응답이 올바른지 확인할 수 있습니다.

예를 들어 이전에 입력한 텍스트 How many flights depart from the west side?의 경우 에이전트 풍선을 클릭합니다. 왼쪽 탐색 메뉴의 이벤트 탭에서 functionResponse를 펼쳐 다음 응답을 확인합니다.

"{"disambiguationQuestion": ["[NOT_ENOUGH_INFO] The database schema does not
contain information about which airports are on the 'west side'. Therefore, I
cannot determine how many flights depart from the west side.Possible alternative
questions: 1. How many flights depart from a specific airport? 2. What are the
departure airports for all flights? 3. How many flights depart from each
airport?"]}"

대답 정확도 개선

추가 컨텍스트를 추가하여 Gemini 데이터 분석 QueryData 도구의 대답 정확성을 지속적으로 개선할 수 있습니다. Gemini CLI를 사용하여 컨텍스트를 생성한 다음 업데이트된 컨텍스트 세트 파일을 기존 flights-assistant QueryData 에이전트에 업로드합니다. 자세한 내용은 Gemini CLI를 사용하여 컨텍스트 빌드를 참고하세요. 콘솔은 업로드 후 즉시 새로운 컨텍스트를 수집하므로 애플리케이션 다운타임 없이 에이전트의 정확도를 개선할 수 있습니다.

여러 에이전트

개발 환경에서 tools.yaml 파일의 도구에 고유한 이름을 할당하여 여러 QueryData 에이전트 컨텍스트에서 A/B 테스트를 실행할 수 있습니다. 예를 들어 cloud_gda_query_tool_v1 및 cloud_gda_query_tool_v2과 같이 이름이 다른 두 개의 cloud-gemini-data-analytics-query 도구를 정의하여 고유한 tools.yaml 구성을 만들 수 있습니다. 이 설정을 사용하면 해당 도구 이름을 선택하여 필요한 컨텍스트 버전을 프로그래매틱 방식으로 선택하는 애플리케이션 논리를 구현할 수 있습니다.

다음 예시 tools.yaml에서는 데이터베이스 소스에 여러 QueryData 에이전트를 설정하는 방법을 보여줍니다.

kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: <var>PROJECT_ID</var>
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V1_YOUR_CONTEXT_SET_ID"
generationOptions: ...
---
kind: tool
name: cloud_gda_query_tool_v2
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V2_YOUR_CONTEXT_SET_ID"
generationOptions: ...

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • V1_YOUR_CONTEXT_SET_ID: 버전 1의 컨텍스트 세트 ID입니다.
  • V2_YOUR_CONTEXT_SET_ID: 버전 2의 컨텍스트 세트 ID

삭제

다음 섹션에서는 이러한 리소스와 객체를 삭제하는 방법을 설명합니다.

컨텍스트 세트 삭제

인스턴스를 삭제하기 전에 만든 컨텍스트 세트를 삭제합니다.

  1. Google Cloud 콘솔에서 Cloud SQL 페이지로 이동합니다.

    Cloud SQL로 이동

  2. 목록에서 인스턴스를 선택합니다.

  3. 탐색 메뉴에서 Cloud SQL Studio를 클릭합니다.

  4. Identity and Access Management 인증을 사용하여 스튜디오에 로그인합니다.

  5. 탐색기 창에서 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.

  6. 컨텍스트 세트 삭제 창의 확인란에 flight-assistant를 입력합니다.

  7. 확인을 클릭합니다.

인스턴스 삭제

시작하기 전 섹션에서 생성한 인스턴스를 삭제하면 생성한 모든 객체도 삭제됩니다.

  1. Google Cloud 콘솔에서 Cloud SQL 페이지로 이동합니다.

    Cloud SQL로 이동

  2. 목록에서 인스턴스를 선택합니다.

  3. 삭제를 클릭합니다.

  4. 인스턴스 이름을 입력하고 삭제를 클릭하여 인스턴스 삭제를 확인합니다.

다음 단계