애플리케이션과 데이터 에이전트 통합

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

자세한 내용은 데이터 에이전트 개요를 참고하세요.

목표

  • 테이블을 만들고 입력합니다.
  • Gemini CLI 및 MCP 도구 상자를 사용하여 에이전트 컨텍스트를 빌드합니다.
  • 데이터 에이전트를 만들고 컨텍스트를 업로드합니다.
  • 스튜디오에서 에이전트를 검사하고 SQL 쿼리를 생성합니다.
  • MCP 도구 상자의 Gemini 데이터 분석 QueryData 도구를 사용하여 에이전트를 애플리케이션과 통합합니다.

비용

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

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

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

이 문서에 설명된 작업을 완료한 후 만든 리소스를 삭제하여 비용이 계속 청구되지 않도록 하세요. 자세한 내용은 삭제를 참조하세요.

시작하기 전에

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

필수 서비스 사용 설정

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

Cloud SQL 인스턴스 준비

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

필수 역할 및 권한

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

Cloud SQL 인스턴스에 executesql 권한을 부여하고 Cloud SQL Data API를 사용 설정하려면 다음 명령어를 실행합니다. 
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
INSTANCE_ID을 Cloud SQL 인스턴스 ID로 바꿉니다.

이 튜토리얼의 단계를 수행하려면 Cloud de Confiance by S3NS에 로그인한 다음 IAM 인증을 사용하여 데이터베이스를 인증합니다.

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

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

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

    Cloud SQL로 이동

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

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

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

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

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

  7. airports 테이블과 스키마를 만듭니다.

    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 및 airport 테이블 채우기

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

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

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

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

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

데이터 에이전트 만들기

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

  1. 탐색기 창에서 데이터 에이전트 옆에 있는 작업 보기를 클릭합니다.
  2. 에이전트 만들기를 클릭합니다.
  3. 에이전트 이름 지정에 flights-assistant를 입력합니다.
  4. 만들기를 클릭합니다.

스튜디오에서 에이전트 검사

이 섹션에서는 flights-assistant 에이전트에게 자연어 질문을 하면 SQL 쿼리가 생성됩니다. 에이전트에는 컨텍스트가 없으므로 nighttime traffic와 같은 컨텍스트가 포함된 질문을 한 후에도 에이전트가 최적화되지 않은 쿼리를 생성합니다.

  1. 탐색기 창에서 데이터 에이전트 옆에 있는 작업 보기를 클릭합니다.
  2. 에이전트 검사를 클릭합니다.
  3. 쿼리 편집기에서 에이전트를 사용하여 SQL 생성: flights-assistant을 클릭합니다.

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

    Find flights from SFO to JFK.

    SQL 쿼리를 검토합니다. 상담사가 이 명확한 질문에 대해 올바른 SQL을 생성합니다.

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

  5. 에이전트를 사용하여 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;

에이전트의 컨텍스트 생성

이 섹션에서는 에이전트의 쿼리 기능을 개선하는 데 도움이 되는 컨텍스트 파일을 만듭니다. 이전 섹션에서 에이전트가 nighttime traffic라는 용어를 인식하지 못하는 문제를 해결하려면 에이전트 컨텍스트에서 이 용어를 5:00 PM과 7:00 PM 사이에 발생하는 트래픽으로 정의하세요.

에이전트 컨텍스트를 생성하려면 다음 단계를 수행하세요.

  1. 로컬 디렉터리에서 Gemini CLI를 설치합니다. 자세한 내용은 Gemini CLI 빠른 시작을 참고하세요.
  2. gcloud CLI를 설치 하고 애플리케이션 기본 사용자 인증 정보 (ADC)를 설정합니다.

  3. 데이터베이스에 연결되는 MCP 도구 상자 Gemini CLI 확장 프로그램을 설치합니다.

    gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

  4. MCP 도구 상자를 설치하는 것과 동일한 디렉터리에 tools.yaml 구성 파일을 만들어 데이터베이스 연결을 구성합니다.

    sources:
  flight-sql-source:
    kind: cloud-sql-postgres
    project: PROJECT_ID
    region: REGION_ID
    instance: INSTANCE_ID
    database: DATABASE_ID
    user: USER_NAME
    password: PASSWORD

