Genie エージェントのエージェント モード API

エージェント モード API を使用すると、Azure Databricks UI ではなく、プログラムでエージェント モードを実行できます。 これらを使用して、チャットボット、スケジュールされたレポート、内部ツールなどの独自のアプリケーションにエージェント モードを統合します。

エージェント モード API のしくみ

エージェント モード API では、自然言語の質問を Genie エージェントに送信します。 調査計画を作成して調整し、SQL クエリを実行し、各結果に基づいて反復処理を行い、引用文献とサポート テーブルを含むレポートを返します。 結果は、Server-Sent イベント (SSE) としてクライアントにストリーム配信されます。

API には、エージェント モードと直接通信するために必要なエンドポイント、要求と応答の形式、ストリーミング イベントの種類が含まれます。 概念の概要については、「 エージェント モード」を参照してください。 UI エクスペリエンスについては、「 エージェント モードの使用」を参照してください。

Requirements

エージェント モード API を使用するには、ワークスペースが次の要件を満たしている必要があります。

• Unity カタログが有効になっています。 「Unity Catalog とは」を参照してください。
• パートナーが利用する AI 機能が有効になっています。 パートナーを利用した AI 機能を参照してください。
• 明確な命令とテーブル メタデータを持つ Genie エージェントがあります。 エージェント モードは、データに関する理由としてこのコンテキストに依存します。 効果的な Genie エージェントのキュレーションを参照してください。

概要

次の例は、プロンプトを送信し、ストリーミングされた応答を読み取る方法を示しています。

curl を使用して最初のプロンプトを送信する

次の要求は、自然言語の質問を Genie エージェントに送信し、応答を SSE としてストリーミングします。

curl -N --no-buffer \
  -X POST "https://${DATABRICKS_HOST}/api/2.0/genie/agents/${AGENT_ID}/responses" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{"type": "input_text", "text": "What were our top 10 customers by revenue last quarter?"}]
      }
    ]
  }'

イベントは、 event: と data: のペアとして到着します。

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"object":"response","id":"01f14fe4e34b...","model":"genie-agent","status":"in_progress","output":[],"conversation_id":"01f14fe4e338..."}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"sequence_number":1,"item":{"type":"reasoning","id":"01f14fe4f248...","status":"in_progress","content":[{"type":"reasoning_text","text":"I need to find revenue data..."}],"summary":[]}}

event: response.completed
data: {"type":"response.completed","sequence_number":42,"response":{"object":"response","id":"01f14fe4e34b...","model":"genie-agent","status":"completed","output":[...],"conversation_id":"01f14fe4e338...","created_at":1748383200}}

Databricks OpenAI クライアントを使用してストリームを読み取る (Python)

クライアントをインストールします。

pip install databricks-openai

応答を作成し、到着するたびに各イベントを処理します。

from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

AGENT_ID = "<your-agent-id>"  # Same as your Genie Agent ID

w = WorkspaceClient()
host = f"https://{w.config.host}" if not w.config.host.startswith("http") else w.config.host

client = DatabricksOpenAI(workspace_client=w)
client.base_url = f"{host}/api/2.0/genie/agents/{AGENT_ID}"

stream = client.responses.create(
    model="genie-agent",
    input=[
        {
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "What were our top 10 customers by revenue last quarter?"}],
        }
    ],
    stream=True,
)

conversation_id = None
for event in stream:
    if event.type == "response.created":
        conversation_id = event.response.conversation_id
    elif event.type == "response.output_item.done":
        print(f"Output item: {event.item.type}")
    elif event.type == "response.completed":
        print(f"Done: {event.response.status}")
    elif event.type == "response.failed":
        print(f"Failed: {event.response.error}")

フォローアップ プロンプトを送信する

会話を続けるには、最初の応答から conversation_id を渡します。

stream = client.responses.create(
    model="genie-agent",
    input=[
        {
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "Break that down by region"}],
        }
    ],
    stream=True,
    extra_body={"conversation_id": conversation_id},
)

エージェントは以前のターンのコンテキストを保持し、以前のクエリと結果を参照できます。

API リファレンス

エージェント モード API には、使用可能なエンドポイント、要求と応答の形式、SSE イベントのライフサイクル、データ モデル、およびエラー コードが含まれます。

基準URL

すべてのエンドポイントは、次のベース URL に対して相対的です。

