查询已部署在 Azure Databricks 上的代理

你如何查询代理取决于为其提供服务的代理服务器。 请在下表中找到您的代理,然后按照相应部分操作。 想了解代理服务器,请参见 代理服务器。

你的智能体 托管于 如何查询
使用 DurableAgentServer Databricks 应用上的 Agent Runtime 位于 /api/invocations 的调用 API
使用 MLflow AgentServer 或 LongRunningAgentServer (遗留) Databricks 应用 Databricks OpenAI 客户端或位于 /responses 的 OpenAI Responses API
部署到模型服务 (遗留) 模型服务终结点 Databricks OpenAI 客户端、REST API ai_query或 AI Playground

托管在 Databricks 应用上的代理需要 Databricks OAuth 令牌。 个人访问令牌对Databricks应用不起作用。 要从脚本、服务主体、其他应用或笔记本生成 OAuth 令牌,请参阅使用令牌身份验证连接到 API Databricks 应用。

查询一个使用DurableAgentServer的代理

使用 DurableAgentServer 的智能体提供调用 API。 你用 Agent Bricks CLI 创建的代理使用 DurableAgentServer,并由 agentbricks deploy 将其部署到 agent-bricks-<name>,应用名为 。 每个向 API 的请求都会启动你的代理的一次运行,称为调用。

终结点 Description
POST /api/invocations 开始调用。 默认情况下,请求会等待并返回结果。 将 stream 设置为在事件发生时接收事件,或将 background 设置为立即返回。
GET /api/invocations/<id> 返回调用状态,完成后返回输出。
GET /api/invocations/<id>/events?after=<event-id> 流式传输在 <event-id> 之后发生的已存储事件。 使用该端点重新连接流。

请求主体

请求 POST /api/invocations 体接受以下字段。 服务器会拒绝包含其他字段的请求。

领域 Description
id Required. 一个你为每次调用生成的UUID。 服务器将该ID视为幂等密钥:使用相同的ID重新发送同一请求会返回已有的调用,而不是重新运行代理。 为不同请求重复使用ID会返回 409 错误。
session_id 该调用所属的对话。 共享会话ID的调用一次按顺序执行。 由CLI模板生成的代理需要该字段。
input 你的代理输入内容。 从 CLI 模板生成的智能体接受消息列表,或接受一个带有 messages 列表的对象。
stream 设置为 true,以接收作为服务器发送事件 (SSE) 的事件。
background 将其设置为 true 后,会立即返回包含状态 URL 的 202 响应,然后轮询结果。

你的代理的处理器定义了 input 的结构。 当 input 是对象时,由 CLI 模板生成的代理读取以下字段:

领域 Description
messages 要发送给智能体的对话轮次。
actor 智能体读取和写入其长期记忆所对应的标识。 如果你没有传入 actor,代理会使用会话 ID,因此记忆不会带到新的会话中。 将 actor 设置为来自你的应用中已登录用户的值,而不是用户输入的文本。
model 用于调用的模型,而不是代理代码中设定的模型。
resume 对暂停等待人工输入(如工具调用批准)的代理响应。 当代理暂停时,调用的 status 为 interrupted。 在新的调用中发送 resume,并使用相同的 session_id 以继续。

要让智能体跨会话回忆它了解到的用户相关信息,可以将用户 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

要从终端测试已部署的代理,请使用 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。

REST API

  1. 获取应用的网址。 输出中的 URL 字段是调用 API 的基础 URL。

    agentbricks --profile <profile> deployments get agent-bricks-<name>
    
  2. 为你的配置文件获取 OAuth 令牌。 输出在 access_token 字段中包含该令牌。

    databricks auth token --profile <profile>
    
  3. 发送请求:

    curl --request POST \
      --url <app-url>/api/invocations \
      --header 'Authorization: Bearer <OAuth token>' \
      --header 'content-type: application/json' \
      --data '{
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "session_id": "support-case-123",
        "input": [{ "role": "user", "content": "What does Databricks do?" }]
      }'
    

