데이터 에이전트 만들기

대화형 데이터 에이전트를 사용하면 자연어 인터페이스를 사용하여 데이터베이스 데이터와 상호작용할 수 있습니다. 이러한 에이전트를 빌드하면 사용자가 복잡한 SQL 쿼리를 작성하지 않고도 운영 데이터베이스에서 인사이트를 얻을 수 있습니다.

개략적으로 데이터 에이전트는 페르소나, 데이터 소스 집합, 목적에 중요한 비즈니스 지식 집합에 대한 액세스의 조합입니다.

애플리케이션 개발자에게 이러한 에이전트는 다음과 같은 이점을 제공합니다.

  • 높은 정확도: 작성된 컨텍스트를 사용하면 특정 비즈니스 질문에 대해 높은 정확도를 달성할 수 있습니다. 작성된 컨텍스트는 에이전트 제작자가 정확성을 개선하는 데 사용할 수 있는 기본 핵심 요소입니다. 여기에는 스키마 설명, 시스템 안내, 예상 데이터베이스 쿼리에 관한 추가 정보를 제공하는 구조화된 컨텍스트가 포함됩니다.
  • 복잡성 감소: 에이전트가 자연어를 SQL 쿼리, 실행, 데이터 요약 또는 시각화로 변환합니다.
  • 유연성: 개인 테스트를 위해 에이전트를 초안으로 작성하거나, 프로젝트의 다른 사용자가 사용할 수 있도록 게시하거나, API를 사용하여 프로그래매틱 방식으로 사용할 수 있습니다.

시작하기 전에

  1. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  2. Cloud SQL, Gemini 기반 Data Analytics API, Gemini for Google Cloud API를 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

    API 사용 설정

필요한 역할

데이터 에이전트를 사용하려면 사용 사례에 맞는 IAM 권한이 있어야 합니다. 다음 표에는 에이전트를 만들고 게시하는지, Gemini Enterprise에서 에이전트를 프로비저닝하는지, 에이전트를 검색하고 사용하는지에 따라 필요한 역할이 나와 있습니다. 자세한 내용은 Conversational Analytics API IAM 역할을 참고하세요.

사용 사례 필요한 역할
에이전트 생성, 수정, 게시, 공유, 삭제
  • 프로젝트에서 데이터 에이전트를 만들려면 프로젝트에 대한 Gemini 데이터 분석 데이터 에이전트 생성자 (roles/geminidataanalytics.dataAgentCreator) 권한이 있어야 합니다. 이 역할을 사용하면 사용자가 만든 데이터 에이전트에 대한 Gemini 데이터 분석 데이터 에이전트 소유자 역할이 자동으로 부여됩니다.
  • 데이터 에이전트를 수정, 공유 또는 삭제하려면 에이전트 또는 프로젝트에 대한 Gemini 데이터 분석 데이터 에이전트 소유자 (roles/geminidataanalytics.dataAgentOwner) 권한이 있어야 합니다.
  • 프로젝트에서 데이터 에이전트를 수정하려면 프로젝트에 대한 Gemini 데이터 분석 데이터 에이전트 편집자 (roles/geminidataanalytics.dataAgentEditor)가 있어야 합니다.
  • 프로젝트에서 데이터 에이전트를 보려면 프로젝트에 대한 Gemini 데이터 분석 데이터 에이전트 뷰어 (roles/geminidataanalytics.dataAgentViewer) 권한이 있어야 합니다.
  • 또한 데이터 에이전트를 만들거나 수정하려면 다음 역할이 있어야 합니다.
Gemini Enterprise에서 에이전트 프로비저닝

게시된 에이전트를 Gemini Enterprise의 사용자가 사용할 수 있도록 하려면 Gemini Enterprise 관리 콘솔에서 A2A 에이전트를 등록하고 관리할 수 있는 권한이 있어야 합니다.
에이전트 살펴보기 및 사용하기
  • 데이터 에이전트와 채팅하려면 Gemini 데이터 분석 데이터 에이전트 사용자 (roles/geminidataanalytics.dataAgentUser)여야 합니다.
  • 프로젝트의 모든 데이터 에이전트를 보려면 Gemini 데이터 분석 데이터 에이전트 뷰어 (roles/geminidataanalytics.dataAgentViewer)를 사용하세요.

