メインコンテンツまでスキップ
に最終更新

Genie Agent APIを使用する

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

注記

Genieエージェントは以前、Genie Spaceとして知られていました。

概要​

Genie APIは2種類の機能を提供します：

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

このページでは、会話 APIs と管理 APIs の両方について説明しています。会話 APIs を呼び出す前に、適切にキュレーションされた Genie Agent を準備してください。エージェントは、Genie が質問を解釈し、回答を生成するために使用するコンテキストを提供します。エージェントが不完全であるかテストされていない場合、API 統合が正しくても、ユーザーは誤った結果を受け取る可能性があります。このガイドでは、Genie API と効果的に連携するエージェントを作成するために必要な最小限のセットアップについて説明しています。

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

前提条件​

Genie APIを使用するには、以下が必要です。

  • Databricks SQL エンタイトルメントが付与されたDatabricksワークスペースへのアクセス。
  • SQLプロまたはServerless SQLウェアハウスに対するCAN USE権限が少なくとも1つ必要です。

使い始める​

Databricks認証を構成します。​

ブラウザにアクセスできるユーザーが存在する本番運用ユースケースの場合は、ユーザー向けOAuth (OAuth U2M)を使用してください。ブラウザベースの認証が不可能な状況では、Service Principalを使用してAPIで認証します。See OAuth for Service Principals (OAuth M2M)を参照してください。Service Principalは、必要なデータとSQLウェアハウスにアクセスする権限を持っている必要があります。

詳細を収集する​

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

    例： https://cust-success.cloud.databricks.com/

  • warehouse ID: 少なくとも CAN USE 権限を持つ SQLウェアハウスの ID が必要です。warehouse ID を見つけるには:

    1. ワークスペースの SQLウェアハウス に移動します。
    2. 使用するwarehouseを選択します。
    3. URLまたはwarehouseの詳細ページからwarehouse IDをコピーします。

    または、List warehouses Endpoint GET /api/2.0/sql/warehousesを使用して、アクセス権のあるすべてのSQLウェアハウスのリストをプログラムで取得できます。応答にはwarehouse IDが含まれます。

Genie Agentを作成または選択します​

十分に構造化されたGenie Agentには、次の特性があります：

  • 適切にアノテーションが付けられたデータを使用します ：Genieはテーブルのメタデータとカラムコメントに依存しています。Unity Catalogデータソースに明確で分かりやすいコメントがあることを確認してください。
  • ユーザーによるテスト済み ：エンド ユーザーから想定される質問をして、エージェントをテストします。テストを使用して、SQL クエリーの例を作成し、改善します。
  • **会社固有のコンテキストが含まれます**: 指示、SQLの例、および関数を追加します。SQLの例と指示を追加するを参照してください。少なくとも5つのテスト済みSQLクエリーを目指してください。
  • 精度をテストするベンチマークを使用します ：想定されるユーザーの質問に基づいて、少なくとも5つのベンチマーク質問を追加してください。ベンチマークを参照してください。

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

新しい Genie Agent を作成するか、既存の Genie Agent を使用できます。

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

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"
}

serialized_spaceフィールドの理解​

serialized_spaceフィールドは、Genie Agentの構成とデータソースを定義するJSON文字列です。APIリクエストでは、このJSONは文字列としてエスケープする必要があります。フィールドの内容：

  • バージョン ：下位互換性のためのスキーマバージョン番号。以下の例に示すように、2 を使用します。

  • config ：エージェント構成（以下を含む）：

    • **sample_questions：** ユーザーをガイドするための質問例。各質問には**ID**（32文字の16進数文字列）と**質問**（文字列の配列）が必要です。

  • data_sources ：エージェントが利用できるデータソース：

    • tables ： identifier （3 レベルの名前空間）、任意の description 、および任意の column_configs を持つ table オブジェクトの配列。
    • **メトリクスビュー**: メトリクスビューオブジェクトの配列（テーブルと同じ構造）。

  • 指示 : エージェント向けの構造化された指示:

    • LLM向けの**text_instructions**: 高レベルのガイダンス
    • example_question_sqls : SQL の回答を伴う質問の例で、オプションで パラメーター と usage_guidance を伴います。
    • sql_functions ：エージェントが利用できるSQL関数への参照です。
    • join_specs ：テーブル間の事前定義された結合リレーションシップ。sqlフィールドは、結合条件（バッククォートで囲まれたエイリアス参照を使用）、およびリレーションシップタイプの注釈（例: "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--"）という2つの要素を正確に必要とします。「結合仕様の形式」を参照してください。
    • SQLスニペット ：再利用可能な フィルター 、 式 、および メジャー 。

  • **ベンチマーク：**エージェントの品質を評価するための質問で、それぞれに正解SQLの**回答**が含まれます。