https://<workspace-url>/api/2.0/genie/agents

Endpoints

API は、次のエンドポイントを提供します。

応答を作成する

新しいエージェント モードの応答を作成します。 エージェント モードの実行時に出力項目をリアルタイムで配信する SSE ストリームを返します。

POST /{agent_id}/responses

パスパラメーター

エンドポイントは、次のパス パラメーターを受け入れます。

リクエスト本文

要求本文は、次のフィールドを受け入れます。

SSE イベントのライフサイクル

ストリームは、 response.created イベントで開き、出力項目をストリームしてから、ターミナル イベントで閉じます。

response.created                    (once, stream opened)
  -> response.output_item.added     (0..N, new item appears)
  -> response.output_item.updated   (0..N, item content changed)
  -> response.output_item.done      (0..N, item finalized)
  -> response.completed             (once, terminal success)
     OR response.failed             (once, terminal failure)

すべてのイベントは、順序付けに使用できる単調に増加する sequence_number を伴います。

SSE イベントの種類

ストリームは、次のイベントの種類を出力します。

response.created

開始時に 1 回出力されます。 Responseと空のstatus: "in_progress"配列を持つoutput オブジェクトを格納します。

event: response.created
data: {
  "type": "response.created",
  "sequence_number": 0,
  "response": {
    "object": "response",
    "id": "01f15a22a7a816299374da7bc4264025",
    "model": "genie-agent",
    "status": "in_progress",
    "output": [],
    "conversation_id": "01f15a22a79a1699ab5e7f59563c5655",
    "created_at": 1748383200
  }
}

response.output_item.added

新しい出力項目が最初に表示されたときに出力されます。 アイテムは引き続き in_progress。

event: response.output_item.added
data: {
  "type": "response.output_item.added",
  "output_index": 0,
  "sequence_number": 1,
  "item": {
    "type": "reasoning",
    "id": "01f14fe4f24818d79f3e5963c31ec151",
    "status": "in_progress",
    "content": [
      {"type": "reasoning_text", "text": "I need to find the revenue data..."}
    ],
    "summary": []
  }
}

response.output_item.updated

function_call_outputのクエリ結果が到着したときなど、既存のアイテムのコンテンツが変更されたときに生成されます。 response.output_item.addedと同じペイロード図形を使用します。

response.output_item.done

出力項目が最終的な状態に達したときに出力されます。 response.output_item.addedと同じペイロード図形を使用します。 項目が既に完了している場合は、 added イベントと done イベントの両方が順番に出力されます。

response.completed

ターミナル成功イベント。 すべての出力項目で最終的な Response をラップします。

event: response.completed
data: {
  "type": "response.completed",
  "sequence_number": 42,
  "response": {
    "object": "response",
    "id": "01f14fe4e34b1b2293908bcece575499",
    "model": "genie-agent",
    "status": "completed",
    "output": [ ... ],
    "conversation_id": "01f14fe4e33816c6aa264b4661f998ea",
    "created_at": 1748383200
  }
}

response.failed

ターミナル エラー イベント。 Responseには、status: "failed"とerror オブジェクトがあります。 システム エラー メッセージ項目は、このイベントの直前に response.output_item.added として出力されます。 コードの完全な一覧については、「 ストリーミング エラー コード」を参照してください。

event: response.failed
data: {
  "type": "response.failed",
  "sequence_number": 5,
  "response": {
    "object": "response",
    "id": "01f14fe4e34b1b2293908bcece575499",
    "model": "genie-agent",
    "status": "failed",
    "output": [ ... ],
    "error": {
      "type": "server_error",
      "code": "sql_execution_error",
      "message": "Table 'sales' does not exist"
    },
    "conversation_id": "01f14fe4e33816c6aa264b4661f998ea",
    "created_at": 1748383200
  }
}

Concurrency

会話ごとに一度に生成できる応答は 1 つだけです。 既に進行中の応答がある会話に対する 2 番目の要求は、HTTP 409 を返します。

HTTP 409
{"error": {"type": "RESOURCE_CONFLICT", "message": "A response is already being generated for conversation <id>"}}

タイムアウト

SSE ストリームのサーバー側タイムアウトは 90 分です。 エージェント モードでは複数ステップの推論と SQL の実行が実行されるため、完全な期間、HTTP 接続を開いたままにしておきます。

会話アイテムを一覧表示する

