Genie Agents のエージェントモード APIs

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

備考

ベータ版

Genie AgentsのAgentモードAPIsはベータ版です。

注記

Agent modeは以前、Research Agentとして知られていました。Genieエージェントは以前、Genieスペースとして知られていました。

エージェントモードのAPIsの仕組み

AgentモードのAPIsを使用して、自然言語の質問をGenie Agentに送信します。調査プランを作成して洗練させ、SQLクエリーを実行し、各結果に基づいて反復処理を行い、引用とサポートテーブルを含むレポートを返します。結果は、Server-Sent Events（SSE）としてクライアントにストリームされます。

APIs は、エージェントモードと直接通信するために必要な Endpoint、リクエストとレスポンスの形式、およびストリーミングイベントのタイプを網羅しています。概念の概要とUIエクスペリエンスについては、Genie Agentsのエージェントモードを参照してください。

要件

AgentモードAPIsを使用するには、ワークスペースが次の要件を満たす必要があります:

Unity Catalogが有効になっています。「Unity Catalog とは」を参照してください。
パートナー提供のAI機能が有効になっています。パートナー提供のAI機能をご覧ください。
明確な指示とテーブルメタデータを持つGenie Agentがあります。エージェントモードは、データを推論するためにこのコンテキストに依存します。効果的なGenie Agentをキュレーションするを参照してください。

ワークスペースでAPIsを有効にするには、機能を希望するワークスペースIDを添えてDatabricksアカウントチームに連絡してください。 リクエストが承認された後、ワークスペース管理者は**プレビュー**メニューから**Genie Agents Agent Mode API**を有効にします。

使い始める

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

Curl を使用して最初のプロンプトを送信します

次のリクエストは、自然言語の質問をGenie Agentに送信し、そのレスポンスをSSEとしてストリームします。

Bash
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）でストリームを読み取ります。

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

Bash
pip install databricks-openai

応答を作成し、到着した各イベントを処理します：

Python
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を渡します。

Python
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={&quot;conversation_id&quot;: conversation_id},
)

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

APIリファレンス

AgentモードAPIsは、利用可能なEndpoint、リクエストとレスポンスの形式、SSEイベントのライフサイクル、データモデル、およびエラーコードを扱っています。

ベースURL

すべてのEndpointは、以下のベースURLを基準としています：

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

注記

各パスのagent_idはGenie Agent IDであり、Genie Agent URLに表示される32文字の16進数識別子と同じです。

Endpoint

APIsは次のEndpointを提供します:

手法	パス	説明
`POST`	`/{agent_id}/responses`	SSE ストリームとして応答を作成します。
`GET`	`/{agent_id}/conversations/{conversation_id}/items`	会話内のすべてのアイテムをリストします。

手法	パス	説明
`POST`	`/{agent_id}/responses`	SSE ストリームとして応答を作成します。
`GET`	`/{agent_id}/conversations/{conversation_id}/items`	会話内のすべてのアイテムをリストします。

応答を作成

新しいAgentモードレスポンスを作成します。Agentモードのラン中にリアルタイムで出力項目を配信するSSEストリームを返します。

POST /{agent_id}/responses

パスパラメーター

Endpointは次のパスパラメーターを受け入れます。

パラメーター	Type	必須	説明
`agent_id`	`string`	はい	Genie AgentのIDです。32文字の小文字の16進数文字列です。

リクエスト本文

リクエスト本文は次のフィールドを受け入れます。

フィールド	Type	必須	デフォルト	説明
`input`	`array<InputItem>`	はい	なし	入力項目です。配列には、質問を含む`role: "user"`を持つ`message`項目が1つだけ含まれている必要があります。マルチターンコンテキストはサーバー側で管理されるため、`input`で以前のメッセージを渡す代わりに、`conversation_id`をフォローアップに使用してください。
`conversation_id`	`string`	No	`null`	既存の会話を続けるためのID。省略した場合、新しい会話が作成されます。

