Databricksにデプロイされたエージェントにクエリーを実行する
エージェントに対してどのようにクエリーを実行するかは、それをサービングするエージェントサーバーによって異なります。以下の表からエージェントを見つけ、対応するセクションを参照してください。エージェントサーバーの詳細については、エージェント サーバーを参照してください。
エージェント | ホスト元: | クエリーの方法 |
|---|---|---|
Databricks Apps上のエージェントランタイム | 呼び出しAPIのエンドポイント: | |
Databricks Apps | Databricks OpenAI クライアントまたは次の場所にある OpenAI Responses API | |
Model Serving にデプロイ済み (レガシー) | モデルサービングエンドポイント | Databricks OpenAIクライアント、REST API、 |
Databricks Apps でホストされるエージェントには、Databricks OAuth トークンが必要です。パーソナル アクセストークンは Databricks Apps では機能しません。スクリプト、Service Principal、別のアプリ、またはノートブックから OAuth トークンを生成する方法については、トークン認証を使用して API Databricks アプリに接続するを参照してください。
次を使用するエージェントをクエリーする DurableAgentServer
DurableAgentServer を使用するエージェントが呼び出し API を提供します。Agent Bricks CLI で作成したエージェントは DurableAgentServer を使用し、agentbricks deploy はそれらを agent-bricks-<name> という名前のアプリとして Agent ランタイム にデプロイします。API への各リクエストによって、エージェントの 1 つのランが起動されます。これは呼び出しと呼ばれます。
エンドポイント | 説明 |
|---|---|
| 呼び出しを起動します。By default では、リクエストは待機して結果を返します。イベントが発生したときに受け取るには |
| 呼び出しのステータスを返し、完了後に出力を返します。 |
|
|
リクエスト本文
POST /api/invocations のリクエスト本文では、以下のフィールドを指定できます。サーバーは、他のフィールドが含まれているリクエストを拒否します。
フィールド | 説明 |
|---|---|
| 必須。各呼び出しに対して生成するUUID。サーバーはIDをべき等性キーとして扱います。同じIDで同じリクエストを再送信すると、エージェントを再実行する代わりに既存の呼び出しが返されます。異なるリクエストでIDを再利用すると、 |
| 呼び出しが属する会話。セッション ID を共有する呼び出しは、順番に 1 つずつ実行されます。CLI Templateから生成されたエージェントでは、このフィールドが必要です。 |
| エージェントへの入力です。CLI Templateから生成されたエージェントは、メッセージのリスト、または |
| Server-Sent Events(SSE)としてイベントを受信するには、 |
|
|
エージェントのハンドラーは input の構造を定義します。CLI Templateから生成されたエージェントは、input がオブジェクトである場合に次のフィールドを読み取ります:
フィールド | 説明 |
|---|---|
| エージェントに送信する会話のターン。 |
| エージェントが読み書きする長期記憶の識別情報。 |
| エージェントコードで設定されたモデルの代わりに、この呼び出しで使用するモデル。 |
| ツール呼び出しの承認など、人間の入力を待つために停止するエージェントへの応答。エージェントが一時停止すると、呼び出しの |
エージェントがセッション間でユーザーについて学習した内容を記憶できるようにするには、ユーザーの ID を actor として渡します。
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "support-case-123",
"input": {
"messages": [{ "role": "user", "content": "What does Databricks do?" }],
"actor": "user-42"
}
}
- Agent Bricks CLI
- REST API
- Python
ターミナルからデプロイされたエージェントをテストするには、agentbricks endpoint invoke を使用します。このコマンドはアプリを検索し、CLIプロファイルで認証を行います。
agentbricks --profile <profile> endpoint invoke agent-bricks-<name> \
--path /api/invocations \
--json "{\"id\":\"$(uuidgen)\",\"session_id\":\"$(uuidgen)\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"
応答をストリームするには、JSON本文に"stream":trueを追加し、--sseを渡します。agentbricks devを使用してローカルで実行中にエージェントをテストするには、アプリ名を--url http://localhost:8000に置き換えます。
-
アプリのURLを取得します。出力内の URL フィールドは、呼び出しAPIのベースURLです。
Bashagentbricks --profile <profile> deployments get agent-bricks-<name> -
プロファイルのOAuthトークンを取得します。出力には、
access_tokenフィールドにトークンが含まれています。次のコマンドは、それをTOKENシェル変数に保存します。BashTOKEN=$(databricks auth token --profile <profile> | jq -r .access_token)このコマンドには、
databricks auth loginで作成したプロファイルが必要です。Service Principalまたはスクリプトについては、トークン認証を使用してAPI Databricksアプリに接続するを参照するか、SDKのw.config.authenticate()を使用してください。 -
リクエストを送信します。次のコマンドは二重引用符を使用しているため、シェルは
$TOKENを展開し、uuidgenを含む新しい呼び出しidを生成します。Bashcurl --request POST \--url <app-url>/api/invocations \--header "Authorization: Bearer $TOKEN" \--header 'content-type: application/json' \--data "{\"id\": \"$(uuidgen)\",\"session_id\": \"support-case-123\",\"input\": [{ \"role\": \"user\", \"content\": \"What does Databricks do?\" }]}"リクエストごとに新しい
idを使用してください。idを再送信した場合、サーバーはその呼び出しの格納済みの結果を返します。呼び出しが失敗した場合、サーバーは500エラーを返します。
応答には、呼び出し id、その status、およびエージェントが返す値を持つ output フィールドが含まれます。サーバーは出力スキーマを必要としません。ハンドラーは JSON シリアル化可能な値を返すことができます。
CLI Templateから生成されたエージェントの場合、最上位の output 自体がオブジェクトです。それ自体の output リストには、この呼び出しでエージェントが生成したメッセージが保持されており、独自の status が含まれる可能性があります。 completed 、またはエージェントが人間による入力を待機している場合は interrupted です。たとえば:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"output": {
"output": [{ "role": "assistant", "content": "Databricks is ..." }],
"session_id": "support-case-123",
"status": "completed"
}
}
次の例では、Databricks SDKを使用してアプリのURLを検索し、OAuthトークンを生成してから、invocations APIを呼び出します。WorkspaceClientでは、OAuth認証を使用する必要があります。
import uuid
import requests
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
app_url = w.apps.get("agent-bricks-<name>").url
session_id = str(uuid.uuid4())
response = requests.post(
f"{app_url}/api/invocations",
headers=w.config.authenticate(),
json={
"id": str(uuid.uuid4()),
"session_id": session_id,
"input": [{"role": "user", "content": "What does Databricks do?"}],
},
)
response.raise_for_status()
print(response.json()["output"]["output"])
CLI Templateから生成されたエージェントの場合、メッセージは output.output にあります。エージェントが返す値を表示するには、response.json()["output"] を使用します。
会話を続けるには、同じ session_id と新しい id を指定して次のメッセージを送信します。
ストリーム、バックグラウンドでのラン、および再接続
- ストリーム :
"stream": trueを設定します。レスポンスは、run.startedおよびrun.completed(またはrun.failed)イベントに加えて、エージェントが生成するイベント(ストリームテキストを含むdeltaイベントなど)を含む SSE ストリームです。各イベントには、再接続に使用するシーケンス番号を持つ SSEid:行があります。data:ペイロードには、イベントIDではないフレームワークランIDのような独自のidフィールドを含めることができます。 - バックグラウンドでラン :
"background": trueを設定します。サーバーは{"id": "...", "status": "queued", "status_url": "/api/invocations/<id>"}などの202レスポンスを返します。"stream": trueも設定した場合、レスポンスにはイベントの読み取り元となるevents_urlが含まれます。status_urlフィールドとevents_urlフィールドは、アプリ URL からの相対パスです。ステータスがcompletedまたはfailedになるまでGET /api/invocations/<id>をポーリングします。 - 再接続 :ストリームが切断された場合は、以下の例の
last_event_idのように、受信した最後のイベントの ID を指定してGET /api/invocations/<id>/events?after=<event-id>を呼び出します。
CLI Templateから生成されたエージェントにおいて、各 delta イベントには content のテキストのチャンクが含まれ、各 message イベントには最終的なアシスタントメッセージを含む message の完全なメッセージが含まれます。message イベントは、その前の delta イベントのテキストを繰り返すため、両方ではなくどちらか一方を印刷してください。
次の Python の例では、応答をストリームし、 delta イベントからテキストを出力し、最後のイベントの ID を追跡します。
import json
invocation_id = str(uuid.uuid4())
last_event_id = None
with requests.post(
f"{app_url}/api/invocations",
headers=w.config.authenticate(),
json={
"id": invocation_id,
"session_id": session_id,
"input": [{"role": "user", "content": "Summarize our last conversation."}],
"stream": True,
},
stream=True,
) as response:
response.raise_for_status()
for line in response.iter_lines(decode_unicode=True):
if line.startswith("id: "):
event_id = line[len("id: "):]
elif line.startswith("data: "):
event = json.loads(line[len("data: "):])
if event.get("type") == "delta":
print(event["content"], end="", flush=True)
# Advance the cursor only after the event is processed.
last_event_id = event_id
ストリームが切断された場合は、最後のイベント ID から残りのイベントを読み取ります:
with requests.get(
f"{app_url}/api/invocations/{invocation_id}/events",
headers=w.config.authenticate(),
params={"after": last_event_id},
stream=True,
) as response:
response.raise_for_status()
for line in response.iter_lines(decode_unicode=True):
if line.startswith("id: "):
event_id = line[len("id: "):]
elif line.startswith("data: "):
event = json.loads(line[len("data: "):])
if event.get("type") == "delta":
print(event["content"], end="", flush=True)
last_event_id = event_id
次のPythonの例では、バックグラウンドで呼び出しを実行し、完了するまでそのステータスURLをポーリングします。ステータスがfailedの場合、レスポンスにはoutputの代わりにerrorフィールドが含まれます。
import time
response = requests.post(
f"{app_url}/api/invocations",
headers=w.config.authenticate(),
json={
"id": str(uuid.uuid4()),
"session_id": session_id,
"input": [{"role": "user", "content": "What does Databricks do?"}],
"background": True,
},
)
response.raise_for_status()
status_url = response.json()["status_url"]
while True:
state = requests.get(f"{app_url}{status_url}", headers=w.config.authenticate()).json()
if state["status"] in ("completed", "failed"):
break
time.sleep(2)
print(state.get("output", state.get("error")))
複数のインスタンスを使用してエージェントをデプロイする場合は、セッション内のすべてのリクエストを同じインスタンスにルーティングするために、X-Routing-KeyヘッダーでセッションIDを送信します。
レガシー MLflow を使用するエージェントにクエリーする AgentServer
レガシーエージェントサーバーを使用して Databricks Apps にデプロイするエージェントの場合は、このセクションを使用します。MLflowAgentServer LongRunningAgentServerの または をResponsesAgent インターフェイスとともに使用します。これらのエージェントは、/responses で OpenAI Responses API を提供します。
LongRunningAgentServer 同じ API を提供するため、次の例も適用されます。また、バックグラウンドランもサポートされます。リクエストで background を true に設定し、そのシーケンス番号以降のイベントをストリームする GET /responses/<response-id>?stream=true&starting_after=<sequence-number> でレスポンスを取得します。
- Databricks OpenAI client
- REST API
Databricksでは、これらのエージェントに対してDatabricks OpenAI clientをお勧めしています。モデル名に apps/ プレフィックスを含めます。
from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI
input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
app_name = "<agent-app-name>"
# The WorkspaceClient must use OAuth authentication.
w = WorkspaceClient()
client = DatabricksOpenAI(workspace_client=w)
# Non-streaming request
response = client.responses.create(model=f"apps/{app_name}", input=input_msgs)
print(response)
# Streaming request
streaming_response = client.responses.create(
model=f"apps/{app_name}", input=input_msgs, stream=True
)
for chunk in streaming_response:
print(chunk)
custom_inputs を渡すには、extra_body パラメーターを使用します。
response = client.responses.create(
model=f"apps/{app_name}",
input=input_msgs,
extra_body={"custom_inputs": {"id": 5}},
)
リクエストのトレースIDを取得するには、x-mlflow-return-trace-idヘッダーを含めます。次に、MLflow の get_trace を使用して、完全なトレースを取得します。
response = client.responses.create(
model=f"apps/{app_name}",
input=input_msgs,
extra_headers={"x-mlflow-return-trace-id": "true"},
)
trace_id = response.metadata["trace_id"]
trace = client.get_trace(trace_id)
アプリURLの/responsesパスにリクエストを送信します。リクエスト本文はOpenAI Responses APIに準拠しているため、それをサポートする任意のHTTPクライアントまたはツールを使用できます。
curl --request POST \
--url <app-url>/responses \
--header 'Authorization: Bearer <OAuth token>' \
--header 'content-type: application/json' \
--data '{
"input": [{ "role": "user", "content": "hi" }],
"stream": true
}'
custom_inputsを渡すには、リクエスト本文に追加します:
curl --request POST \
--url <app-url>/responses \
--header 'Authorization: Bearer <OAuth token>' \
--header 'content-type: application/json' \
--data '{
"input": [{ "role": "user", "content": "hi" }],
"custom_inputs": { "id": 5 }
}'
トレースIDを取得するには、x-mlflow-return-trace-id: trueヘッダーを含めます。応答本文には、metadata.trace_idフィールドにトレースIDが含まれています。ストリーミングリクエストの場合、トレースIDはストリームの終わりの方で別のSSEイベント(data: {"trace_id": "tr-..."})として届きます。
Model Serving でレガシーエージェントをクエリーする
Model Servingエンドポイントにデプロイされたレガシーエージェントについては、このセクションを使用してください。Databricks OAuthトークンまたは個人アクセストークンを使用して認証できます。これらのエージェントをDatabricks Appsに移行するには、Model ServingからDatabricks Appsへのエージェントの移行を参照してください。
- Databricks OpenAI client
- REST API
- AI Playground
- SQL with
ResponsesAgent インターフェイスを使用するエージェントの場合は、エンドポイント名をモデルとして指定して responses.create を呼び出します。
from databricks_openai import DatabricksOpenAI
input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>"
client = DatabricksOpenAI()
# Non-streaming request. Calls predict.
response = client.responses.create(model=endpoint, input=input_msgs)
print(response)
# Streaming request. Calls predict_stream.
streaming_response = client.responses.create(model=endpoint, input=input_msgs, stream=True)
for chunk in streaming_response:
print(chunk)
レガシーの ChatAgent または ChatModel インターフェイスを使用するエージェントの場合は、チャットコンプリーションクライアントを使用します。
from databricks.sdk import WorkspaceClient
messages = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>"
client = WorkspaceClient().serving_endpoints.get_open_ai_client()
response = client.chat.completions.create(model=endpoint, messages=messages)
print(response)
どちらのクライアントでも、extra_bodyパラメーターを介してcustom_inputsまたはdatabricks_optionsを渡します。たとえば、extra_body={"databricks_options": {"return_trace": True}}は応答とともにトレースを返します。
ResponsesAgent インターフェイスを使用するエージェントの場合は、モデルとしてエンドポイント名を指定して /serving-endpoints/responses にリクエストを送信します。
curl --request POST \
--url https://<workspace-url>/serving-endpoints/responses \
--header 'Authorization: Bearer <token>' \
--header 'content-type: application/json' \
--data '{
"model": "<agent-endpoint-name>",
"input": [{ "role": "user", "content": "hi" }],
"stream": true
}'
ChatAgentまたはChatModelインターフェースを使用するエージェントの場合は、inputではなくmessagesリストを指定して/serving-endpoints/chat/completionsにリクエストを送信します。custom_inputsまたはdatabricks_optionsを渡すには、リクエスト本文に追加します。Endpointの/serving-endpoints/<agent-endpoint-name>/invocations URLにリクエストを送信することもできます。Endpointの背後にある個々のモデルをクエリーするを参照してください。
コードを記述せずに Model Serving上のエージェントとチャットするには、AI Playgroundを開き、エージェントのサービングエンドポイントを選択します。AI Playground からエージェントにcustom_inputsを渡す方法については、AI Playground およびレビュー アプリでのcustom_inputsの提供を参照してください。
ai_queryを使用して、SQLからModel Serving上のエージェントをクエリーします。構文とパラメーターについては、ai_query関数を参照してください。
SELECT ai_query(
"<agent-endpoint-name>", question
) FROM (VALUES ('what is MLflow?'), ('how does MLflow work?')) AS t(question);
その他のリソース
- エージェントサーバー
- エージェントランタイム
- 本番運用モニタリングをセットアップする
- 基盤モデルと埋め込みモデルのクエリー:エージェントを使用する代わりに、基盤モデルその他のモデルに直接クエリーを実行します。