会話内の出力項目をフラット リストとして取得します。 すべてのターンのアイテムは、ユーザー メッセージ、推論、クエリ、結果、レポートなど、時系列の順序で結合されます。 このエンドポイントは、 after および limit クエリ パラメーターを使用したカーソルベースの改ページ位置の修正をサポートします。

GET /{agent_id}/conversations/{conversation_id}/items

このエンドポイントを使用して、次の操作を行います。

• アプリケーションの会話の完全な履歴を表示します。
• SSE ストリームの切断後に結果を回復します。 応答が完了したら、このエンドポイントを呼び出します。
• 一度にすべての項目を読み込むのではなく、大規模な会話を段階的にフェッチします。

パスパラメーター

エンドポイントは、次のパス パラメーターを受け入れます。

クエリ パラメーター

エンドポイントは、次のクエリ パラメーターを受け入れます。

要求の例

会話内のすべてのアイテムを取得します。

GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items

ページ サイズを制限する:

GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?limit=5

最初に最新の項目を返します。

GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?order=desc&limit=5

次のページをフェッチします。

GET /api/2.0/genie/agents/01f14fe4e338.../conversations/01f14fe4e338.../items?limit=5&after=01f14fe4f24e10beacaa1720d4b79b59_output

応答

応答には Content-Type: application/json があり、 "object": "list"を含むページ分割されたリスト エンベロープです。

{
  "data": [
    {
      "type": "message",
      "role": "user",
      "content": [{ "type": "input_text", "text": "What were our top 10 customers by revenue last quarter?" }],
      "id": "01f14fe4e34b1b2293908bcece575499_input",
      "status": "completed"
    },
    {
      "type": "reasoning",
      "id": "01f14fe4f24818d79f3e5963c31ec151",
      "status": "completed",
      "content": [{ "type": "reasoning_text", "text": "I'll query the revenue table grouped by customer..." }],
      "summary": []
    },
    {
      "type": "function_call",
      "id": "01f14fe4f24e10beacaa1720d4b79b59",
      "call_id": "01f14fe4f24e10beacaa1720d4b79b59",
      "status": "completed",
      "name": "execute_sql",
      "arguments": "{\"title\": \"Top 10 Customers\", \"sql\": \"SELECT customer, SUM(revenue) AS total FROM sales GROUP BY customer ORDER BY total DESC LIMIT 10\"}"
    },
    {
      "type": "function_call_output",
      "id": "01f14fe4f24e10beacaa1720d4b79b59_output",
      "call_id": "01f14fe4f24e10beacaa1720d4b79b59",
      "status": "completed",
      "output": "Top 10 Customers\n\n| customer | total |\n| --- | --- |\n| Acme Corp | 1500000 |\n| Globex | 1200000 |"
    },
    {
      "type": "message",
      "id": "01f14fe5383f184a97ca1178af0d9356",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Here are your top 10 customers by revenue last quarter [1](https://host/genie/rooms/01f14fe4e338.../chats/01f14fe4e338...?o=12345&gra_focus=01f14fe4f24e...)."
        },
        {
          "type": "output_text",
          "text": "| customer | total |\n| --- | --- |\n| Acme Corp | 1500000 |\n| Globex | 1200000 |",
          "metadata": {
            "columns": [
              { "name": "customer", "type": "STRING" },
              { "name": "total", "type": "DOUBLE" }
            ],
            "preview_rows": [
              ["Acme Corp", "1500000"],
              ["Globex", "1200000"]
            ],
            "total_row_count": 10,
            "status": "available",
            "sql": "SELECT customer, SUM(revenue) AS total FROM sales GROUP BY customer ORDER BY total DESC LIMIT 10"
          }
        },
        {
          "type": "output_text",
          "text": "Acme Corp leads with $1.5M [1](https://host/genie/rooms/01f14fe4e338.../chats/01f14fe4e338...?o=12345&gra_focus=01f14fe4f24e...), followed by Globex at $1.2M [1](https://host/genie/rooms/01f14fe4e338.../chats/01f14fe4e338...?o=12345&gra_focus=01f14fe4f24e...)..."
        }
      ]
    }
  ],
  "first_id": "01f14fe4e34b1b2293908bcece575499_input",
  "last_id": "01f14fe5383f184a97ca1178af0d9356",
  "has_more": false,
  "status": "completed",
  "object": "list"
}

