Genie Agents API の使用

Genie Agents API を使用して、Genie Agents を独自のチャットボット、エージェント、またはアプリケーションに統合します。この API は、ステートフルな自然言語データクエリ用の Conversation API (フォローアップの質問と履歴を含む) と、ワークスペース間で Genie エージェントを作成、構成、デプロイする CI/CD ワークフロー用の管理 API を提供します。

Note

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

Overview

Genie API には、次の 2 種類の機能があります。

会話 API: アプリケーション、チャットボット、およびエージェントフレームワークで自然言語データクエリを有効にします。これらの API は、ユーザーがフォローアップの質問をしたり、時間の経過と同時に自然にデータを探索したりできるステートフルな会話をサポートします。
管理 API: ワークスペース間での Genie エージェントのプログラムによる作成、構成、デプロイを有効にします。 CI/CD パイプライン、バージョン管理、および自動エージェント管理には、これらの API を使用します。

このページでは、会話 API と管理 API の両方について説明します。会話 API を呼び出す前に、適切にキュレーションされた Genie エージェントを準備します。エージェントは、Genie が質問を解釈して回答を生成するために使用するコンテキストを提供します。エージェントが不完全または未テストの場合、正しい API 統合を使用しても、ユーザーは間違った結果を受け取る可能性があります。このガイドでは、Genie 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 フィールドを空にすることはできません。

会話 API の使用

Genie エージェントを構成したら、会話 API エンドポイントを使用して質問し、結果を取得し、コンテキストを使用して複数ターンの会話を維持します。

会話を開始する

会話の開始エンドポイントPOST /api/2.0/genie/spaces/{space_id}/start-conversationは Genie エージェントで新しい会話を開始します。

プレースホルダーを Databricks インスタンス、Genie エージェント ID、認証トークンに置き換えます。成功した応答の例は、要求に従います。これには、フォローアップの質問のためにこの会話に再度アクセスするために使用できる詳細が含まれています。

POST /api/2.0/genie/spaces/{space_id}/start-conversation

HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
    "content": "<your question>",
}


Response:

{
  "conversation": {
    "created_timestamp": 1719769718,
    "id": "6a64adad2e664ee58de08488f986af3e",
    "last_updated_timestamp": 1719769718,
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "title": "Give me top sales for last month",
    "user_id": 12345
  },
  "message": {
    "attachments": null,
    "content": "Give me top sales for last month",
    "conversation_id": "6a64adad2e664ee58de08488f986af3e",
    "created_timestamp": 1719769718,
    "error": null,
    "id": "e1ef34712a29169db030324fd0e1df5f",
    "last_updated_timestamp": 1719769718,
    "query_result": null,
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "status": "IN_PROGRESS",
    "user_id": 12345
  }
}

生成された SQL を取得する

応答で conversation_id と message_id を使用してメッセージの生成状態を確認し、Genie から生成された SQL を取得します。要求と応答の詳細については、 GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} を参照してください。

値を次の要求に置き換えます。

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

次の応答例は、メッセージの詳細を報告します。

Response:

{
  "attachments": null,
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "id": "e1ef34712a29169db030324fd0e1df5f",
  "last_updated_timestamp": 1719769718,
  "query_result": null,
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "IN_PROGRESS",
  "user_id": 12345
}

attachments フィールドは、処理中に段階的に設定されます。状態が PENDING_WAREHOUSE または EXECUTING_QUERYの場合は、 attachments フィールドの読み取りを既に開始できます。応答は、生成された SQL クエリから始まり、説明、フォローアップの質問、および追加のコンテキストから始めて、増分的に設定されます。 COMPLETED状態は、応答プロセスが完全に完了し、ポーリングを停止できることを示しますが、クライアントがポーリング中に完了を待機するのではなく、応答を検査する場合は、意味のあるコンテンツを先に使用できます。

信頼された資産を使用して応答が生成されたかどうかを確認するには、応答のattachmentsフィールドでquery.parameters オブジェクトを確認します。その存在は、信頼できる資産からの回答を示します。

Genie の推論トレースにアクセスするには、attachments フィールドで、query_attachments型のGenieQueryAttachments オブジェクトを確認します。存在する場合は、応答の生成に使用される Genie の段階的な推論が含まれます。完全なフィールドの詳細については、メッセージの取得 API リファレンスを参照してください。

クエリ結果を取得する

