Genie Agents API の使用

Genie Agents API を使用して、Genie Agents を独自のチャットボット、エージェント、またはアプリケーションに統合します。 APIは、ステートフルな自然言語データクエリ(フォローアップ質問や履歴付き)のためのチャットモードAPIや、ワークスペース間でGenieエージェントを作成、設定、展開するCI/CDワークフロー向けの管理APIを提供します。

Note

Genie Agents は、以前は Genie Spaces として知られていました。

Overview

Genie APIは以下の種類の機能を提供します:

チャットモードAPI:アプリケーション、チャットボット、エージェントフレームワークで自然言語データクエリを可能にします。これらのAPIは、チャットモードで作成されたステートフルな会話をサポートし、ユーザーが時間をかけて自然に質問したりデータを探索したりできます。
エージェントモードAPI:開発者がエージェントモードでプログラム的にプロンプトを送信し、推論やSQL結果をストリーミングし、引用付きの最終レポートを受け取ることを可能にします。
管理 API: ワークスペース間での Genie エージェントのプログラムによる作成、構成、デプロイを有効にします。 CI/CD パイプライン、バージョン管理、および自動エージェント管理には、これらの API を使用します。

このページでは、よくキュレーションされたGenieエージェントの準備方法と、ワークスペース間のエージェント管理方法を説明しています。これによりAPIが信頼できる結果を返すことができるようにします。エージェントは、Genie が質問を解釈して回答を生成するために使用するコンテキストを提供します。エージェントが不完全または未テストの場合、正しい API 統合を使用しても、ユーザーは間違った結果を受け取る可能性があります。ランタイムエンドポイント、リクエストフォーマット、レスポンス形式については、 Genie APIリファレンスにリンクされたREST APIリファレンスを参照してください。

このページのセットアップ例はREST APIを直接使っています。これらの API は、Azure Databricks SDK を使用して呼び出すこともできます。 Databricks SDK を参照してください。

前提条件

Genie API を使用するには、次のものが必要です。

Databricks SQL エンタイトルメントを使用して Azure Databricks ワークスペースにアクセスします。
少なくとも SQL Pro またはサーバーレス SQL ウェアハウスで使用する権限が必要です。

作業の開始

Azure Databricks 認証を構成する

ブラウザーにアクセスできるユーザーが存在する運用環境のユースケースでは、ユーザーの OAuth (OAuth U2M) を使用します。ブラウザーベースの認証ができない場合は、サービスプリンシパルを使用して API で認証します。サービスプリンシパル向けの OAuth (OAuth M2M) を参照してください。サービスプリンシパルには、必要なデータと SQL ウェアハウスにアクセスするためのアクセス許可が必要です。

詳細を収集する

ワークスペースインスタンス名: Databricks ワークスペースの URL からワークスペースインスタンス名を検索してコピーします。 URL 内のワークスペース識別子の詳細については、「ワークスペースオブジェクトの識別子を取得する」を参照してください。

例： https://cust-success.cloud.databricks.com/
ウェアハウス ID: 少なくとも CAN USE 特権を持っている SQL ウェアハウスの ID が必要です。倉庫 ID を検索するには:
1. ワークスペースの SQL Warehouse に 移動します。
2. 使用する倉庫を選択します。
3. URL または倉庫の詳細ページから倉庫 ID をコピーします。
または、List warehouses エンドポイントを使用してGET /api/2.0/sql/warehousesアクセス許可を持つすべての SQL ウェアハウスの一覧をプログラムで取得します。応答にはウェアハウスIDが含まれています。

Genie エージェントを作成または選択する

適切に構造化された Genie エージェントには、次の特性があります。

適切に注釈付けされたデータを使用します。Genie はテーブルメタデータと列コメントに依存します。 Unity カタログのデータソースに明確でわかりやすいコメントがあることを確認します。
ユーザーテスト: エンドユーザーに期待される質問をしてエージェントをテストします。テストを使用して、SQL クエリの例を作成および調整します。
会社固有のコンテキストを含む: 命令の追加、SQL の例、関数。「SQL の例と手順を追加する」を参照してください。少なくとも 5 つのテスト済みの SQL クエリ例を目指します。
ベンチマークを使用して精度をテストします。予測されるユーザーの質問に基づいて、少なくとも 5 つのベンチマークの質問を追加します。ベンチマークを参照してください。