PostgreSQL용 Cloud SQL 데이터베이스 리소스에 대한 액세스를 관리할 때는 다음 권한 레이어를 고려하세요.

  • Google Cloud IAM: 데이터베이스 인스턴스에 대한 액세스를 클라우드 리소스로 제어합니다. 여기에는 executeSql 권한을 사용하여 연결하고, 인스턴스를 관리하고, SQL 쿼리를 실행하는 권한이 포함됩니다.
  • 데이터베이스 권한: 테이블, 뷰, 스키마와 같은 데이터베이스의 객체에 대한 액세스를 제어합니다. 이러한 권한은 GRANT와 같은 SQL 명령어와 데이터베이스별 사용자 및 역할 시스템을 사용하여 관리됩니다.

PostgreSQL용 Cloud SQL의 경우 인스턴스에 연결하고 쿼리를 전송할 권한을 부여받으려면 적절한 Cloud SQL IAM 역할이 필요합니다. 표 및 뷰와 같은 객체와 상호작용하려면 연결하는 데이터베이스 사용자에게 PostgreSQL용 Cloud SQL GRANT 시스템을 사용하여 필요한 권한이 부여되어 있어야 합니다. 자세한 내용은 PostgreSQL 사용자 및 역할 정보를 참고하세요. 에이전트가 서비스 계정을 사용하는 경우 데이터베이스 역할을 할당받을 수 있습니다. 예를 들어 IAM 데이터베이스 인증으로 사용자 관리를 참고하세요.

데이터 에이전트 만들기

다음 섹션에서는 데이터 에이전트를 만드는 방법을 설명합니다. 에이전트를 만든 후에는 설정을 수정할 수 있습니다.

기본사항 구성

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

    Cloud SQL로 이동

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

  3. 탐색 메뉴에서 에이전트를 클릭합니다.

  4. 에이전트 탭을 클릭합니다.

  5. 데이터베이스를 선택하고 IAM 계정을 사용하여 로그인합니다.

  6. 새 에이전트를 클릭합니다. 새 에이전트 페이지가 열립니다.

  7. 편집기 섹션의 에이전트 이름 필드에 데이터 에이전트의 설명이 포함된 이름을 입력합니다(예: Q4 sales data 또는 User activity logs).

  8. 에이전트 설명 필드에 데이터 에이전트에 대한 설명을 입력합니다. 좋은 설명은 에이전트가 수행하는 작업과 사용하는 데이터를 설명하고 대화에 사용할 올바른 데이터 에이전트인지 판단하는 데 도움이 됩니다(예: What are the top 10 selling products in Q2?).

  9. 지식 소스 섹션에서 소스 추가를 클릭합니다. 데이터 추가 페이지가 열립니다.

  10. 에이전트가 질문에 답변할 때 주로 사용할 테이블을 선택하세요. 추가 지식 소스를 보려면 더보기를 선택합니다.

  11. 추가를 클릭합니다. 새 에이전트 페이지가 다시 열립니다.

표 및 필드 설명 맞춤설정

대화형 데이터 에이전트의 정확도를 개선하려면 선택적으로 추가 테이블 메타데이터를 제공하면 됩니다. 데이터 에이전트만 이 메타데이터를 사용하며 소스 테이블에는 영향을 미치지 않습니다. 다음 메타데이터를 추가할 수 있습니다.

  • 스키마 설명: 에이전트가 데이터를 이해할 수 있도록 테이블과 열에 설명을 추가합니다. 설명을 추가하지 않으면 에이전트가 데이터 정의의 스키마 설명을 사용합니다.

표 및 필드 설명을 추가할 때는 다음 권장사항을 따르세요.

  • 데이터 에이전트 정의뿐만 아니라 데이터 정의에도 설명을 추가합니다. 이렇게 하면 다른 에이전트도 설명을 활용할 수 있습니다.
  • 데이터 에이전트가 데이터를 이해하는 데 도움이 되는 적절한 설명을 프로토타입으로 만들려면 특정 에이전트에 설명을 추가하세요. 설명이 의도한 영향을 미치는지 확인한 후 데이터 정의에 설명을 추가할지 결정할 수 있습니다.

표 및 필드 설명을 구성하려면 다음 단계를 따르세요.

  1. 에이전트 카탈로그 탭에서 맞춤설정하려는 에이전트를 엽니다.
  2. 상담사 수정을 클릭합니다.
  3. 지식 소스에서 맞춤설정할 표를 찾아 맞춤설정을 클릭합니다.
  4. 표 설명을 입력합니다.
  5. 필드 설명을 수정하려면 필드 옆에 있는 수정을 클릭합니다. 필드 수정 창이 열립니다.
    1. ID 필드에 필드 설명을 입력합니다.
    2. 필드 설명을 저장하려면 업데이트를 클릭합니다.
  6. 설명과 필드 업데이트를 저장하려면 업데이트를 클릭합니다. 새 상담사 페이지가 다시 열립니다.
  7. 맞춤설정하려는 각 표에 대해 이 단계를 반복합니다.