attachments配列には Genie の応答が含まれています。これには、生成されたテキスト応答 (text)、存在する場合のクエリステートメント (query)、および関連付けられたクエリ結果を取得するために使用できる識別子 (attachment_id) が含まれます。次の例のプレースホルダーを置き換えて、生成されたクエリ結果を取得します。

Note

Genie エージェント UI とは異なり、Genie Conversation API は、Genie が暫定的な回答を示し、検査後に更新する 2 フェーズ応答パターンをサポートしていません。ユーザーに段階的な進行状況を表示するには、attachmentsを待つ代わりに、PENDING_WAREHOUSEまたはEXECUTING_QUERY状態のポーリング中にCOMPLETED フィールドを調べます。

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/query-result/{attachment_id}
Authorization: Bearer <your_authentication_token>

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-resultを参照してください。

視覚化の結果を取得する (ベータ)

既定では、Genie Conversation API は表形式のクエリ結果を返します。また、視覚エフェクトの結果を取得するには、会話の開始時またはメッセージの作成時に enable_visualization: true を設定します。有効にすると、応答内のattachmentsフィールドには、vizビジュアライゼーションと、その生成元となったGenieVizAttachmentを含む、title型のquery_attachment_idオブジェクトが含まれます。

視覚化をダウンロードするには、ダウンロードメッセージ添付ファイルの視覚化エンドポイントを使用します。

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/download-visualization
Authorization: Bearer <your_authentication_token>

Genie API リファレンスを参照してください。

可視化のダウンロードは地域ごとに限定されています。サポートされている地域の一覧については、エージェント機能の可用性をご覧ください。

フォローアップの質問をする

応答を受け取ったら、 conversation_id を使用して会話を続行します。前のメッセージからのコンテキストは保持され、フォローアップ応答で使用されます。要求と応答の詳細については、 POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messagesを参照してください。

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages
HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
  "content": "Which of these customers opened and forwarded the email?",
}

メッセージにコメントを追加する

メッセージコメント API エンドポイントを使用して、メッセージにテキストコメントを追加したり、既存のコメントを一覧表示したりできます。

メッセージにコメントを追加するには、メッセージコメントの作成エンドポイントを使用しますPOST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments:

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "content": "<your comment text>"
}

メッセージの既存のコメントを一覧表示するには、メッセージコメントの一覧表示エンドポイントを使用します。

エージェントと会話のデータを取得する

Genie API には、既存のエージェントと会話から構成データと履歴データを取得するための追加のエンドポイントが用意されています。

エージェント構成を取得する

Get Genie Agent API を使用してエージェント情報を取得する場合は、serialized_space パラメーターを include_serialized_space に設定することで、true フィールドを応答に含めることができます。 serialized_space フィールドには、命令、ベンチマーク、結合、その他の構成の詳細など、Genie エージェントのシリアル化された文字列形式が含まれます。

Genie エージェントの作成 API と Genie エージェントの更新 API を使用して、このシリアル化された表現を使用して、ワークスペース間で Genie エージェントを昇格させるか、エージェント構成のバックアップを作成します。

GET要求の例:

GET /api/2.0/genie/spaces/{space_id}?include_serialized_space=true
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f600000000000000000000\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g700000000000000000000\",\"question\":[\"Show top 10 customers by revenue\"]}]},\"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\"]}]}}}"
}

古い会話スレッドを参照する

ユーザーが古い会話スレッドを参照できるようにするには、メッセージ交換メッセージの一覧表示エンドポイントGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages を使用して、特定の会話スレッドからすべてのメッセージを取得します。

分析のために会話データを取得する

エージェントマネージャーは、エージェントのすべてのユーザーに分析を求められた以前のすべてのメッセージをプログラムで取得できます。このデータを取得するには:

GET /api/2.0/genie/spaces/{space_id}/conversations エンドポイントを使用して、エージェント内のすべての既存の会話スレッドを取得します。
- 既定では、このエンドポイントは要求しているユーザーの会話のみを返します。エージェント内のすべてのユーザーからの会話を返すには、 include_all パラメーターを true に設定します。 include_allを使用するには、少なくともエージェントに対する CAN MANAGE アクセス許可が必要です。
- エンドポイントはパブリックAPI、Genie One、組み込みGenieを通じて開始された会話を返すため、 その結果はモニタリング タブに表示される履歴と一致します。「エージェントを監視する」を参照してください。
返される各会話 ID について、 GET /api/2.0/genie/spaces/{space_id}/conversations エンドポイントを使用して、その会話のメッセージの一覧を取得します。

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

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-20