エージェント作成例のserialized_spaceフィールドのエスケープされていないバージョンは次のとおりです：

JSON
{
  "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 Agent 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を生成できます：

Bash
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 （アルファベット順）

コレクション

並べ替えキー

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つの要素 を含める必要があります。

  1. バッククォートで引用されたエイリアスの参照を使用する結合条件:

    Text
    "`orders`.`customer_id` = `customers`.`customer_id`"

  2. 次の形式のリレーションシップタイプの注釈：

    Text
    "--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 Agent を構成した後、コンテキストを持つ複数ターンの会話で質問したり、結果を取得したり、会話を維持したりするには、会話 API Endpoint を使用してください。

会話を開始する​

The Start conversation Endpoint POST /api/2.0/genie/spaces/{space_id}/start-conversation 起動します a new conversation in your Genie Agent.

プレースホルダーをDatabricksインスタンス、Genie Agent 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の推論トレースにアクセスするには、タイプGenieQueryAttachmentsのquery_attachmentsオブジェクトのattachmentsフィールドを確認します。存在する場合、Genieが応答を生成するために使用したステップバイステップの推論が含まれています。完全なフィールドの詳細については、Get message API referenceを参照してください。

クエリー結果の取得​

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

注記

Genie Agent UI とは異なり、Genie Conversation API は、Genie が予備的な回答を表示し、検査後にそれを更新する 2 フェーズの応答パターンをサポートしていません。ユーザーに増分的な進捗状況を表示するには、COMPLETED を待つのではなく、PENDING_WAREHOUSE または EXECUTING_QUERY の状態でポーリング中に attachments フィールドを検査します。

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を参照してください。

視覚化結果の取得 (ベータ版)​

By default、Genie Conversation APIは表形式のクエリー結果を返します。ビジュアライゼーションの結果も取得するには、会話を開始するかメッセージを作成する際にenable_visualization: trueを設定します。有効にすると、レスポンスのattachmentsフィールドには、ビジュアライゼーションtitleとそれが生成されたquery_attachment_idを含む、GenieVizAttachment型のvizオブジェクトが含まれます。

ビジュアライゼーションをdownloadするには、downloadメッセージ添付ビジュアライゼーションEndpointを使用します。

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リファレンス」を参照してください。

注記

ビジュアライゼーションの結果は、Private Linkワークスペースではサポートされていません。

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

応答を受信したら、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 Endpointを使用して、メッセージにテキストコメントを追加したり、既存のコメントを一覧表示したりできます。

メッセージにコメントを追加するには、「Create message comment endpoint」 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>"
}

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

エージェントと会話データを取得​

Genie APIは、既存のエージェントおよび会話から構成およびヒストリカルデータを取得するための追加のEndpointを提供します。

エージェント構成を取得​

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

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

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\"]}]"
}

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

ユーザーが過去の会話スレッドを参照できるようにするには、特定の会話スレッドのすべてのメッセージを取得するために、会話メッセージのEndpoint GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages を使用します。

分析用の会話データを取得する​

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

  1. エージェント内のすべての既存の会話スレッドを取得するには、GET /api/2.0/genie/spaces/{space_id}/conversations Endpointを使用します。

    • default では、この Endpoint はリクエストしているユーザーの会話のみを返します。エージェント内のすべてのユーザーからの会話を返すには、include_all パラメーターを true に設定します。include_all を使用するには、エージェントに対する少なくとも CAN MANAGE 権限が必要です。

  2. 返された各会話IDについて、その会話のメッセージのリストを取得するには、GET /api/2.0/genie/spaces/{space_id}/conversations Endpointを使用します。

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

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

Genie API を使用する際に性能と信頼性を維持するには：

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

エージェントを監視する​

アプリケーションがセットアップされた後、Databricks UI で質問と応答をモニタリングできます。

ユーザーがエージェントをテストするように促し、ユーザーが尋ねる可能性のある質問の種類と、受け取る応答について学びます。ユーザーがエージェントのテストを開始するのに役立つように、ガイダンスを提供します。質問と応答を表示するには、 モニタリング タブを使用します。エージェントを監視するを参照してください。

Genie Agentのアクティビティを監視するために、監査Logsを使用することもできます。Genie Agent イベントをご覧ください。

このページの見出し