tools:
  # (Optional) Fetches database schemas for context generation in the bulk generation (/generate_bulk_templates) phase.
  list_flight_schemas_tool:
    kind: postgres-list-tables
    source: flight-sql-source
    description: Use this tool to list all tables and their schemas in the flight database.
  # (Optional) Executes generated SQL for validation in the bulk generation (/generate_bulk_templates) phase.
  execute_sql_tool:
    kind: postgres-execute-sql
    source: flight-sql-source
    description: Use this tool to execute SQL against the flight database.

    다음을 바꿉니다.

    • PROJECT_ID: Cloud de Confiance 프로젝트 ID입니다.
    • REGION_ID: Cloud SQL 인스턴스의 리전입니다 (예: us-central1).
    • INSTANCE_ID: Cloud SQL 인스턴스의 ID입니다.
    • DATABASE_ID: 연결할 데이터베이스의 이름입니다.
    • USER_NAME: 데이터베이스 사용자입니다. 이를 리터럴 값이 아닌 환경 변수로 설정합니다. 이 값을 설정하는 방법에 관한 자세한 내용은 MCP 도구 상자의 소스를 참고하세요.
    • PASSWORD: 데이터베이스 사용자의 비밀번호입니다. 이를 리터럴 값이 아닌 환경 변수로 설정합니다. 이 값을 설정하는 방법에 관한 자세한 내용은 MCP 도구 상자의 소스를 참고하세요.

  5. 공식 설치 가이드에 따라 uv Python 패키지 설치 프로그램을 설치하고 다음을 실행하여 설치가 성공했는지 확인합니다.

    uv --version

  6. 컨텍스트 생성 워크플로가 포함된 DB 컨텍스트 보강 MCP 서버를 설치합니다.

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

  7. Gemini API 키를 환경 변수로 내보냅니다. API 키를 찾는 방법에 관한 자세한 내용은 Gemini API 키 사용을 참고하세요.

    export GEMINI_API_KEY="YOUR_API_KEY"

    YOUR_API_KEY를 Gemini API 키로 바꿉니다.

  8. tools.yaml 파일을 만든 동일한 디렉터리에서 Gemini를 시작합니다.

    gemini

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

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

    /mcp list

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

    /generate_targeted_templates

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

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

  13. 쿼리 템플릿에 추가할 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;

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

    원하는 경우 /generate_bulk_templates 워크플로를 실행하여 Gemini CLI가 데이터베이스 스키마를 스캔하고 관련 컨텍스트를 제안하여 더 많은 컨텍스트를 생성하도록 합니다. 4단계에서 만든 tools.yaml 구성에 list_flight_schemas_tool와 execute_sql_tool를 모두 추가해야 합니다.

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

  16. 새 에이전트 컨텍스트 파일을 만드는 옵션을 선택합니다. 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 ?"
      }
    }
  ]
}

에이전트에 컨텍스트 업로드

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

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

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

    Cloud SQL로 이동

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

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

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

  5. 탐색기 창에서 데이터 에이전트 옆에 있는 작업 보기를 클릭합니다.

  6. 상담사 수정을 클릭합니다.

  7. 선택사항: 에이전트 설명을 수정합니다.

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

  9. 저장을 클릭합니다.

에이전트 컨텍스트를 사용하여 SQL 쿼리 생성

이 섹션에서는 업로드한 에이전트 컨텍스트 파일을 사용하여 자연어로 질문합니다. 이를 통해 에이전트가 nighttime traffic와 같은 용어 및 기타 관련 문구의 정의를 올바르게 이해하고 적용하는지 확인할 수 있습니다.

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

  1. 탐색기 창에서 데이터 에이전트 옆에 있는 작업 보기를 클릭합니다.
  2. 에이전트 검사를 클릭합니다.
  3. 쿼리 편집기에서 에이전트를 사용하여 SQL 생성: flights-assistant을 클릭합니다.

  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;

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

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

  5. 에이전트를 사용하여 SQL 생성: flights-assistant 창에서 수정을 클릭합니다.

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

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

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

    생성된 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;