响应包含调用 id、其 status以及一个 output 字段,其值为代理返回的值。 服务器不需要输出模式:你的处理器可以返回任何可序列化的 JSON 值。 由CLI模板生成的代理返回包含以下字段的对象:

  • output:代理人在此次调用中产生的信息。
  • status:completed,或者,如果代理暂停等待人类输入,则为 interrupted。

Python

以下示例使用 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"])

要继续对话,发送下一条消息,并发送相同的 session_id 内容和新的 id。

流式传输、后台运行与重新连接

  • 流:设置 "stream": true。 响应是包含 run.started 和 ( run.completed 或 run.failed)事件的 SSE 流,以及你的代理发出的事件,比如 delta 带有流式文本的事件。 每个事件都有一个ID。
  • 在背景运行:设置"background": true。 服务器返回一个带有 status_url 的 202 响应。 轮询 GET /api/invocations/<id> 直到状态为 completed。 如果你也设置了 "stream": true,响应中会包含一个 events_url,你可以从中读取事件。
  • 重新连接:如果流断开,请使用你收到的最后一个事件的 ID 调用 GET /api/invocations/<id>/events?after=<event-id>。

以下 Python 示例以流式方式返回响应:

with requests.post(
    f"{app_url}/api/invocations",
    headers=w.config.authenticate(),
    json={
        "id": str(uuid.uuid4()),
        "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("data: "):
            print(line[len("data: "):])

如果你部署代理时有多个实例,请在 X-Routing-Key 标头中发送会话 ID,将会话中的所有请求路由到同一个实例。

查询使用遗留MLflow的代理 AgentServer

对于你使用旧版智能体服务器部署到 Databricks 应用上的智能体,请参考本节: MLflow AgentServer 或 LongRunningAgentServer,使用 ResponsesAgent 接口。 这些智能体在 /responses 处提供 OpenAI 响应 API。

LongRunningAgentServer 服务于相同的API,因此以下示例同样适用于它。 它还支持后台运行:在请求中将 background 设置为 true,然后用 GET /responses/<response-id>?stream=true&starting_after=<sequence-number> 检索响应,从而流式传输该序列号之后的事件。

Databricks OpenAI 客户端

Databricks 推荐这些代理使用 Databricks OpenAI 客户端 。 在型号名称中包含 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)

REST API

向应用 URL 的 /responses 路径发送请求。 请求体遵循OpenAI响应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 字段中包含 trace ID。 对于流请求,跟踪 ID 作为单独的 SSE 事件(data: {"trace_id": "tr-..."})出现在流的末端附近。

在模型服务上查询旧版智能体

使用此部分用于 部署到模型服务端点的遗留代理。 你可以用Databricks OAuth令牌或个人访问令牌进行认证。 要将这些代理迁移到Databricks Apps,请参见“ 将代理从模型服务迁移到Databricks Apps”。

Databricks OpenAI 客户端

对于使用 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}} 会返回包含响应的 trace。

REST API

对于使用 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 接口的智能体,请向 /serving-endpoints/chat/completions 发送一个带有 messages 列表的请求,而不是 input。 要通过 custom_inputs 或 databricks_options,将它们添加到请求正文中。 你也可以向端点 /serving-endpoints/<agent-endpoint-name>/invocations 的 URL 发送请求。 参见 “查询端点背后的单个模型”。

AI 操场

要在 Model Serving 上与代理聊天而无需编写代码,打开 AI Playground ,选择代理的服务端点。 要将 custom_inputs 从 AI 操场传递给智能体,请参阅在 AI 操场和审阅应用中提供 custom_inputs。

使用 SQL 与

使用 ai_query 从 SQL 查询模型服务上的智能体。 关于语法和参数,请参见 ai_query 函数 。

SELECT ai_query(
  "<agent-endpoint-name>", question
) FROM (VALUES ('what is MLflow?'), ('how does MLflow work?')) AS t(question);

其他资源