你如何查询代理取决于为其提供服务的代理服务器。 请在下表中找到您的代理,然后按照相应部分操作。 想了解代理服务器,请参见 代理服务器。
| 你的智能体 | 托管于 | 如何查询 |
|---|---|---|
使用 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
获取应用的网址。 输出中的 URL 字段是调用 API 的基础 URL。
agentbricks --profile <profile> deployments get agent-bricks-<name>为你的配置文件获取 OAuth 令牌。 输出在
access_token字段中包含该令牌。databricks auth token --profile <profile>发送请求:
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);
其他资源
- 代理服务器
- 代理运行时
- 建立生产监控
- 查询基础模型和嵌入模型:直接查询基础模型和其他模型,而不是智能体。