エージェントの作成の詳細については、「Genie エージェントの作成と管理」および「効果的な Genie エージェントのキュレーション」を参照してください。

新しい Genie エージェントを作成することも、既存の Genie エージェントを使用することもできます。

新しいエージェントを作成する

Genie エージェントの作成 API を使用してプログラムで Genie エージェントを作成します。次の例では、ベストプラクティスに従った適切に構造化されたエージェントを示します。プレースホルダーを実際の値に置き換えます。

POST /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "description": "Space for analyzing sales performance and trends",
  "parent_path": "/Workspace/Users/<username>",
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g7\",\"question\":[\"Show top 10 customers by revenue\"]},{\"id\":\"c3d4e5f6g7h8\",\"question\":[\"Compare sales by region for Q1 vs Q2\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
  "title": "Sales Analytics Space",
  "warehouse_id": "<warehouse-id>"
}

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "serialized_space": "{\n  \"version\": 1,\n  \"config\": {\n    \"sample_questions\": [\n      {\n        \"id\": \"a1b2c3d4e5f600000000000000000000\",\n        \"question\": [\n          \"What were total sales last month?\"\n        ]\n      },\n      {\n        \"id\": \"b2c3d4e5f6g700000000000000000000\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ]\n      },\n      {\n        \"id\": \"c3d4e5f6g7h800000000000000000000\",\n        \"question\": [\n          \"Compare sales by region for Q1 vs Q2\"\n        ]\n      }\n    ]\n  },\n  \"data_sources\": {\n    \"tables\": [\n      {\n        \"identifier\": \"sales.analytics.orders\",\n        \"description\": [\n          \"Transactional order data including order date, amount, and customer information\"\n        ],\n        \"column_configs\": [\n          {\n            \"column_name\": \"order_date\",\n            \"get_example_values\": true\n          },\n          {\n            \"column_name\": \"status\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          },\n          {\n            \"column_name\": \"region\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          }\n        ]\n      },\n      {\n        \"identifier\": \"sales.analytics.customers\"\n      },\n      {\n        \"identifier\": \"sales.analytics.products\"\n      }\n    ]\n  },\n  \"instructions\": {\n    \"text_instructions\": [\n      {\n        \"id\": \"01f0b37c378e1c91\",\n        \"content\": [\n          \"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"\n        ]\n      }\n    ],\n    \"example_question_sqls\": [\n      {\n        \"id\": \"01f0821116d912db\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ],\n        \"sql\": [\n          \"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\n          \"FROM sales.analytics.orders o\\n\",\n          \"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\n          \"GROUP BY customer_name\\n\",\n          \"ORDER BY total_revenue DESC\\n\",\n          \"LIMIT 10\"\n        ]\n      },\n      {\n        \"id\": \"01f099751a3a1df3\",\n        \"question\": [\n          \"What were total sales last month\"\n        ],\n        \"sql\": [\n          \"SELECT SUM(order_amount) as total_sales\\n\",\n          \"FROM sales.analytics.orders\\n\",\n          \"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\n          \"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"\n        ]\n      }\n    ],\n    \"join_specs\": [\n      {\n        \"id\": \"01f0c0b4e8151\",\n        \"left\": {\n          \"identifier\": \"sales.analytics.orders\",\n          \"alias\": \"orders\"\n        },\n        \"right\": {\n          \"identifier\": \"sales.analytics.customers\",\n          \"alias\": \"customers\"\n        },\n        \"sql\": [\n          \"orders.customer_id = customers.customer_id\"\n        ]\n      }\n    ],\n    \"sql_snippets\": {\n      \"filters\": [\n        {\n          \"id\": \"01f09972e66d1\",\n          \"sql\": [\"orders.order_amount > 1000\"],\n          \"display_name\": \"high value orders\",\n          \"synonyms\": [\"large orders\", \"big purchases\"]\n        }\n      ],\n      \"expressions\": [\n        {\n          \"id\": \"01f09974563a1\",\n          \"alias\": \"order_year\",\n          \"sql\": [\"YEAR(orders.order_date)\"],\n          \"display_name\": \"year\"\n        }\n      ],\n      \"measures\": [\n        {\n          \"id\": \"01f09972611f1\",\n          \"alias\": \"total_revenue\",\n          \"sql\": [\"SUM(orders.order_amount)\"],\n          \"display_name\": \"total revenue\",\n          \"synonyms\": [\"revenue\", \"total sales\"]\n        }\n      ]\n    }\n  }\n}\n"
}

