データを検出するエージェントをビルドする

ナレッジカタログ検出エージェントは、ナレッジカタログの検索機能に基づいて、複雑な自然言語クエリの検索関連性を向上させる AI 搭載のアシスタントです。クエリの理解と作成を最適化することで、標準の Knowledge Catalog Search API よりも正確な結果が得られます。この機能は、複雑なクエリや長いクエリで特に重要です。

ユースケース

検出エージェントは、次のようなシナリオで豊富な会話機能を提供します。

複雑なインテントと制約、または複合インテントと制約: us-central1 でデータセットを検索するが、BigQuery のリソースは除外するなど、複数の条件を含む検索リクエストを処理します。
ビジネス指向の検索: 正確な技術用語を照合するのではなく、意図とビジネスコンテキストに基づいてデータアセットを検出します。
マルチターンの探索: 会話形式のダイアログで検索を絞り込み、結果を絞り込みます。

検出エージェントは Knowledge Catalog セマンティック検索上に構築されており、すぐに使用できるハイブリッド検索を提供します。購入意向の強い検索（特定のリソースまたは列がわかっている場合）、低レイテンシ要件、またはゼロ設定のハイブリッド検索を処理する必要がある場合は、Knowledge Catalog のセマンティック検索を直接使用できます。

仕組み

検出エージェントは、検索クエリに応答するために次の手順を実行します。

クエリを理解するためにインテントの入力を分析し、複数の検索バリエーションを生成して、キーワードをメタデータフィルタにマッピングします。
Knowledge Catalog のセマンティック検索を使用してリソースを検索します。
統合された結果を関連性に基づいてランク付けします。

次の図式は、プロセスの詳細を示しています。

検索リクエストの検出エージェントプロセス。 — ディスカバリエージェントでの検索リクエストの処理パス。

エージェントは、Knowledge Catalog Search API を使用して関連する Google Cloud リソースを取得します。次のコードスニペットは、エージェントが Knowledge Catalog のセマンティック検索を呼び出す方法を示しています。


      # Configure the request parameters for the
      # call to Knowledge Catalog Semantic Search API.
      endpoint = "dataplex.googleapis.com"

      client = dataplex_v1.CatalogServiceClient(
          client_options={"api_endpoint": endpoint}
      )

      location = "global"
      consumer_project_id = "my-gcp-project"
      parent_name = f"projects/{consumer_project_id}/locations/{location}"

      # Call Knowledge Catalog Semantic Search API.
      response = client.search_entries(
          request={
              "name": parent_name,
              "query": query,
              "page_size": 50,
              "semantic_search": True,
          }
      )

      # Extract useful metadata to share with the agent.
      entries = [
          {
              "entry_name": result.dataplex_entry.name,
              "system": result.dataplex_entry.entry_source.system,
              "resource_id": result.dataplex_entry.entry_source.resource,
              "display_name": result.dataplex_entry.entry_source.display_name,
          }
          for result in response.results
      ]

      return {"results": entries}

始める前に

Knowledge Catalog 検出エージェントを実行するには、次の要件を満たしていることを確認します。

必要なロール

ディスカバリーエージェントの使用に必要な権限を取得するには、 Google Cloud プロジェクト iam.gserviceaccount.comに対する次の IAM ロールを付与するよう管理者に依頼してください。

Dataplex 閲覧者（roles/dataplex.viewer）
Vertex AI ユーザー（roles/aiplatform.user）
Service Usage ユーザー（roles/serviceusage.serviceUsageConsumer）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、検出エージェントの使用に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

検出エージェントを使用するには、次の権限が必要です。

dataplex.projects.search
aiplatform.endpoints.predict
serviceusage.services.use

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

API を有効にする

Knowledge Catalog 検出エージェントを使用するには、プロジェクトで次の API を有効にします。Knowledge Catalog API、Vertex AI API、Service Usage API。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

API を有効にする

環境を設定する

検出エージェントの開発環境を設定する手順は次のとおりです。

dataplex-labs リポジトリのクローンを作成します。

git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git

エージェントディレクトリに移動します。
```
cd dataplex-labs/knowledge_catalog_discovery_agent
```
Python 仮想環境を作成して有効にし、requirements.txt ファイルに記載されている依存関係をインストールします。
- google-adk（Agent Development Kit）
- google-cloud-dataplex（Knowledge Catalog Python クライアント）
- google-api-core
```
  python3 -m venv /tmp/kcsearch

  source /tmp/kcsearch/bin/activate

  pip3 install -r requirements.txt
```
次のコマンドを使用して、環境変数を設定します。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True
```
次のように置き換えます。
- PROJECT_ID はプロジェクトの ID に置き換えます。

検出エージェントをルートエージェントとして実行する

検出エージェントをルートエージェントとして直接実行するには、次の操作を行います。

knowledge_catalog_discovery_agent フォルダにある agent.py ファイルで、discovery_agent 変数の名前を root_agent に変更します。
adk run コマンドを使用してエージェントを実行します。
```
adk run path/to/agent/parent/folder
```
次のように置き換えます。
- path/to/agent/parent/folder は、エージェントを含むフォルダを含む親ディレクトリに置き換えます。たとえば、エージェントが knowledge_catalog_discovery_agent/ にある場合は、agents/ ディレクトリから adk run を実行します。

ディスカバリーエージェントをサブエージェントとして実行する

ディスカバリーエージェントを my_custom_agent などの大規模なカスタムエージェントに統合するには、次の操作を行います。

検出エージェントモジュールを含むプロジェクト構造を設定します。

my_custom_agent/
├── agent.py
└── knowledge_catalog_discovery_agent/
    ├── SKILL.md
    ├── agent.py
    ├── tools.py
    └── utils.py

カスタムエージェントの agent.py ファイルで、検出エージェントをインポートして、エージェントツールとして使用します。次の例をご覧ください。

root_agent = llm_agent.Agent(
    model=google_llm.Gemini(model=GEMINI_MODEL),
    name="my_custom_agent",
    instruction=(
        "You are a Custom Agent. Your goal is to help users understand"
        " their data landscape, evaluate data assets, and derive insights"
        " from available resources. **IMPORTANT**: You should use the"
        " `knowledge_catalog_discovery_agent` to search for and discover"
        " data assets. For best results, pass in the Natural Language user'"
        " query as is to the `knowledge_catalog_discovery_agent`. Once assets"
        " are found, you should analyze their metadata, compare them, and"
        " provide recommendations or summaries to the user to help them make"
        " decisions. Focus on general metadata summary and comparison."
    ),
    tools=[
        agent_tool.AgentTool(discovery_agent),
    ],
)

adk run コマンドを使用してエージェントを実行します。
```
adk run path/to/agent/parent/folder
```
次のように置き換えます。
- path/to/agent/parent/folder は、my_custom_agent/ フォルダを含む親ディレクトリに置き換えます。たとえば、エージェントが agents/my_custom_agent/ にある場合は、agents/ ディレクトリから adk run を実行します。

次のステップ

Knowledge Catalog の検索構文を理解する。
Agent Development Kit の詳細を確認する。

データを検出するエージェントをビルドする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ユースケース

仕組み

始める前に

必要なロール

必要な権限

API を有効にする

環境を設定する

検出エージェントをルート エージェントとして実行する

ディスカバリー エージェントをサブエージェントとして実行する

次のステップ

データを検出するエージェントをビルドする

検出エージェントをルートエージェントとして実行する

ディスカバリーエージェントをサブエージェントとして実行する