Pular para o conteúdo principal

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

Usos DurableAgentServer

Agent Runtime no Databricks Apps

API de invocação em /api/invocations

Usa o MLflow AgentServer ou LongRunningAgentServer (legado)

Databricks Apps

Databricks OpenAI client or the OpenAI Responses API at /responses

Implantado no Model Serving (legado)

Modelo de ponto de extremidade de serviço

Cliente OpenAI, API REST, ai_query ou AI Playground do Databricks

Seu agente

Hospedado no

Como query

Usos DurableAgentServer

Agent Runtime no Databricks Apps

API de invocação em /api/invocations

Usa o MLflow AgentServer ou LongRunningAgentServer (legado)

Databricks Apps

Databricks OpenAI client or the OpenAI Responses API at /responses

Implantado no Model Serving (legado)

Modelo de ponto de extremidade de serviço

Cliente OpenAI, API REST, ai_query ou AI Playground do Databricks

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

POST /api/invocations

Começar uma invocação. Por default, a solicitação aguarda e retorna o resultado. Defina stream para receber eventos conforme eles acontecem, ou background para retornar imediatamente.

GET /api/invocations/<id>

Retorna o status de uma invocação e, após a conclusão, sua saída.

GET /api/invocations/<id>/events?after=<event-id>

Faz a transmissão dos eventos armazenados que vêm após <event-id>. Use este endpoint para se reconectar a uma transmissão.

Endpoint

Descrição

POST /api/invocations

Começar uma invocação. Por default, a solicitação aguarda e retorna o resultado. Defina stream para receber eventos conforme eles acontecem, ou background para retornar imediatamente.

GET /api/invocations/<id>

Retorna o status de uma invocação e, após a conclusão, sua saída.

GET /api/invocations/<id>/events?after=<event-id>

Faz a transmissão dos eventos armazenados que vêm após <event-id>. Use este endpoint para se reconectar a uma transmissão.

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

id

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 409.

session_id

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.

input

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 messages.

stream

Definido como true para receber eventos como eventos enviados pelo servidor (SSE).

background

Set to true to return a 202 response immediately with a status URL, and then poll for the result.

campo

Descrição

id

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 409.

session_id

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.

input

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 messages.

stream

Definido como true para receber eventos como eventos enviados pelo servidor (SSE).

background

Set to true to return a 202 response immediately with a status URL, and then poll for the result.

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

messages

Os turnos de conversa a serem enviados ao agente.

actor

The identity whose long-term memory the agent reads and writes. If you don't pass an actor, the agent uses the session ID, so memories don't carry over to a new session. Set actor from your application's signed-in user, not from text that the user types.

model

The model to use for this invocation, instead of the model set in the agent code.

resume

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 status da invocação é interrupted. Envie resume em uma nova invocação com o mesmo session_id para continuar.

campo

Descrição

messages

Os turnos de conversa a serem enviados ao agente.

actor

The identity whose long-term memory the agent reads and writes. If you don't pass an actor, the agent uses the session ID, so memories don't carry over to a new session. Set actor from your application's signed-in user, not from text that the user types.

model

The model to use for this invocation, instead of the model set in the agent code.

resume

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 status da invocação é interrupted. Envie resume em uma nova invocação com o mesmo session_id para continuar.

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:

JSON
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "support-case-123",
"input": {
"messages": [{ "role": "user", "content": "What does Databricks do?" }],
"actor": "user-42"
}
}

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.

Bash
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.

Transmissão, execução em segundo plano e reconexão​

  • Transmissão : Definir "stream": true. A resposta é uma transmissão SSE que inclui eventos run.started e run.completed (ou run.failed), além dos eventos emitidos pelo seu agente, como eventos delta com texto transmitido. Cada evento tem uma linha SSE id: com um número de sequência, que você usa para reconectar. O payload data: pode conter seu próprio campo id, 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 resposta 202, como {"id": "...", "status": "queued", "status_url": "/api/invocations/<id>"}. Se você também definir "stream": true, a resposta inclui um events_url do qual você pode ler eventos. Os campos status_url e events_url são caminhos relativos ao URL do aplicativo. Pesquise GET /api/invocations/<id> até que o status seja completed ou failed.
  • Reconectar : se uma transmissão desconectar, chame GET /api/invocations/<id>/events?after=<event-id> com o ID do último evento recebido, como last_event_id no 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:

Python
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:

Python
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.

Python
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.

O Databricks recomenda o cliente Databricks OpenAI para esses agentes. Inclua o prefixo apps/ no nome do modelo.

Python
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:

Python
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.

Python
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)

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.

Para agentes que usam a interface ResponsesAgent, chame responses.create com o nome do endpoint como o modelo:

Python
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:

Python
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.

Outros recursos​