query agents implantado on Databricks
A forma como você faz query em um agente depende do servidor de agente que o serve. Encontre seu agente na tabela a seguir e siga a seção correspondente. Para saber mais sobre servidores de agentes, consulte Servidor de agente.
Seu agente | Hospedado no | Como query |
|---|---|---|
Agent Runtime no Databricks Apps | API de invocação em | |
Databricks Apps | Databricks OpenAI client or the OpenAI Responses API at | |
Implantado no Model Serving (legado) | Modelo de ponto de extremidade de serviço | Cliente OpenAI, API REST, |
Os agentes hospedados em Databricks Apps exigem um token OAuth do Databricks. Tokens de acesso pessoal não funcionam para o Databricks Apps. Para gerar tokens OAuth a partir de um script, de um service principal, de outro aplicativo ou de um notebook, consulte Connect to an API Databricks app using token authentication.
Query um agente que usa DurableAgentServer
Agents that use DurableAgentServer serve the invocation API. Agents that you create with the Agent Bricks CLI use DurableAgentServer, and agentbricks deploy deploys them to Agent Runtime as an app named agent-bricks-<name>. Each request to the API começar one execução of your agent, called an invocation.
Endpoint | Descrição |
|---|---|
| Começar uma invocação. Por default, a solicitação aguarda e retorna o resultado. Defina |
| Retorna o status de uma invocação e, após a conclusão, sua saída. |
| Faz a transmissão dos eventos armazenados que vêm após |
Corpo da solicitação
O corpo da solicitação para POST /api/invocations aceita os seguintes campos. O servidor rejeita solicitações que contenham outros campos.
campo | Descrição |
|---|---|
| Obrigatório. Um UUID gerado por você para cada invocação. O servidor trata o ID como uma key de idempotência: reenviar a mesma solicitação com o mesmo ID retorna a invocação existente em vez de executar o agente novamente. Reutilizar um ID para uma solicitação diferente retorna um erro |
| A conversa à qual a invocação pertence. Invocações que compartilham um ID de sessão são executadas uma de cada vez, em ordem. Agentes gerados a partir dos padrões da CLI exigem este campo. |
| A entrada para o seu agente. Agentes gerados a partir dos padrões da CLI aceitam uma lista de mensagens ou um objeto com uma lista |
| Definido como |
| Set to |
O manipulador do seu agente define a estrutura de input. Os agentes gerados a partir dos padrões da CLI leem os seguintes campos quando input é um objeto:
campo | Descrição |
|---|---|
| Os turnos de conversa a serem enviados ao agente. |
| The identity whose long-term memory the agent reads and writes. If you don't pass an |
| The model to use for this invocation, instead of the model set in the agent code. |
| A resposta a um agente que entrou em pausa para entrada humana, como a aprovação de uma chamada de ferramenta. Quando um agente está em pausa, o |
Para permitir que o agente se lembre do que aprendeu sobre um usuário entre as sessões, passe o ID do usuário como 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
Para testar um agente implantado a partir do seu terminal, use agentbricks endpoint invoke. O comando procura o aplicativo e se autentica com o seu perfil da CLI.
agentbricks --profile <profile> endpoint invoke agent-bricks-<name> \
--path /api/invocations \
--json "{\"id\":\"$(uuidgen)\",\"session_id\":\"$(uuidgen)\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"
To fazer a transmissão da response, add "stream":true to the JSON body and pass --sse. To test the agent while it execução locally with agentbricks dev, replace the app name with --url http://localhost:8000.
-
Obtenha o URL do aplicativo. O campo URL na saída é o URL base para a API de invocações.
Bashagentbricks --profile <profile> deployments get agent-bricks-<name> -
Obtenha um token OAuth para o seu perfil. A saída contém os tokens no campo
access_token. O comando a seguir o salva na variável de shellTOKEN:BashTOKEN=$(databricks auth token --profile <profile> | jq -r .access_token)Este comando requer um perfil que você criou com
databricks auth login. Para Service Principal ou scripts, consulte Conectar-se a um aplicativo Databricks de API usando autenticação por token ou use ow.config.authenticate()do SDK. -
Envie uma solicitação. O comando a seguir usa aspas duplas para que o shell expanda
$TOKENe gere uma nova chamadaidcomuuidgen: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?\" }]}"Use um novo
idpara cada solicitação. Se você reenviar umid, o servidor retornará o resultado armazenado dessa invocação. Se essa invocação falhar, o servidor retornará um erro500.
A resposta contém o id de invocação, seu status e um campo output com o valor que seu agente retorna. O servidor não requer um esquema de saída: seu manipulador pode retornar qualquer valor serializável em JSON.
Para agentes gerados a partir dos padrões da CLI, o output de nível superior é ele próprio um objeto. Sua própria lista output mantém as mensagens que o agente produziu nesta invocação, e pode incluir seu próprio status: completed, ou interrupted se o agente pausa para entrada humana. Por exemplo:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"output": {
"output": [{ "role": "assistant", "content": "Databricks is ..." }],
"session_id": "support-case-123",
"status": "completed"
}
}
O exemplo a seguir usa o Databricks SDK para procurar a URL do aplicativo e gerar tokens OAuth, e chama a API de invocações. O WorkspaceClient deve usar a autenticação 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"])
Para agentes gerados a partir de padrão CLI, as mensagens estão em output.output. Para imprimir o valor que qualquer agente retorna, use response.json()["output"].
Para continuar a conversa, envie a próxima mensagem com o mesmo session_id e um novo id.
Transmissão, execução em segundo plano e reconexão
- Transmissão : Definir
"stream": true. A resposta é uma transmissão SSE que inclui eventosrun.startederun.completed(ourun.failed), além dos eventos emitidos pelo seu agente, como eventosdeltacom texto transmitido. Cada evento tem uma linha SSEid:com um número de sequência, que você usa para reconectar. O payloaddata:pode conter seu próprio campoid, como um ID de execução de framework, que não é o ID de evento. - Execução em segundo plano : Defina
"background": true. O servidor retorna uma resposta202, como{"id": "...", "status": "queued", "status_url": "/api/invocations/<id>"}. Se você também definir"stream": true, a resposta inclui umevents_urldo qual você pode ler eventos. Os camposstatus_urleevents_urlsão caminhos relativos ao URL do aplicativo. PesquiseGET /api/invocations/<id>até que o status sejacompletedoufailed. - Reconectar : se uma transmissão desconectar, chame
GET /api/invocations/<id>/events?after=<event-id>com o ID do último evento recebido, comolast_event_idno exemplo a seguir.
Nos agentes gerados a partir de padrões da CLI, cada evento delta contém um pedaço de texto em content, e cada evento message contém uma mensagem completa em message, incluindo a mensagem final do assistente. Um evento message repete o texto dos eventos delta antes dele, então imprima um ou o outro, não ambos.
O seguinte exemplo de Python transmissão uma resposta, imprime o texto de eventos delta e rastreia o ID do último evento:
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
Se a transmissão for desconectada, leia os eventos restantes do último ID de evento:
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
O exemplo de Python a seguir faz uma execução de uma invocação em segundo plano e verifica a URL de status até que ela termine. Quando o status é failed, a resposta contém um campo error em vez de output.
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")))
Se você implantar o agente com mais de uma instância, envie o ID da sessão em um cabeçalho X-Routing-Key para direcionar todas as solicitações de uma sessão para a mesma instância.
Query um agente que usa o MLflow legado AgentServer
Use esta seção para agentes que você implanta no Databricks Apps com o servidor de agentes herdado: o MLflow AgentServer ou LongRunningAgentServer, com a interface ResponsesAgent. Esses agentes atendem à OpenAI Responses API em /responses.
LongRunningAgentServer serve a mesma API, portanto, os exemplos a seguir também se aplicam a ela. Ela também oferece suporte a execuções em segundo plano: defina background como true na solicitação e, em seguida, recupere a resposta com GET /responses/<response-id>?stream=true&starting_after=<sequence-number>, que faz a transmissão dos eventos após esse número de sequência.
- Databricks OpenAI client
- REST API
O Databricks recomenda o cliente Databricks OpenAI para esses agentes. Inclua o prefixo apps/ no nome do modelo.
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)
Para passar custom_inputs, use o parâmetro extra_body:
response = client.responses.create(
model=f"apps/{app_name}",
input=input_msgs,
extra_body={"custom_inputs": {"id": 5}},
)
Para obter o ID de rastreio de uma solicitação, inclua o cabeçalho x-mlflow-return-trace-id. Em seguida, use oget_tracedo MLflow para recuperar o rastreamento completo.
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)
Envie solicitações para o caminho /responses do URL do aplicativo. O corpo da solicitação segue a OpenAI Responses API, portanto, você pode usar qualquer cliente ou ferramenta HTTP que dê suporte a ela.
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
}'
Para passar custom_inputs, adicione-os ao corpo da solicitação:
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 }
}'
Para obter o ID de rastreamento, inclua o cabeçalho x-mlflow-return-trace-id: true. O corpo da resposta inclui o ID de rastreamento em um campo metadata.trace_id. Para solicitações de transmissão, o ID de rastreamento chega como um evento SSE separado (data: {"trace_id": "tr-..."}) próximo ao final da transmissão.
query um agente legado no Model Serving
Use esta seção para agentes legados implantados em Endpoint do Model Serving. Você pode se autenticar com um token OAuth do Databricks ou um access token pessoal. Para mover esses agentes para o Databricks Apps, consulte Migrar um agente do Model Serving para o Databricks Apps.
- Databricks OpenAI client
- REST API
- AI Playground
- SQL with
Para agentes que usam a interface ResponsesAgent, chame responses.create com o nome do endpoint como o modelo:
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)
Para agentes que usam as interfaces legadas ChatAgent ou ChatModel, use o cliente de conclusões de chat:
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)
Com qualquer um dos clientes, passe custom_inputs ou databricks_options por meio do parâmetro extra_body. Por exemplo, extra_body={"databricks_options": {"return_trace": True}} retorna o rastreamento com a resposta.
Para agentes que usam a interface ResponsesAgent, envie uma solicitação para /serving-endpoints/responses com o nome do endpoint como o modelo:
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
}'
Para agentes que usam as interfaces ChatAgent ou ChatModel, envie uma solicitação para /serving-endpoints/chat/completions com uma lista messages em vez de input. Para passar custom_inputs ou databricks_options, adicione-os ao corpo da solicitação. Você também pode enviar solicitações para a URL /serving-endpoints/<agent-endpoint-name>/invocations do endpoint. Consulte query modelos individuais por trás de um endpoint.
To chat with an agent on Model Serving without writing code, open AI Playground and select the agent's serving endpoint. To pass custom_inputs to the agent from AI Playground, see Provide custom_inputs in the AI Playground and review app.
Use ai_query para query um agente em Model Serving a partir de SQL. Consulte funçãoai_query para ver a sintaxe e os parâmetros.
SELECT ai_query(
"<agent-endpoint-name>", question
) FROM (VALUES ('what is MLflow?'), ('how does MLflow work?')) AS t(question);
Outros recursos
- Servidor do agente
- Agent Runtime
- Set up production monitoramento
- Query foundation and embedding models: Query foundation models and other models directly, instead of an agent.