데이터 에이전트에 라벨 추가

에이전트 설정 섹션에서 라벨을 만들어 Google Cloud 리소스를 정리할 수 있습니다. 라벨은 관련 객체를 함께 그룹화하거나 다른 Google Cloud리소스와 그룹화할 수 있게 해주는 키-값 쌍입니다.

  1. 에이전트 카탈로그 탭에서 라벨을 추가할 에이전트를 엽니다.
  2. 상담사 수정을 클릭합니다.
  3. 상담사 설정 섹션에서 라벨 추가를 클릭합니다. 라벨 관리 창이 열립니다.
  4. 라벨 추가를 클릭합니다.
  5. 키 및 값 필드에 라벨의 키-값 쌍을 입력합니다.
  6. 라벨을 더 추가하려면 라벨 추가를 다시 클릭합니다.
  7. 라벨을 삭제하려면 삭제를 클릭합니다.
  8. 완료되면 추가를 클릭합니다. 새 에이전트 페이지가 다시 열립니다.

다음 섹션으로 계속 진행하여 에이전트를 초안 모드로 설정하거나 에이전트를 게시합니다.

에이전트 미리보기 및 게시

  1. 미리보기 섹션의 질문하기 필드에 예시 질문을 입력한 다음 Enter를 누릅니다.

    데이터 에이전트가 예상한 데이터를 반환하는지 확인하려면 에이전트의 응답을 검토하세요. 대답이 예상과 다른 경우 편집기 섹션에서 설정을 변경하여 만족스러운 대답을 얻을 때까지 데이터 에이전트 구성을 수정합니다. 에이전트의 결과를 개선하기 위해 에이전트를 계속 테스트하고 수정할 수 있습니다.

  2. 저장을 클릭합니다.

  3. 나중에 다시 수정할 수 있는 초안 모드로 데이터 에이전트를 배치하려면 뒤로를 클릭하여 에이전트 카탈로그 페이지로 돌아갑니다. 이제 에이전트가 초안 모드이므로 에이전트 카탈로그 탭의 내 초안 에이전트 섹션에 표시됩니다.

    에이전트를 게시하려면 에이전트 생성 페이지에 머물러 다음 단계로 진행합니다.

  4. 데이터 에이전트를 게시하고 프로젝트에서 사용할 수 있도록 하려면 게시를 클릭합니다. 에이전트를 게시하면 동일한 데이터베이스 테이블에 액세스할 수 있는 다른 사용자가 내가 만든 안내와 컨텍스트를 활용하여 내 에이전트를 보고 대화할 수 있습니다.

    Google Cloud 콘솔의 에이전트 페이지를 사용하여 데이터 에이전트와 대화를 만들 수 있습니다. Conversational Analytics API를 사용하여 데이터 에이전트와 채팅할 수 있는 자체 인터페이스를 빌드할 수도 있습니다.

  5. 선택사항: 에이전트가 게시됨 대화상자에서 공유를 클릭하여 다른 사용자와 데이터 에이전트를 공유합니다.

    1. 권한 공유 창에서 주 구성원 추가를 클릭합니다.
    2. 새 주 구성원 필드에 주 구성원을 하나 이상 입력합니다.
    3. 역할 선택 목록을 클릭합니다.
    4. 역할 목록에서 다음 역할 중 하나를 선택합니다.
      • Gemini 데이터 분석 데이터 에이전트 사용자(roles/geminidataanalytics.dataAgentUser): 데이터 에이전트와 채팅할 수 있는 권한을 부여합니다.
      • Gemini 데이터 분석 데이터 에이전트 편집자(roles/geminidataanalytics.dataAgentEditor): 데이터 에이전트를 수정할 권한을 부여합니다.
      • Gemini 데이터 분석 데이터 에이전트 뷰어(roles/geminidataanalytics.dataAgentViewer): 데이터 에이전트를 볼 수 있는 권한을 부여합니다.
    5. 저장을 클릭합니다.

  6. 선택사항: 데이터 에이전트를 Gemini Enterprise에 게시할 수 있습니다. 자세한 내용은 Gemini Enterprise에서 데이터 에이전트 게시하기를 참고하세요.

  7. 새 상담사 페이지로 돌아가려면 닫기를 클릭합니다. 에이전트를 저장하거나 게시하면 에이전트 카탈로그에서 확인할 수 있습니다.