最上位の status フィールドには、会話の最新の応答の状態が反映されます。 応答がストリーミング中に "in_progress" され、完了後に "completed" または "failed" されます。 応答が完了したことを検出するには、このフィールドをポーリングします。

改ページ

応答には、次の 3 つの改ページ位置フィールドが含まれています。

すべてのアイテムをページングするには、 has_more が falseされるまでページを要求します。

items = []
after = None
while True:
    params = {"limit": 10}
    if after:
        params["after"] = after
    page = client.get(f"/conversations/{conv_id}/items", params=params)
    items.extend(page["data"])
    if not page["has_more"]:
        break
    after = page["last_id"]

data配列には、出力項目が時系列で格納されます。 ユーザー入力メッセージは、ID にmessageサフィックスが付いた_input項目として表示されます。

応答を理解する

このセクションでは、完全なエージェント モード応答を形成するために、出力項目がどのように一緒に収まるかについて説明します。

出力項目フロー

一般的なエージェント モードの応答では、次の順序で出力項目が生成されます。

reasoning              The agent's plan and analysis
    |
function_call          A SQL query the agent runs
    |
function_call_output   The query results, paired with the function_call above
    |
  ... (reasoning, function_call, and function_call_output repeat for each query) ...
    |
message                The final report, with structured text and inline tables

エージェントは複数のクエリを順番に実行し、各結果に基づいて分析を絞り込むことができます。 1 つの応答には、最終的なレポートの前に、多くの推論、クエリ、および結果サイクルを含めることができます。

function_callとfunction_call_outputのペアの方法

すべての SQL クエリでは、 call_idによってリンクされた出力項目のペアが生成されます。

• function_call は、エージェントが実行するクエリです。 arguments フィールドは、ツールの呼び出しを記述する JSON エンコード文字列です。
• function_call_output は結果です。 項目が完了すると、 output フィールドには、クエリ タイトルの後にデータのマークダウン テーブルが表示されます。

call_idは両方の項目で同じです。 function_call_output.idは常に{call_id}_output。

レポートを解析する

最終的な出力項目は、messageを含むrole: "assistant"です。 その content 配列には、次の 2 種類の複数の output_text チャンクが含まれています。

• テキスト チャンクには、インライン引用リンクを使用したストーリー分析が含まれます。
• テーブル チャンクは、マークダウン テーブルとしてレンダリングされるインライン クエリ結果を保持します。 各テーブル チャンクには、構造化されたクエリ結果データを含む metadata が含まれているため、クライアントはプログラムによってリッチ テーブルまたはグラフをレンダリングできます。

次の表のチャンクには、レンダリングされたマークダウンと構造化 metadataの両方が含まれています。

{
  "type": "output_text",
  "text": "| customer | total |\n| --- | --- |\n| Acme Corp | 1500000 |\n| Globex | 1200000 |",
  "metadata": {
    "columns": [
      { "name": "customer", "type": "STRING" },
      { "name": "total", "type": "DOUBLE" }
    ],
    "preview_rows": [
      ["Acme Corp", "1500000"],
      ["Globex", "1200000"]
    ],
    "total_row_count": 10,
    "status": "available",
    "sql": "SELECT customer, SUM(revenue) AS total FROM sales GROUP BY customer ORDER BY total DESC LIMIT 10"
  }
}

テーブル チャンク metadata オブジェクトには、次のフィールドが含まれています。

引用

レポート内のテキスト チャンクには、各要求をサポートする SQL クエリにリンクするインライン引用が含まれています。 各引用は、フォーム [N](url)のマークダウン リンクです。ここで、 N は連続する脚注番号であり、 url は、関連するクエリに重点を置いた Genie Agent UI を指します。

引用 URL の形式は次のとおりです。

https://<workspace-url>/genie/rooms/<space_id>/chats/<conversation_id>?o=<workspace_id>&gra_focus=<attachment_id>

URL には、次のコンポーネントが含まれています。

引用文献をレンダリングするには、クライアントに基づいて次のガイダンスに従います。

• Markdown レンダラーは、引用文献をクリック可能な脚注リンクとして自動的に表示します。
• プレーンテキストの場合は、 [N](url) を減らして引用文献を [N] または削除します。
• カスタム UI の場合は、URL から gra_focus クエリ パラメーターを解析して、引用されたクエリを識別し、会話内の function_call_output 項目と照合します。