フィールド	Type	必須	デフォルト	説明
`input`	`array<InputItem>`	はい	なし	入力項目です。配列には、質問を含む`role: "user"`を持つ`message`項目が1つだけ含まれている必要があります。マルチターンコンテキストはサーバー側で管理されるため、`input`で以前のメッセージを渡す代わりに、`conversation_id`をフォローアップに使用してください。
`conversation_id`	`string`	No	`null`	既存の会話を続けるためのID。省略した場合、新しい会話が作成されます。

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

起動時に一度発行されます。status: "in_progress" および空の output 配列を持つ Response オブジェクトが含まれています。

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

同時実行

会話ごとに一度に生成できるレスポンスは1つのみです。すでに処理中のレスポンスがある会話への2回目のリクエストは、HTTP 409を返します:

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

タイムアウト

SSEストリームには90分のサーバーサイドタイムアウトがあります。エージェントモードでは多段階推論とSQL実行が行われるため、HTTP接続は全期間にわたって開いたままにしてください。

会話項目を一覧表示

会話内の出力項目をフラットリストとして取得します。すべてのターンからの項目は、ユーザーメッセージ、推論、クエリー、結果、レポートを含め、時系列順で結合されます。このEndpointは、afterとlimitクエリーパラメーターを通じて、カーソルベースのページネーションをサポートしています。

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

このEndpointを使用して：

アプリケーションで会話履歴全体を表示します。
SSEストリームが切断された後に結果を回復します。応答が完了したら、このEndpointを呼び出してください。
すべての項目を一度にロードする代わりに、大規模な会話を段階的にフェッチします。

パスパラメーター

Endpointは次のパスパラメーターを受け入れます：

パラメーター	Type	必須	説明
`agent_id`	`string`	はい	Genie AgentのIDです。32文字の小文字の16進数文字列です。
`conversation_id`	`string`	はい	会話のID。

クエリーパラメーター

Endpointは以下のクエリーパラメーターを受け入れます：

パラメーター	Type	必須	デフォルト	説明
`limit`	`integer`	No	100	返されるアイテムの最大数。範囲：1～100。
`after`	`string`	No	なし	ページネーションカーソルです。次のページを取得するために、前の応答から`last_id`を渡します。
`order`	`string`	No	`asc`	ソート順。時系列順（最も古い順）には`asc`を使用し、逆時系列順（最も新しい順）には`desc`を使用します。

パラメーター	Type	必須	デフォルト	説明
`limit`	`integer`	No	100	返されるアイテムの最大数。範囲：1～100。
`after`	`string`	No	なし	ページネーションカーソルです。次のページを取得するために、前の応答から`last_id`を渡します。
`order`	`string`	No	`asc`	ソート順。時系列順（最も古い順）には`asc`を使用し、逆時系列順（最も新しい順）には`desc`を使用します。

要求の例

会話内のすべての項目を取得：

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"を含むページ分割されたリストエンベロープです：