애플리케이션과 에이전트 통합

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

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

  2. 터미널에서 사용 중인 프로젝트를 설정합니다.

    gcloud config set project [PROJECT_ID]

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

    gcloud auth application-default login

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

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

    sources:
  gda-api-source:
    kind: cloud-gemini-data-analytics
    projectId: "PROJECT_ID"

tools:
  cloud_gda_query_tool:
    kind: 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: "DATA_AGENT_CONTEXT_SET_ID"
    generationOptions:
      generateQueryResult: true
      generateNaturalLanguageAnswer: true
      generateExplanation: true
      generateDisambiguationQuestion: true

    다음을 바꿉니다.

    • PROJECT_ID: Cloud de Confiance 프로젝트 ID입니다.
    • REGION_ID: Cloud SQL 인스턴스의 리전입니다 (예: us-central1).
    • INSTANCE_ID: Cloud SQL 인스턴스의 ID입니다.
    • DATABASE_ID: 연결할 데이터베이스의 이름입니다.
    • DATA_AGENT_CONTEXT_SET_ID: 데이터 에이전트 컨텍스트 세트 ID입니다.

  6. tools.yaml 파일을 사용하여 MCP Toolbox 서버를 실행합니다.

    ./toolbox --tools-file "tools.yaml"

  7. 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]),
)

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

    adk web --port 8000

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

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

  10. 다음과 같은 항공편 관련 질문을 입력합니다.

    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?

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

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

    앞서 추가된 에이전트 컨텍스트를 기반으로 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

에이전트 성능 반복

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 에이전트에 업로드합니다. 자세한 내용은 Gemini CLI를 사용하여 컨텍스트 빌드를 참고하세요. 콘솔은 업로드 후 즉시 새로운 컨텍스트를 수집하므로 애플리케이션 다운타임 없이 에이전트의 정확도를 개선할 수 있습니다.

여러 에이전트

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

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

sources:
  gda-api-source:
    kind: cloud-gemini-data-analytics
    projectId: "<var>PROJECT_ID</var>"
tools:
  cloud_gda_query_tool_v1:
    kind: cloud-gemini-data-analytics-query
    source: gda-api-source
    context:
      datasourceReferences:
        <var>DB_SOURCE</var>:
          databaseReference: ...
          agentContextReference:
            contextSetId: "V1_YOUR_DATA_AGENT_CONTEXT_SET_ID"
    generationOptions: ...
  cloud_gda_query_tool_v2:
    kind: cloud-gemini-data-analytics-query
    source: gda-api-source
    context:
      datasourceReferences:
        <var>DB_SOURCE</var>:
          databaseReference: ...
          agentContextReference:
            contextSetId: "V2_YOUR_DATA_AGENT_CONTEXT_SET_ID"
    generationOptions: ...

다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • V1_YOUR_DATA_AGENT_CONTEXT_SET_ID: 버전 1의 데이터 에이전트 컨텍스트 세트 ID입니다.
  • V2_YOUR_DATA_AGENT_CONTEXT_SET_ID: 버전 2의 데이터 에이전트 컨텍스트 설정 ID입니다.

삭제

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

에이전트 삭제

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

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

    Cloud SQL로 이동

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

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

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

  5. 탐색기 창에서 데이터 에이전트 옆에 있는 작업 보기를 클릭합니다.

  6. 에이전트 삭제 창의 확인란에 flight-assistant를 입력합니다.

  7. 확인을 클릭합니다.

인스턴스 삭제

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

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

    Cloud SQL로 이동

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

  3. 삭제를 클릭합니다.

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

다음 단계