引用文献は重複除去されます。 同じクエリが複数回引用された場合、すべての参照で同じインデックス番号と URL が使用されます。

データ モデル

このセクションでは、API が返すオブジェクトについて説明します。

応答

Response オブジェクトは、response.created、response.completed、および response.failed SSE イベントで返されます。

エラー情報

ErrorInfo オブジェクトは、エラーについて説明します。

出力項目

出力項目は、 type フィールドでポリモーフィックです。 次の種類を使用できます。

reasoning

エージェント モードが実行されるエージェントの内部推論。

function_call

ツール呼び出し。これは SQL クエリの実行です。

function_call_output

function_callを介してcall_idとペアになったツール呼び出しの結果。

項目が進行すると、 output フィールドが進化します。

message

テキスト メッセージ。 次の 3 つのロールのいずれかにメッセージが表示されます。

message オブジェクトには、次のフィールドが含まれています。

応答が失敗すると、構造化されたエラーは、システム Response項目ではなく、error オブジェクトの フィールド (response.failed を参照) とmessage イベントで配信されます。

コンテンツアイテム

API では、次のコンテンツ 項目の種類が使用されます。

ColumnInfo

ColumnInfo オブジェクトは列を記述します。

エラー処理

API は、ストリームが開始される前の HTTP エラーと、開いているストリームを終了するストリーミング エラーの 2 種類のエラーを返します。

HTTP エラー

HTTP エラーは、SSE ストリームが開始される前に標準の JSON 応答として返されます。

{ "error": { "type": "ERROR_CODE", "message": "Human-readable description" } }

次の HTTP エラーが発生する可能性があります。

ストリーミング エラー コード

ストリームの途中でエラーが発生すると、システム エラー メッセージ (role: "system"、 status: "failed") が response.output_item.addedとして出力され、その後に response.failed イベントが生成されます。 errorのResponse オブジェクトには、typeとcodeが含まれます。

type フィールドは、次のいずれかの仕様タイプです。

code フィールドには、次の詳細が表示されます。

よく寄せられる質問

次の質問では、エージェント モード API の一般的なトピックについて説明します。

応答にはどのくらいの時間がかかりますか?

応答時間は、質問の複雑さによって異なります。 単一クエリの質問は、1 分以内に完了できます。 マルチクエリの調査には数分かかる場合があります。 ストリームのサーバー側タイムアウトは 90 分です。

ストリーミングの代わりにポーリングできますか?

Yes. 応答を作成する要求を送信し、 response.created イベントの会話 ID を使用して会話アイテムを取得します。 アイテム エンドポイントは、進行中の応答を含む完全な会話履歴を返します。 statusまたはcompletedされるまで、items-list 応答の最上位のfailed フィールドをポーリングします。

複数ターンの会話のしくみ

次の要求で、前の応答からの会話 ID を渡します。 エージェントは、会話内のすべての以前のクエリと結果にアクセスでき、レポートでそれらを参照できます。

マークダウン出力形式は安定していますか?

レポート チャンク、推論テキスト、クエリ結果出力などのテキスト コンテンツは、マークダウンで返されます。 見出しレベルやテーブルの書式設定など、正確なマークダウン構造はモデルによって生成され、要求または API バージョン間で安定するとは限りません。 マークダウン出力をベスト エフォート形式のテキストとして扱い、列やプレビュー行などの構造化フィールドを、機械で読み取り可能な安定したデータ表現として使用します。

視覚エフェクトを取得できますか?

Yes. メッセージ添付ファイルのダウンロード視覚化エンドポイントを使用して視覚エフェクトを取得します。 REST API リファレンスの GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result/visualization を参照してください。

クエリ結果の有効期限は切れますか?

Yes. SQL クエリの結果は、 ステートメント実行 API と同じ有効期限ポリシーに従います。 結果の有効期限が切れると、ステートメント ID から返されなくなります。 応答メタデータのプレビュー行は、会話項目エンドポイントから引き続き使用できます。

エージェントがクエリを実行できるテーブルを知る方法

エージェントは、Genie エージェントに追加したテーブルにのみクエリを実行できます。 完全なカタログにアクセスできません。 最適な結果を得るには、列の説明、サンプル クエリ、結合手順を追加します。 効果的な Genie エージェントのキュレーションを参照してください。