JSON
{
  "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つのページ分割フィールドが含まれます。

フィールド	Type	説明
`first_id`	`string`	現在のページで最初のアイテムのID。`data` が空の場合に存在しません。
`last_id`	`string`	現在のページの最後のアイテムのID。次のページを取得するために、`after`として渡してください。`data`が空の場合に存在しません。
`has_more`	`boolean`	`true` このページにさらに項目が続く場合。

フィールド	Type	説明
`first_id`	`string`	現在のページで最初のアイテムのID。`data` が空の場合に存在しません。
`last_id`	`string`	現在のページの最後のアイテムのID。次のページを取得するために、`after`として渡してください。`data`が空の場合に存在しません。
`has_more`	`boolean`	`true` このページにさらに項目が続く場合。

すべての項目をページ分割して表示するには、has_moreがfalseになるまでページを要求します。

Python
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配列には、出力項目が時系列順に含まれています。ユーザー入力メッセージはmessage項目として表示され、IDには_inputサフィックスが付きます。

応答を理解する

このセクションでは、出力項目がどのように組み合わさって完全なAgentモード応答を形成するかを説明します。

出力アイテムフロー

通常のAgentモードの応答では、出力項目を以下の順序で生成します：

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

エージェントは複数のクエリーを連続して実行し、それぞれの結果に基づいて分析を洗練させることができます。単一の応答には、最終レポートの前に多くの推論、クエリー、および結果サイクルを含めることができます。

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です。

レポートを解析

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

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

以下のテーブルチャンクには、レンダリングされたマークダウンと構造化されたmetadataが含まれます。

JSON
{
  "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オブジェクトは以下のフィールドを含みます：

フィールド	Type	説明
`columns`	`array<ColumnInfo>`	列の定義。
`preview_rows`	`array<array<string>>`	切り捨てられた結果行。
`total_row_count`	`integer`	判明している場合の合計行数。
`status`	`string`	`"available"`または`"fetch_failed"`のいずれか。
`sql`	`string`	結果を生成したSQLクエリー。

フィールド	Type	説明
`columns`	`array<ColumnInfo>`	列の定義。
`preview_rows`	`array<array<string>>`	切り捨てられた結果行。
`total_row_count`	`integer`	判明している場合の合計行数。
`status`	`string`	`"available"`または`"fetch_failed"`のいずれか。
`sql`	`string`	結果を生成したSQLクエリー。

引用

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

引用URLは次の形式です。

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

URLには以下のコンポーネントが含まれています：

コンポーネント	説明
`space_id`	Genie Agent ID。`agent_id`と同じ値です。
`conversation_id`	引用されたクエリーを含む会話。
`workspace_id`	数値のワークスペースID。
`attachment_id`	クエリーのアタッチメントID。これは特定のSQLクエリー結果を識別します。

コンポーネント	説明
`space_id`	Genie Agent ID。`agent_id`と同じ値です。
`conversation_id`	引用されたクエリーを含む会話。
`workspace_id`	数値のワークスペースID。
`attachment_id`	クエリーのアタッチメントID。これは特定のSQLクエリー結果を識別します。

引用を表示するには、クライアントに基づいて以下のガイダンスに従ってください：

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

引用は重複排除されます。同じクエリーが複数回引用されている場合、すべての参照は同じインデックス番号とURLを使用します。

データモデル

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

レスポンス

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

フィールド	Type	説明
`object`	`string`	常に `"response"` です。
`id`	`string`	一意のレスポンスIDです。
`model`	`string`	常に `"genie-agent"` です。
`status`	`string`	`"in_progress"`、`"completed"`、または`"failed"`のいずれか。
`output`	`array<OutputItem>`	レスポンスによって生成された出力項目です。
`conversation_id`	`string`	応答が属する会話。
`created_at`	`integer`	応答が作成されたときのUnixエポック時間（秒単位）。
`error`	`ErrorInfo`	`status`が`"failed"`のときに存在します。

フィールド	Type	説明
`object`	`string`	常に `"response"` です。
`id`	`string`	一意のレスポンスIDです。
`model`	`string`	常に `"genie-agent"` です。
`status`	`string`	`"in_progress"`、`"completed"`、または`"failed"`のいずれか。
`output`	`array<OutputItem>`	レスポンスによって生成された出力項目です。
`conversation_id`	`string`	応答が属する会話。
`created_at`	`integer`	応答が作成されたときのUnixエポック時間（秒単位）。
`error`	`ErrorInfo`	`status`が`"failed"`のときに存在します。

ErrorInfo

ErrorInfoオブジェクトは失敗について説明します:

フィールド	Type	説明
`type`	`string`	次のいずれか：`server_error`、`invalid_request`、`not_found`、`model_error`、または`too_many_requests`。
`message`	`string`	人間が判読できる説明。内部エラーの場合、これは常に`"An internal error occurred"`です。
`code`	`string`	詳細情報を含むオプションのエラーコード（`"sql_execution_error"`や`"warehouse_access_denied"`など）。ストリーミングエラーコードを参照してください。

フィールド	Type	説明
`type`	`string`	次のいずれか：`server_error`、`invalid_request`、`not_found`、`model_error`、または`too_many_requests`。
`message`	`string`	人間が判読できる説明。内部エラーの場合、これは常に`"An internal error occurred"`です。
`code`	`string`	詳細情報を含むオプションのエラーコード（`"sql_execution_error"`や`"warehouse_access_denied"`など）。ストリーミングエラーコードを参照してください。

出力項目

出力項目は、typeフィールド上でポリモーフィックです。以下の種類が利用可能です。

reasoning

エージェントモード実行中のエージェントの内部推論。

フィールド	Type	説明
`type`	`string`	`"reasoning"`.
`id`	`string`	アイテムの一意の ID。
`status`	`string`	`"in_progress"`または`"completed"`のいずれか。
`content`	`array<ContentItem>`	`reasoning_text`個のアイテムが含まれています。
`summary`	`array<string>`	常に `[]` です。将来の使用のために予約されています。

フィールド	Type	説明
`type`	`string`	`"reasoning"`.
`id`	`string`	アイテムの一意の ID。
`status`	`string`	`"in_progress"`または`"completed"`のいずれか。
`content`	`array<ContentItem>`	`reasoning_text`個のアイテムが含まれています。
`summary`	`array<string>`	常に `[]` です。将来の使用のために予約されています。

function_call

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

フィールド	Type	説明
`type`	`string`	`"function_call"`.
`id`	`string`	アイテムの一意の ID。
`call_id`	`string`	ペアになっている`function_call_output`にLinkする相関ID。
`status`	`string`	`"completed"`.
`name`	`string`	`"execute_sql"`.
`arguments`	`string`	JSON文字列、たとえば`{"title": "Human-readable query title", "sql": "SELECT ..."}`。キーのセットは変更される可能性があるため、クライアントは固定スキーマに依存すべきではありません。

フィールド	Type	説明
`type`	`string`	`"function_call"`.
`id`	`string`	アイテムの一意の ID。
`call_id`	`string`	ペアになっている`function_call_output`にLinkする相関ID。
`status`	`string`	`"completed"`.
`name`	`string`	`"execute_sql"`.
`arguments`	`string`	JSON文字列、たとえば`{"title": "Human-readable query title", "sql": "SELECT ..."}`。キーのセットは変更される可能性があるため、クライアントは固定スキーマに依存すべきではありません。

function_call_output

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

フィールド	Type	説明
`type`	`string`	`"function_call_output"`.
`id`	`string`	常に `{call_id}_output` です。
`call_id`	`string`	対応する`function_call`と一致します。
`status`	`string`	`"in_progress"`または`"completed"`のいずれか。
`output`	`string`	クエリー結果。以下のライフサイクルテーブルを参照してください。

フィールド	Type	説明
`type`	`string`	`"function_call_output"`.
`id`	`string`	常に `{call_id}_output` です。
`call_id`	`string`	対応する`function_call`と一致します。
`status`	`string`	`"in_progress"`または`"completed"`のいずれか。
`output`	`string`	クエリー結果。以下のライフサイクルテーブルを参照してください。

outputフィールドは、アイテムの進行に合わせて進化します。

ステータス	`output` コンテンツ
`in_progress`	クエリータイトルのみです。
`completed`	クエリーのタイトル、空白行、その後マークダウン結果テーブル。

注記

列、行、SQLなどの構造化されたクエリー結果データは、レポートのテーブルチャンクで利用可能であり、function_call_output項目では利用できません。レポートを解析するを参照してください。

message

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

ロール	場合	説明
`"user"`	入力	ユーザーからの質問です。`GET`応答に表示され、IDには`_input`サフィックスが付きます。
`"assistant"`	レポート	テキストとインラインテーブルチャンクを含む最終的な構造化レポート。
`"system"`	エラー／キャンセル	応答が失敗した、またはキャンセルされた場合に発生します。

ロール	場合	説明
`"user"`	入力	ユーザーからの質問です。`GET`応答に表示され、IDには`_input`サフィックスが付きます。
`"assistant"`	レポート	テキストとインラインテーブルチャンクを含む最終的な構造化レポート。
`"system"`	エラー／キャンセル	応答が失敗した、またはキャンセルされた場合に発生します。

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

フィールド	Type	説明
`type`	`string`	`"message"`.
`role`	`string`	`"user"`、`"assistant"`、または`"system"`のいずれか。
`content`	`array<ContentItem>`	メッセージ内容です。アシスタントメッセージについては、レポートを解析するを参照してください。
`id`	`string`	一意のアイテムID。システムメッセージでは `{responseId}_error` または `{responseId}_cancelled` を使用します。
`status`	`string`	`"completed"`、`"failed"`、または`"cancelled"`のいずれか。

フィールド	Type	説明
`type`	`string`	`"message"`.
`role`	`string`	`"user"`、`"assistant"`、または`"system"`のいずれか。
`content`	`array<ContentItem>`	メッセージ内容です。アシスタントメッセージについては、レポートを解析するを参照してください。
`id`	`string`	一意のアイテムID。システムメッセージでは `{responseId}_error` または `{responseId}_cancelled` を使用します。
`status`	`string`	`"completed"`、`"failed"`、または`"cancelled"`のいずれか。

応答が失敗した場合、構造化されたエラーは、Response オブジェクトの error フィールド（ErrorInfo を参照）と response.failed イベントで配信され、システム message アイテムでは配信されません。

コンテンツ項目

APIsは次のコンテンツアイテムタイプを使用します：

Type	フィールド	使用済み
`input_text`	`text`	ユーザーメッセージ（入力）。
`output_text`	`text`, `metadata`	アシスタントメッセージ（チャンクを報告）。テキストチャンクには`[N](url)`個の引用Linkが含まれています。テーブルチャンクには、構造化クエリー結果データを含む`metadata`が含まれています。
`reasoning_text`	`text`	推論項目。

Type	フィールド	使用済み
`input_text`	`text`	ユーザーメッセージ（入力）。
`output_text`	`text`, `metadata`	アシスタントメッセージ（チャンクを報告）。テキストチャンクには`[N](url)`個の引用Linkが含まれています。テーブルチャンクには、構造化クエリー結果データを含む`metadata`が含まれています。
`reasoning_text`	`text`	推論項目。

ColumnInfo

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

フィールド	Type	説明
`name`	`string`	列名。
`type`	`string`	列のデータ型 (例: `"STRING"`、`"DOUBLE"`、`"BIGINT"`)。

エラー処理

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

HTTP エラー

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

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

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

HTTPステータス	エラーコード	条件
`400`	`INVALID_PARAMETER_VALUE`	パスパラメーターが見つからないか、入力項目が見つからないか無効であるか、または最後の入力がユーザーメッセージではありません。
`404`	`FEATURE_DISABLED`	ワークスペースがプレビューに登録されていないか、ワークスペース管理者がプレビューをオンにしていません。
`403`	`PERMISSION_DENIED`	呼び出し元は、Genie Agentに対するCAN VIEW権限がありません。
`404`	`NOT_FOUND`	Genie Agent または会話は存在しません。
`409`	`RESOURCE_CONFLICT`	この会話の応答はすでに生成されています。
`500`	`INTERNAL_ERROR`	予期しないサーバーエラーが発生しました。

HTTPステータス	エラーコード	条件
`400`	`INVALID_PARAMETER_VALUE`	パスパラメーターが見つからないか、入力項目が見つからないか無効であるか、または最後の入力がユーザーメッセージではありません。
`404`	`FEATURE_DISABLED`	ワークスペースがプレビューに登録されていないか、ワークスペース管理者がプレビューをオンにしていません。
`403`	`PERMISSION_DENIED`	呼び出し元は、Genie Agentに対するCAN VIEW権限がありません。
`404`	`NOT_FOUND`	Genie Agent または会話は存在しません。
`409`	`RESOURCE_CONFLICT`	この会話の応答はすでに生成されています。
`500`	`INTERNAL_ERROR`	予期しないサーバーエラーが発生しました。

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

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

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

`type`	説明
`server_error`	クライアントが原因ではない内部サーバー障害です。
`invalid_request`	不正な、または意味的に無効なリクエスト、またはユーザーが対処できる権限の問題です。
`not_found`	参照されたリソースは存在しません。
`model_error`	モデルは、それ自体は有効なリクエストの処理に失敗しました。
`too_many_requests`	リクエストはレート制限されました。

`type`	説明
`server_error`	クライアントが原因ではない内部サーバー障害です。
`invalid_request`	不正な、または意味的に無効なリクエスト、またはユーザーが対処できる権限の問題です。
`not_found`	参照されたリソースは存在しません。
`model_error`	モデルは、それ自体は有効なリクエストの処理に失敗しました。
`too_many_requests`	リクエストはレート制限されました。

codeフィールドには、さらに詳細情報が記載されています。

`code`	`type`	説明
`internal_error`	`server_error`	予期しないサーバーエラーが発生しました。メッセージは常に`"An internal error occurred"`です。
`sql_execution_error`	`server_error`	SQLクエリーの実行に失敗しました。
`upstream_unavailable`	`server_error`	上位の依存関係が一時的に利用できません。
`timeout`	`server_error`	リクエストまたはアップストリームコールがタイムアウトしました。
`model_unavailable`	`model_error`	モデルは一時的に利用できません。
`context_length_exceeded`	`model_error`	会話履歴がモデルのコンテキストウィンドウを超過しました。
`content_filtered`	`model_error`	コンテンツフィルターが応答をブロックしました。
`rate_limit_exceeded`	`too_many_requests`	並列リクエストが多すぎるか、アップストリームのレート制限に達しました。
`budget_exceeded`	`too_many_requests`	ワークスペースがAgent Modeの使用予算を超えました。
`warehouse_access_denied`	`invalid_request`	呼び出し元は、構成されたSQLウェアハウスを使用する権限がありません。
`no_tables_available`	`invalid_request`	Genie Agentでクエリー可能なテーブルはありません。
`invalid_request`	`invalid_request`	リクエストの形式が正しくないか、必須フィールドが入力されていません。
`permission_denied`	`invalid_request`	呼び出し元は権限を失ったか、実行中に委任が失敗しました。
`conflict`	`invalid_request`	並列操作がリクエストと競合しました。
`warehouse_not_found`	`not_found`	構成済みのSQLウェアハウスが存在しないか、削除されています。
`not_found`	`not_found`	実行中に参照されたリソースが見つかりませんでした。

`code`	`type`	説明
`internal_error`	`server_error`	予期しないサーバーエラーが発生しました。メッセージは常に`"An internal error occurred"`です。
`sql_execution_error`	`server_error`	SQLクエリーの実行に失敗しました。
`upstream_unavailable`	`server_error`	上位の依存関係が一時的に利用できません。
`timeout`	`server_error`	リクエストまたはアップストリームコールがタイムアウトしました。
`model_unavailable`	`model_error`	モデルは一時的に利用できません。
`context_length_exceeded`	`model_error`	会話履歴がモデルのコンテキストウィンドウを超過しました。
`content_filtered`	`model_error`	コンテンツフィルターが応答をブロックしました。
`rate_limit_exceeded`	`too_many_requests`	並列リクエストが多すぎるか、アップストリームのレート制限に達しました。
`budget_exceeded`	`too_many_requests`	ワークスペースがAgent Modeの使用予算を超えました。
`warehouse_access_denied`	`invalid_request`	呼び出し元は、構成されたSQLウェアハウスを使用する権限がありません。
`no_tables_available`	`invalid_request`	Genie Agentでクエリー可能なテーブルはありません。
`invalid_request`	`invalid_request`	リクエストの形式が正しくないか、必須フィールドが入力されていません。
`permission_denied`	`invalid_request`	呼び出し元は権限を失ったか、実行中に委任が失敗しました。
`conflict`	`invalid_request`	並列操作がリクエストと競合しました。
`warehouse_not_found`	`not_found`	構成済みのSQLウェアハウスが存在しないか、削除されています。
`not_found`	`not_found`	実行中に参照されたリソースが見つかりませんでした。

よくある質問

以下の質問では、AgentモードAPIsに関する一般的なトピックを網羅しています。

応答にはどのくらいかかりますか？

応答時間は質問の複雑さによって異なります。単一クエリーの質問は1分未満で完了します。複数クエリーの調査には数分かかることがあります。ストリームには90分のサーバー側タイムアウトがあります。

ストリーミングではなくポーリングできますか？

はい。応答を作成するためのリクエストを送信し、その後response.createdイベントから会話IDを使用して会話アイテムを取得します。アイテムEndpointは、進行中の応答を含め、完全な会話履歴を返します。アイテムリスト応答のトップレベルのstatusフィールドを、completedまたはfailedになるまでポーリングします。

複数ターンの会話の仕組みは？

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

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

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

可視化を取得できますか？

はい。downloadメッセージ添付ビジュアライゼーションEndpointを使用してビジュアライゼーションを取得します。REST APIリファレンスの GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result/visualization を参照してください。

クエリー結果は有効期限切れになりますか？

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

エージェントがどのテーブルをクエリーできるかは、どのようにすれば分かりますか？

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

エージェントモードのAPIsの仕組み​

要件​

使い始める​

Curl を使用して最初のプロンプトを送信します​

Databricks OpenAI クライアント（Python）でストリームを読み取ります。​

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

APIリファレンス​

ベースURL​

Endpoint​

応答を作成​

パスパラメーター​

リクエスト本文​

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

SSEイベントの種類​

同時実行​

タイムアウト​

会話項目を一覧表示​

パスパラメーター​

クエリーパラメーター​

要求の例​

レスポンス​

ページネーション​

応答を理解する​

出力アイテムフロー​

function_call と function_call_output のペア​

レポートを解析​

引用​

データモデル​

レスポンス​

ErrorInfo​

出力項目​

コンテンツ項目​

ColumnInfo​

エラー処理​

HTTP エラー​

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

よくある質問​

応答にはどのくらいかかりますか？​

ストリーミングではなくポーリングできますか？​

複数ターンの会話の仕組みは？​

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

可視化を取得できますか？​

クエリー結果は有効期限切れになりますか？​

エージェントがどのテーブルをクエリーできるかは、どのようにすれば分かりますか？​

エージェントモードのAPIsの仕組み

要件

使い始める

Curl を使用して最初のプロンプトを送信します

Databricks OpenAI クライアント（Python）でストリームを読み取ります。

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

APIリファレンス

ベースURL

Endpoint

応答を作成

パスパラメーター

リクエスト本文

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

SSEイベントの種類

同時実行

タイムアウト

会話項目を一覧表示

パスパラメーター

クエリーパラメーター

要求の例

レスポンス

ページネーション

応答を理解する

出力アイテムフロー

function_call と function_call_output のペア

レポートを解析

引用

データモデル

レスポンス

ErrorInfo

出力項目

コンテンツ項目

ColumnInfo

エラー処理

HTTP エラー

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

よくある質問

応答にはどのくらいかかりますか？

ストリーミングではなくポーリングできますか？

複数ターンの会話の仕組みは？

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

可視化を取得できますか？

クエリー結果は有効期限切れになりますか？

エージェントがどのテーブルをクエリーできるかは、どのようにすれば分かりますか？