데이터 에이전트 관리

기존 에이전트는 에이전트 카탈로그 탭에서 확인할 수 있으며, 이 탭은 다음 세 섹션으로 구성됩니다.

  • 내 에이전트: 내가 만들고 게시한 모든 에이전트의 목록입니다. 게시된 에이전트를 수정하고 다른 사용자와 공유할 수 있습니다.
  • 내 초안 에이전트: 아직 게시하지 않은 에이전트입니다. 초안 에이전트는 공유할 수 없습니다.
  • 조직의 다른 사용자가 공유: 다른 사용자가 만들어 나와 공유한 에이전트입니다. 다른 사용자가 권한을 부여하면 이러한 공유 에이전트를 수정할 수 있습니다.

데이터 에이전트 수정

데이터 에이전트를 수정하려면 다음 단계를 따르세요.

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

    Cloud SQL로 이동

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

  3. 탐색 메뉴에서 에이전트를 클릭합니다.

  4. Identity and Access Management (IAM) 인증을 사용하여 에이전트에 로그인합니다.

  5. 에이전트 카탈로그 탭을 클릭합니다.

  6. 수정할 데이터 에이전트의 에이전트 카드를 찾습니다.

  7. 에이전트 편집기에서 데이터 에이전트를 열려면 작업 열기를 클릭한 다음 에이전트 카드에서 수정을 클릭합니다.

  8. 필요에 따라 데이터 에이전트의 구성을 수정합니다.

  9. 게시하지 않고 변경사항을 저장하려면 저장을 클릭합니다.

  10. 변경사항을 게시하려면 게시를 클릭합니다. 공유 대화상자에서 에이전트를 다른 사용자와 공유하거나 취소를 클릭할 수 있습니다.

  11. 에이전트 창으로 돌아가려면 뒤로를 클릭합니다.

데이터 에이전트 공유

게시된 데이터 에이전트를 공유하려면 다음 단계를 따르세요. 초안 에이전트는 공유할 수 없습니다.

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

    Cloud SQL로 이동

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

  3. 탐색 메뉴에서 에이전트를 클릭합니다.

  4. Identity and Access Management (IAM) 인증을 사용하여 에이전트에 로그인합니다.

  5. 에이전트 카탈로그 탭을 클릭합니다.

  6. 수정할 데이터 에이전트의 에이전트 카드를 찾습니다.

  7. 에이전트 편집기에서 데이터 에이전트를 열려면 작업 열기를 클릭하고 에이전트 카드에서 수정을 클릭합니다.

  8. 다른 사용자와 데이터 에이전트를 공유하려면 공유를 클릭합니다.

  9. 권한 공유 창에서 주 구성원 추가를 클릭합니다.

  10. 주 구성원 추가 필드에 주 구성원을 하나 이상 입력합니다.

  11. 역할 선택을 클릭합니다.

  12. 역할 목록에서 다음 역할 중 하나를 선택합니다.

    • Gemini 데이터 분석 데이터 에이전트 사용자(roles/geminidataanalytics.dataAgentUser): 데이터 에이전트와 채팅할 권한을 부여합니다.
    • Gemini 데이터 분석 데이터 에이전트 편집자(roles/geminidataanalytics.dataAgentEditor): 데이터 에이전트를 수정할 권한을 부여합니다.
    • Gemini 데이터 분석 데이터 에이전트 뷰어(roles/geminidataanalytics.dataAgentViewer): 데이터 에이전트를 볼 수 있는 권한을 부여합니다.

  13. 저장을 클릭합니다.

  14. 에이전트 편집 페이지로 돌아가려면 닫기를 클릭합니다.

  15. 에이전트 창으로 돌아가려면 뒤로를 클릭합니다.

데이터 에이전트 삭제

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

    Cloud SQL로 이동

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

  3. 탐색 메뉴에서 에이전트를 클릭합니다.

  4. Identity and Access Management (IAM) 인증을 사용하여 에이전트에 로그인합니다.

  5. 에이전트 카탈로그 탭을 선택합니다.

  6. 에이전트 카탈로그 탭의 에이전트 섹션에서 삭제할 데이터 에이전트의 에이전트 카드를 찾습니다.

  7. 작업 열기 > 삭제를 클릭합니다.

  8. 에이전트를 삭제하시겠어요? 대화상자에서 삭제를 클릭합니다. 에이전트를 영구적으로 삭제하면 프로젝트에서 에이전트가 삭제됩니다.

    에이전트를 삭제한 후에는 기존 대화를 보기 전용 모드로 사용할 수 있습니다. 삭제된 에이전트에게는 새로운 질문을 할 수 없습니다.

