Frågeagenter som distribuerats på Azure Databricks

Hur du gör en fråga mot en agent beror på vilken agentserver som tillhandahåller den. Hitta din mäklare i tabellen nedan och följ sedan motsvarande avsnitt. För att lära dig om agentservrar, se Agent Server.

Agenter som hostas på Databricks Apps kräver en Databricks OAuth-token. Personliga åtkomsttokens fungerar inte för Databricks appar. För att generera OAuth-tokens från ett skript, en tjänsteprincipal, en annan app eller en notebook, se Ansluta till en Databricks-app för API med tokenautentisering.

Fråga en agent som använder DurableAgentServer

Agenter som använder DurableAgentServer betjänar anrops-API:et. Agenter som du skapar med Agent Bricks CLI använder DurableAgentServer, och agentbricks deploy distribuerar dem till Agent Runtime som en app med namnet agent-bricks-<name>. Varje förfrågan till API:et startar en körning av din agent, som kallas ett anrop.

Begär brödtext

Begäranarkroppen för POST /api/invocations accepterar följande fält. Servern avvisar förfrågningar som innehåller andra fält.

Din agents hanterare definierar strukturen för input. Agenter som genereras från CLI-mallarna läser följande fält när input är ett objekt:

För att låta agenten minnas vad den lärt sig om en användare över sessioner, skicka användarens ID som 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 tegelstenar

För att testa en utplacerad agent från din terminal, använd agentbricks endpoint invoke. Kommandot söker upp appen och autentiserar med din CLI-profil.

agentbricks --profile <profile> endpoint invoke agent-bricks-<name> \
  --path /api/invocations \
  --json "{\"id\":\"$(uuidgen)\",\"session_id\":\"$(uuidgen)\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"

För att streama svaret, lägg till "stream":true i JSON-kroppen och skicka med --sse. För att testa agenten medan den körs lokalt med agentbricks dev, ersätt appnamnet med --url http://localhost:8000.

REST API

1. Hämta appens URL. URL-fältet i utdatan är bas-URL:en för anrops-API:et.

   agentbricks --profile <profile> deployments get agent-bricks-<name>
   

2. Skaffa en OAuth-token för din profil. Utdata innehåller tokenen i access_token fältet.

   databricks auth token --profile <profile>
   

3. Skicka en begäran:

   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?" }]
     }'
   

Svaret innehåller anropet id, dess status, och ett output fält med det värde som din agent returnerar. Servern kräver inget utdataschema: din hanterare kan returnera vilket JSON-serialiserbart värde som helst. Agenter som genereras från CLI-mallarna returnerar ett objekt med följande fält:

• output: de meddelanden som agenten producerade i detta anrop.
• status: completed, eller interrupted om agenten pausade för mänsklig input.

Python

Följande exempel använder Databricks SDK för att slå upp appens URL och generera en OAuth-token, och anropar sedan anrops-API:et. Den WorkspaceClient måste använda OAuth-autentisering.

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"])

För att fortsätta samtalet, skicka nästa meddelande med samma session_id och ett nytt id.

Streama, kör i bakgrunden och återanslut

• Stream: Ange "stream": true. Svaret är en SSE-ström som inkluderar run.started och run.completed (eller run.failed) händelser, plus de händelser din agent sänder ut, såsom delta händelser med strömmad text. Varje event har ett ID.
• Kör i bakgrunden: Ställ in "background": true. Servern returnerar ett 202 svar med ett status_url. Kontrollera GET /api/invocations/<id> upprepade gånger tills statusen är completed. Om du också sätter "stream": true, innehåller svaret en events_url som du kan läsa händelser från.
• Återanslut: Om en stream bryts, anropa GET /api/invocations/<id>/events?after=<event-id> med ID:t för den senaste händelsen du fick.

Följande Python-exempel strömmar ett svar:

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: "):])

Om du distribuerar agenten med mer än en instans, skicka sessions-ID:t i en X-Routing-Key header för att routa alla förfrågningar i en session till samma instans.

Fråga en agent som använder det äldre MLflowet AgentServer

Använd denna sektion för agenter som du distribuerar på Databricks Apps med den äldre agentservern: MLflow AgentServer eller LongRunningAgentServer, med gränssnittet ResponsesAgent . Dessa agenter betjänar OpenAI Responses API på /responses.

LongRunningAgentServer använder samma API, så följande exempel gäller också för det. Den stöder också bakgrundskörningar: ställ background in till true i förfrågan och hämta sedan svaret med GET /responses/<response-id>?stream=true&starting_after=<sequence-number>, vilket strömmar händelserna efter det sekvensnumret.

Databricks OpenAI-klient

Databricks rekommenderar Databricks OpenAI-klient för dessa agenter. Inkludera prefixet apps/ i modellnamnet.

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)

För att skicka custom_inputs, använd parametern extra_body:

response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    extra_body={"custom_inputs": {"id": 5}},
)

För att få spårnings-ID för en begäran, inkludera x-mlflow-return-trace-id headern. Använd sedan MLflow get_trace för att hämta den fullständiga spårningen.

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

Skicka förfrågningar till sökvägen i appens URL /responses. Förfrågningskroppen följer OpenAI Responses API, så du kan använda vilken HTTP-klient eller verktyg som helst som stödjer det.

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
  }'

För att klara custom_inputs, lägg till dem i begärandetexten:

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 }
  }'

För att få spårnings-ID:t, inkludera x-mlflow-return-trace-id: true headern. Svarsinnehållet innehåller spår-ID:t i ett metadata.trace_id-fält. För strömningsförfrågningar anländer spårnings-ID:t som en separat SSE-händelse (data: {"trace_id": "tr-..."}) nära slutet av strömmen.

Fråga en legacy-agent på Model Serving

Använd denna sektion för äldre agenter distribuerade till Model Serving-endpoints. Du kan autentisera dig med en Databricks OAuth-token eller en personlig åtkomsttoken. För att flytta dessa agenter till Databricks Apps, se Migrera en agent från Model Serving till Databricks Apps.

Databricks OpenAI-klient

För agenter som använder gränssnittet ResponsesAgent , anropa responses.create med endpoint-namnet som modell:

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)

För agenter som använder legacy ChatAgent eller ChatModel gränssnitt, använd chat completions-klienten:

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)

Med någon av klienterna, skicka custom_inputs eller databricks_options genom parametern extra_body. Till exempel returnerar extra_body={"databricks_options": {"return_trace": True}} trace med svaret.

REST API

För agenter som använder gränssnittet ResponsesAgent, skicka en förfrågan till /serving-endpoints/responses med endpointnamn som modell:

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
  }'

För agenter som använder ChatModel- eller /serving-endpoints/chat/completions-gränssnitten, skicka en förfrågan till messages med en input-lista istället för ChatAgent. För att skicka med custom_inputs eller databricks_options, lägg till dem i begärandetexten. Du kan också skicka förfrågningar till endpointens /serving-endpoints/<agent-endpoint-name>/invocations URL. Se Fråga efter individuella modeller bakom en endpoint.

AI-lekplatsen

För att chatta med en agent på Model Serving utan att skriva kod, öppna AI Playground och välj agentens serveringsslutpunkt. För att skicka custom_inputs till agenten från AI Playground, se Tillhandahåll custom_inputs i AI Playground och appen Granska.

SQL med

Använd ai_query för att fråga en agent i Model Serving från SQL. Se ai_query funktion för syntax och parametrar.

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

Ytterligare resurser

• Agent Server
• Agent Runtime
• Sätt upp produktionsövervakning
• Fråga grundmodeller och embedding-modeller: Fråga grundmodeller och andra modeller direkt, istället för en agent.