既存のエージェントを使用する

Genie エージェントが既にある場合は、 Genie エージェントの一覧表示 API を使用してスペース ID を見つけることができます。 Genie エージェント の [設定] タブからスペース ID を見つけてコピーすることもできます。

GET /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "spaces": [
    {
      "description": "Space for analyzing sales performance and trends",
      "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g7\",\"question\":[\"Show top 10 customers by revenue\"]},{\"id\":\"c3d4e5f6g7h8\",\"question\":[\"Compare sales by region for Q1 vs Q2\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
      "space_id": "3c409c00b54a44c79f79da06b82460e2",
      "title": "Sales Analytics Space",
      "warehouse_id": "<warehouse-id>",
    },
    {
      "description": "Space for marketing campaign analysis",
      "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"Show total revenue by state\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.gold.orders\"}]}}",
      "space_id": "7f8e9d0c1b2a3456789abcdef0123456",
      "title": "Marketing Analytics Space",
      "warehouse_id": "<warehouse-id>",
    }
  ]
}

後続の API 呼び出しで応答からの space_id を使用します。

serialized_space フィールドについて

serialized_space フィールドは、Genie エージェントの構成とデータソースを定義する JSON 文字列です。 API 要求では、この JSON を文字列としてエスケープする必要があります。フィールドには次のものが含まれます。

version: 下位互換性のためのスキーマバージョン番号。次の例に示すように、 2 を使用します。
config: エージェントの構成には次が含まれます。
- sample_questions: ユーザーをガイドするための質問の例。各質問には 、ID (32 文字の 16 進文字列) と質問 (文字列の配列) が必要です。
data_sources: エージェントで使用できるデータソース:
- tables: 識別子 (3 レベルの名前空間)、省略可能な説明、および省略可能な column_configsを持つテーブルオブジェクトの配列。
- metric_views: メトリックビューオブジェクトの配列 (テーブルと同じ構造)。
instructions: エージェントの構造化された手順:
- text_instructions: LLM の概要ガイダンス。
- example_question_sqls: SQL 回答を含む質問の例 (必要に応じて パラメーター と usage_guidanceを使用)。
- sql_functions: エージェントで使用できる SQL 関数への参照。
- join_specs: テーブル間の事前定義済みの結合リレーションシップ。 sql フィールドには、結合条件、バックティック引用符で囲まれたエイリアス参照、リレーションシップ型の注釈 ("--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--"など) の 2 つの要素が必要です。「結合スペックの形式」を参照してください。
- sql_snippets: 再利用可能な フィルター、式、 メジャー。
ベンチマーク: エージェントの品質を評価するための質問。各質問には、実際の SQL 回答が含 まれています。

エージェントの作成例の serialized_space フィールドのエスケープされていないバージョンは次のようになります。