Gemini Enterprise에서 데이터 에이전트 게시

데이터 에이전트를 게시하려면 데이터 분석가, Gemini Enterprise 관리자, 비즈니스 사용자 간의 협업이 필요합니다. 이러한 사용자에게 필요한 역할을 알아보려면 필수 역할을 참고하세요.

에이전트 만들기 및 게시

에이전트를 만들고, 수정하고, 게시하려면 다음 단계를 따르세요.

  1. PostgreSQL용 Cloud SQL에서 데이터 에이전트를 만들기 또는 수정
  2. 에이전트를 게시합니다. 에이전트를 게시할 때 게시 옵션으로 Gemini Enterprise를 선택합니다.
  3. A2A 엔드포인트 JSON을 복사하려면 JSON 복사를 클릭합니다.
  4. Gemini Enterprise 관리자가 Google Cloud 콘솔에서 맞춤 에이전트를 등록하고 액세스 권한을 구성할 수 있도록 A2A 엔드포인트 JSON과 사용자 목록을 공유합니다. 자세한 내용은 에이전트 프로비저닝을 참고하세요.
  5. 액세스 권한이 필요한 사용자 및 그룹과 에이전트를 공유합니다.

에이전트 프로비저닝

게시된 에이전트를 Google Cloud 콘솔의 사용자에게 제공하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 Gemini Enterprise로 이동합니다.

    Gemini Enterprise

  2. 에이전트를 등록할 앱의 이름을 클릭합니다.

  3. 에이전트 > 에이전트 추가를 클릭합니다.

  4. 에이전트 유형 선택 섹션에서 A2A를 통한 커스텀 에이전트의 추가를 클릭합니다.

  5. 에이전트 카드 JSON 필드에 이전에 데이터 분석가로부터 받은 에이전트 카드 세부정보를 JSON 형식으로 입력합니다.

  6. 에이전트 세부정보 프리뷰 > 다음을 클릭합니다.

  7. 에이전트가 사용자를 대신하여 Google Cloud 리소스에 액세스하도록 하려면 다음 단계를 따르세요.

    1. 승인 세부정보 구성 섹션에서 생성한 클라이언트 ID와 클라이언트 보안 비밀번호를 입력합니다.

    2. 승인 URI 필드에 다음을 입력합니다.

      https://accounts.google.com/o/oauth2/v2/auth?client_id=client_id&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

      client_id를 인증 세부정보 구성에서 생성한 클라이언트 ID로 바꿉니다.

    3. 토큰 URI 필드에 다음을 입력합니다.

      https://oauth2.googleapis.com/token

    4. 범위 필드에 다음을 입력합니다.

      https://www.googleapis.com/auth/cloud-platform

  8. 마침을 클릭합니다.

  9. 사용자 또는 그룹과 에이전트를 공유합니다.

자세한 내용은 A2A 에이전트 등록 및 관리를 참고하세요.

에이전트 찾기 및 사용하기

다음 방법 중 하나를 사용하여 Gemini Enterprise에서 데이터 에이전트를 찾아 사용할 수 있습니다.

  • Agent Gallery에서 에이전트를 찾아 전용 채팅을 시작합니다.
  • 에이전트의 전용 URL을 사용하여 특정 PostgreSQL용 Cloud SQL 데이터 에이전트와의 세션에서 Gemini Enterprise를 직접 엽니다.
  • Gemini Enterprise 핵심 채팅에서 @mention(예: @sales_pipeline_agent)를 작성하여 에이전트를 호출합니다.
  • '지난 3개월간 판매 파이프라인 추세는 어때?'와 같은 일반적인 분석 질문을 하면 Gemini Enterprise가 자동으로 관련 데이터 에이전트로 쿼리를 라우팅합니다.

에이전트를 찾은 후에는 다음 방법 중 하나를 사용하여 에이전트와 상호작용할 수 있습니다.

  • 일회성 OAuth 로그인으로 PostgreSQL용 Cloud SQL에 안전하게 인증합니다.
  • 자연어로 질문합니다. 대화형 분석 에이전트는 요청을 처리하고 응답을 텍스트, 마크다운, 차트 또는 표로 Gemini Enterprise에 다시 스트리밍합니다.
  • 대화가 자동으로 저장되는 기록 창에서 대화 기록을 확인합니다.

위치

대화형 분석은 전역적으로 작동하므로 사용할 리전을 선택할 수 없습니다.

다음 단계