{
  "version": 2,
  "config": {
    "sample_questions": [
      {
        "id": "a1b2c3d4e5f60000000000000000000a",
        "question": ["What were total sales last month?"]
      },
      {
        "id": "b2c3d4e5f6a70000000000000000000b",
        "question": ["Show top 10 customers by revenue"]
      }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.customers",
        "description": ["Customer master data including contact information and account details"],
        "column_configs": [
          {
            "column_name": "customer_id",
            "description": ["Unique identifier for each customer"],
            "synonyms": ["cust_id", "account_id"]
          },
          {
            "column_name": "customer_name",
            "enable_entity_matching": true
          },
          {
            "column_name": "internal_notes",
            "exclude": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.orders",
        "description": ["Transactional order data including order date, amount, and customer information"],
        "column_configs": [
          {
            "column_name": "order_date",
            "enable_format_assistance": true
          },
          {
            "column_name": "region",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          },
          {
            "column_name": "status",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.products"
      }
    ],
    "metric_views": [
      {
        "identifier": "sales.analytics.revenue_metrics",
        "description": ["Pre-aggregated revenue metrics by region and time period"],
        "column_configs": [
          {
            "column_name": "period",
            "description": ["Time period for the metric (monthly, quarterly, yearly)"],
            "enable_format_assistance": true
          }
        ]
      }
    ]
  },
  "instructions": {
    "text_instructions": [
      {
        "id": "01f0b37c378e1c9100000000000000a1",
        "content": [
          "When calculating revenue, sum the order_amount column. ",
          "When asked about 'last month', use the previous calendar month. ",
          "Round all monetary values to 2 decimal places."
        ]
      }
    ],
    "example_question_sqls": [
      {
        "id": "01f0821116d912db00000000000000b1",
        "question": ["Show top 10 customers by revenue"],
        "sql": [
          "SELECT customer_name, SUM(order_amount) as total_revenue\n",
          "FROM sales.analytics.orders o\n",
          "JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\n",
          "GROUP BY customer_name\n",
          "ORDER BY total_revenue DESC\n",
          "LIMIT 10"
        ]
      },
      {
        "id": "01f099751a3a1df300000000000000b2",
        "question": ["What were total sales last month"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\n",
          "AND order_date < DATE_TRUNC('month', CURRENT_DATE)"
        ]
      },
      {
        "id": "01f099751a3a1df300000000000000b3",
        "question": ["Show sales for a specific region"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE region = :region_name"
        ],
        "parameters": [
          {
            "name": "region_name",
            "type_hint": "STRING",
            "description": ["The region to filter by (e.g., 'North America', 'Europe')"],
            "default_value": {
              "values": ["North America"]
            }
          }
        ],
        "usage_guidance": ["Use this example when the user asks about sales filtered by a specific geographic region"]
      }
    ],
    "sql_functions": [
      {
        "id": "01f0c0b4e815100000000000000000f1",
        "identifier": "sales.analytics.fiscal_quarter"
      }
    ],
    "join_specs": [
      {
        "id": "01f0c0b4e815100000000000000000c1",
        "left": {
          "identifier": "sales.analytics.orders",
          "alias": "orders"
        },
        "right": {
          "identifier": "sales.analytics.customers",
          "alias": "customers"
        },
        "sql": ["`orders`.`customer_id` = `customers`.`customer_id`", "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--"],
        "comment": ["Join orders to customers on customer_id"],
        "instruction": ["Use this join when you need customer details for order analysis"]
      }
    ],
    "sql_snippets": {
      "filters": [
        {
          "id": "01f09972e66d100000000000000000d1",
          "sql": ["orders.order_amount > 1000"],
          "display_name": "high value orders",
          "synonyms": ["large orders", "big purchases"],
          "comment": ["Filters to orders over $1000"],
          "instruction": ["Use when the user asks about high-value or large orders"]
        }
      ],
      "expressions": [
        {
          "id": "01f09974563a100000000000000000e1",
          "alias": "order_year",
          "sql": ["YEAR(orders.order_date)"],
          "display_name": "year",
          "synonyms": ["fiscal year", "calendar year"],
          "comment": ["Extracts the year from order date"],
          "instruction": ["Use for year-over-year analysis"]
        }
      ],
      "measures": [
        {
          "id": "01f09972611f100000000000000000f1",
          "alias": "total_revenue",
          "sql": ["SUM(orders.order_amount)"],
          "display_name": "total revenue",
          "synonyms": ["revenue", "total sales"],
          "comment": ["Sum of all order amounts"],
          "instruction": ["Use this measure for revenue calculations"]
        }
      ]
    }
  },
  "benchmarks": {
    "questions": [
      {
        "id": "01f0d0b4e815100000000000000000g1",
        "question": ["What is the average order value?"],
        "answer": [
          {
            "format": "SQL",
            "content": ["SELECT AVG(order_amount) as avg_order_value\n", "FROM sales.analytics.orders"]
          }
        ]
      }
    ]
  }
}

エージェントを構築するときに、この JSON 構造を作成し、API 要求の文字列としてエスケープします。スキーマの詳細については、 Genie エージェント API の作成に関するリファレンスを参照してください。

serialized_spaceの検証規則

serialized_space JSON は、次の検証規則に準拠している必要があります。無効な JSON は、エージェントの作成または更新中に拒否されます。

バージョン

[バージョン] フィールド: 必須。新しいエージェントには 2 を使用します。バージョン番号は下位互換性のために存在します。

ID フォーマット

すべての ID フィールドは 、32 文字の小文字の 16 進文字列 (ハイフンなしの UUID 形式) である必要があります。

有効:a1b2c3d4e5f60000000000000000000a
無効: a1b2c3d4e5f6 (短すぎる)、 A1B2C3D4E5F60000000000000000000A (大文字)、 a1b2c3d4-e5f6-0000-0000-00000000000a (ハイフンを含む)

ID は次の場合に必要です。

config.sample_questions[].id
instructions.text_instructions[].id
instructions.example_question_sqls[].id
instructions.join_specs[].id
instructions.sql_snippets.filters[].id
instructions.sql_snippets.expressions[].id
instructions.sql_snippets.measures[].id
benchmarks.questions[].id (ベンチマークが含まれている場合)

次のコマンドを使用して、有効な ID を生成できます。

python3 -c "import random,datetime;t=int((datetime.datetime.now()-datetime.datetime(1582,10,15)).total_seconds()*1e7);print(f'{(t&0xFFFFFFFFFFFF0000)|(1<<12)|((t&0xFFFF)>>4):016x}{random.getrandbits(62)|0x8000000000000000:016x}')"

これにより、時間順 UUID が生成されます。シーケンスで生成された ID は、作成された順序でアルファベット順に並べ替えられます。これは、並べ替えの要件を自動的に満たします。

ソーティング要件

ID または識別子を含むコレクションは、事前に並べ替える必要があります。システムは、配列が既に並べ替えられていることを検証し、並べ替えられていない入力を拒否します。

コレクション	並べ替えキー
`data_sources.tables`	`identifier` (アルファベット順)
`data_sources.metric_views`	`identifier` (アルファベット順)
`data_sources.tables[].column_configs`	`column_name` (アルファベット順)
`data_sources.metric_views[].column_configs`	`column_name` (アルファベット順)
`config.sample_questions`	`id` (アルファベット順)
`instructions.text_instructions`	`id` (アルファベット順)
`instructions.example_question_sqls`	`id` (アルファベット順)
`instructions.sql_functions`	`(id, identifier)` タプル (アルファベット順)
`instructions.join_specs`	`id` (アルファベット順)
`instructions.sql_snippets.filters`	`id` (アルファベット順)
`instructions.sql_snippets.expressions`	`id` (アルファベット順)
`instructions.sql_snippets.measures`	`id` (アルファベット順)
`benchmarks.questions`	`id` (アルファベット順)

一意性制約

質問 ID: config.sample_questions と benchmarks.questions 内のすべての ID は、両方のコレクションで一意である必要があります。
命令 ID: text_instructions、 example_question_sqls、 sql_functions、 join_specs、およびすべての sql_snippets の種類にわたるすべての ID は一意である必要があります。
列の構成: (table_identifier, column_name) の組み合わせは、エージェント内で一意である必要があります。

サイズと長さの制限

文字列の長さ: 個々の文字列要素は 25,000 文字に制限されます。
配列サイズ: 繰り返しフィールドは 10,000 項目に制限されます。
テキスト命令: エージェントごとに最大 1 つのテキスト命令を使用できます。
テーブルとメトリックビュー: ワークスペース固有の制限に従います。
SQL コンテンツ: sql フィールドと join_specs.sql フィールドのクエリテキストには、長さの制限があります。

結合スペックの形式

各結合仕様の sql フィールドには 、次の 2 つの要素を含む必要があります。

バッククォートで囲まれたエイリアスを参照する結合条件:
```
"`orders`.`customer_id` = `customers`.`customer_id`"
```
次の形式のリレーションシップ型注釈。
```
"--rt=FROM_RELATIONSHIP_TYPE_<CARDINALITY>--"
```
有効なカーディナリティ値:
- FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
- FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
- FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
- FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

リレーションシップ型の注釈を省略すると、API は解析エラーで要求を拒否します。複数列結合の場合は、リレーションシップごとに個別の結合仕様を作成します。

その他の要件

テーブル識別子: 3 レベルの名前空間形式 (catalog.schema.table) を使用する必要があります。
ベンチマーク回答: 各ベンチマークの質問には、形式が SQL に設定された 1 つの回答が必要です。
SQL スニペット: フィルター、式、およびメジャーの SQL フィールドを空にすることはできません。

Genie API リファレンス

前節では、Genieエージェントの準備方法とワークスペース間のエージェント管理方法を示します。会話の開始、メッセージ送信、Genieエージェントからの結果取得については、REST APIリファレンスを参照してください:

エージェントモードのAPI:エージェントモードでプロンプトを送信し、その推論やSQL結果をストリーミングし、引用付きの最終レポートを受け取ることができます。エージェントモードAPIリファレンスを参照してください。
チャットモードAPI:チャットモードの会話を開始し、フォローアップの質問をし、生成されたSQLやクエリ結果、可視化を取得できます。 Conversation APIのリファレンスを参照してください。

ベストプラクティスと制限

Genie API を使用するためのベストプラクティス

Genie API を使用するときにパフォーマンスと信頼性を維持するには:

指数バックオフを使用して再試行ロジックを実装する: API は失敗した要求を再試行しないため、独自のキューと指数バックオフを追加します。これにより、アプリケーションは一時的な障害を処理し、増加に伴う不要な繰り返し要求を回避できます。
ログ API 応答: API 要求と応答の包括的なログ記録を実装して、デバッグ、使用パターンの監視、コストの追跡に役立ちます。
状態の更新を 1 秒から 5 秒ごとにポーリングする: COMPLETED、 FAILED、 CANCELLEDなどの確定的なメッセージの状態が受信されるまでポーリングを続行します。ほとんどのクエリでポーリングを 10 分に制限します。 10 分後に決定的な応答がない場合は、ポーリングを停止してタイムアウトエラーを返すか、後でクエリの状態を手動で確認するようにユーザーに求めます。
ポーリングに指数バックオフを使用する: ポーリング間の遅延を最大 1 分まで増やします。これにより、実行時間の長いクエリに対する不要な要求が減りますが、高速なクエリの待機時間は短くなります。
セッションごとに新しい会話を開始する: 意図しないコンテキストの再利用によって精度が低下する可能性があるため、セッション間で会話スレッドを再利用しないようにします。
会話の制限を維持する: 古い会話を管理し、10,000 件の会話制限を超えないようにするには:
1. GET /api/2.0/genie/spaces/{space_id}/conversations エンドポイントを使用して、エージェント内のすべての既存の会話スレッドを表示します。
2. 古い会話やテスト会話など、不要になった会話を特定します。
3. DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} エンドポイントを使用して、プログラムによって会話を削除します。

エージェントを監視する

アプリケーションを設定したら、Databricks UI で質問と応答を監視できます。

ユーザーが質問する可能性がある質問の種類と受け取った回答について学習できるように、エージェントをテストするようユーザーに勧めます。エージェントのテストを開始するのに役立つガイダンスをユーザーに提供します。 [監視] タブを使用して、質問と回答を表示します。エージェントの監視を参照してください。

監査ログを使用して、Genie エージェントのアクティビティを監視することもできます。 Genie エージェントのイベントを参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-08-27